S3-yhteensopivuus

Käytä AWS SDK:ta tiedostojen lataamiseen, hakemiseen ja hallintaan IPFS Ninja -palvelussa samalla koodilla, jota käytät Amazon S3:n kanssa.

Endpoint

https://s3.ipfs.ninja

Tunnistetiedot

S3 API käyttää IPFS Ninja -API-avaintasi todennukseen. API-avaimesi toimii sekä access key- että secret key -avaimena.

Tunnistetietojen hankkiminen

Siirry kohtaan Hallintapaneeli > API-avaimet
Napsauta Create API key ja anna sille nimi (esim. "S3-yhteys")
Kopioi koko avain heti — se näytetään vain kerran, eikä sitä voi hakea myöhemmin

Avaimesi näyttää tältä:

bws_628bba35e9e0079d9ff9c392b1b55a7b
├──────────┘└──────────────────────────┘
 prefix (12 chars)    rest of key

Yhdistäminen AWS-tunnistetietoihin

AWS-parametri	Arvo	Esimerkki
`accessKeyId`	API-avaimesi 12 ensimmäistä merkkiä	`bws_628bba35`
`secretAccessKey`	Koko API-avain (kaikki 36 merkkiä)	`bws_628bba35e9e0079d9ff9c392b1b55a7b`
`region`	Aina `us-east-1`	`us-east-1`

WARNING

Koko API-avain näytetään vain kerran, kun luot sen. Jos kadotat sen, poista avain ja luo uusi API-avaimet-sivulla.

Pikaopas

javascript

import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: {
    accessKeyId: "bws_628bba35",
    secretAccessKey: "bws_628bba35e9e0079d9ff9c392b1b55a7b"
  },
  region: "us-east-1",
  forcePathStyle: true
});

// Upload a file
const put = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "hello.json",
  Body: JSON.stringify({ hello: "IPFS" }),
  ContentType: "application/json"
}));

console.log("CID:", put.Metadata?.cid);
// CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Bucket = Kansiot

S3-buckettisi vastaavat IPFS Ninja -kansioitasi. Kun lataat tiedoston buckettiin, se tallennetaan vastaavaan kansioon. Kun listaat bucketin objekteja, näet kyseisen kansion tiedostot.

S3-operaatio	IPFS Ninja -vastine
`CreateBucket`	Luo uusi kansio
`ListBuckets`	Listaa kansiosi
`DeleteBucket`	Poista kansio ja kaikki sen tiedostot
`PutObject` buckettiin	Lataa tiedosto kansioon
`ListObjectsV2` bucketissa	Listaa kansion tiedostot

javascript

import { ListBucketsCommand, CreateBucketCommand, PutObjectCommand } from "@aws-sdk/client-s3";

// Create a bucket (= create a folder)
await s3.send(new CreateBucketCommand({ Bucket: "nft-metadata" }));

// Upload a file into the folder
await s3.send(new PutObjectCommand({
  Bucket: "nft-metadata",      // ← folder name
  Key: "token-42.json",        // ← filename within the folder
  Body: JSON.stringify({ name: "My NFT #42" })
}));

// List buckets (= list your folders)
const { Buckets } = await s3.send(new ListBucketsCommand({}));
console.log(Buckets);
// [{ Name: "nft-metadata", CreationDate: "2026-04-13T..." }]

TIP

S3 API:n kautta luodut kansiot ovat samoja kansioita, jotka näkyvät Hallintapaneelissasi. Voit järjestää tiedostoja S3 API:n, REST API:n tai web-käyttöliittymän kautta — ne kaikki jakavat saman kansiojärjestelmän.

INFO

Toisin kuin Amazon S3:ssa, IPFS Ninja -kansiot ovat oletuksena tasarakenteisia. Luodaksesi sisäkkäisrakenteita, käytä REST API:n kansiopäätepisteitä parentFolderId-parametrilla. S3 API:sta voit käyttää avainprefiksejä (esim. images/photo.png) järjestelyyn kansion sisällä.

Bucket-nimet ovat maailmanlaajuisesti yksilöllisiä

Bucket-nimet elävät globaalissa nimiavaruudessa kaikkien asiakkaiden kesken, AWS S3:n semantiikkaa vastaten. Tämä tarkoittaa:

Ensimmäinen käyttäjä, joka luo bucketin tietyllä nimellä, varaa kyseisen nimen globaalisti.
Myöhemmät CreateBucket-kutsut samalla nimellä miltä tahansa tililtä palauttavat BucketAlreadyExists (409).
Jos yrität luoda oman bucketisi uudelleen, saat BucketAlreadyOwnedByYou (409).
Kansiosi nimi hallintapaneelissa on tilikohtainen ja voi silti olla mikä tahansa — vain S3:ssa näkyvä bucket-nimi kulkee globaalin nimiavaruuden kautta.

Jos haluamasi nimi on varattu, valitse eri tavalla rajattu nimi (myapp-photos-2026, acme-nft-metadata) — sama käytäntö kuin Amazon S3:ssa.

Tuetut operaatiot

PutObject

Lataa tiedosto IPFS:ään. Tiedosto kiinnitetään, turvatarkastetaan ja CID palautetaan ETag- ja x-amz-meta-cid-otsakkeissa.

Tuodaksesi CAR-tiedoston tavallisen tiedoston sijaan, lisää x-amz-meta-import: car -metatietootsake. Katso CAR-tuonti lisätiedoille.

javascript

import { PutObjectCommand } from "@aws-sdk/client-s3";
import fs from "fs";

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "photo.png",
  Body: fs.readFileSync("photo.png"),
  ContentType: "image/png"
}));

console.log("CID:", result.ETag);

bash

# curl equivalent
curl -X PUT "https://s3.ipfs.ninja/my-project/photo.png" \
  --data-binary @photo.png \
  -H "Content-Type: image/png" \
  --aws-sigv4 "aws:amz:us-east-1:s3" \
  --user "bws_628bba35:bws_628bba35e9e0079d9ff9c392b1b55a7b"

GetObject

Lataa tiedosto sen avaimen (tiedostonimen) tai CID:n perusteella.

javascript

import { GetObjectCommand } from "@aws-sdk/client-s3";

const result = await s3.send(new GetObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

const body = await result.Body.transformToByteArray();
console.log("Size:", body.length);
console.log("CID:", result.Metadata?.cid);

HeadObject

Hae tiedoston metatiedot lataamatta sisältöä.

javascript

import { HeadObjectCommand } from "@aws-sdk/client-s3";

const head = await s3.send(new HeadObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

console.log("Size:", head.ContentLength);
console.log("Type:", head.ContentType);
console.log("CID:", head.Metadata?.cid);

DeleteObject

Irrota tiedoston kiinnitys IPFS:stä ja poista se tililtäsi.

javascript

import { DeleteObjectCommand } from "@aws-sdk/client-s3";

await s3.send(new DeleteObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

ListObjectsV2

Listaa bucketin tiedostot valinnaisella prefiksisuodatuksella ja sivutuksella.

javascript

import { ListObjectsV2Command } from "@aws-sdk/client-s3";

const list = await s3.send(new ListObjectsV2Command({
  Bucket: "my-project",
  Prefix: "images/",
  MaxKeys: 100
}));

for (const obj of list.Contents ?? []) {
  console.log(obj.Key, obj.Size, obj.ETag); // ETag = CID
}

Multipart Upload

Lataa suuria tiedostoja (jopa 5 Gt) käyttäen monivaiheista latausta. AWS SDK hoitaa tämän automaattisesti:

javascript

import { Upload } from "@aws-sdk/lib-storage";
import fs from "fs";

const upload = new Upload({
  client: s3,
  params: {
    Bucket: "my-project",
    Key: "large-dataset.tar.gz",
    Body: fs.createReadStream("large-dataset.tar.gz"),
    ContentType: "application/gzip"
  },
  partSize: 10 * 1024 * 1024, // 10 MB per part
});

upload.on("httpUploadProgress", (progress) => {
  console.log(`Uploaded ${progress.loaded} of ${progress.total} bytes`);
});

const result = await upload.done();
console.log("CID:", result.ETag);

Tai hallitse osia manuaalisesti:

javascript

import {
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand
} from "@aws-sdk/client-s3";

// 1. Start
const { UploadId } = await s3.send(new CreateMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin"
}));

// 2. Upload parts
const part1 = await s3.send(new UploadPartCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  PartNumber: 1,
  Body: chunk1
}));

// 3. Complete
const result = await s3.send(new CompleteMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  MultipartUpload: {
    Parts: [{ PartNumber: 1, ETag: part1.ETag }]
  }
}));

Python-esimerkki

python

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.ipfs.ninja",
    aws_access_key_id="bws_628bba35",
    aws_secret_access_key="bws_628bba35e9e0079d9ff9c392b1b55a7b",
    region_name="us-east-1"
)

# Upload
s3.put_object(
    Bucket="my-project",
    Key="data.json",
    Body=b'{"hello": "IPFS"}',
    ContentType="application/json"
)

# List files
response = s3.list_objects_v2(Bucket="my-project")
for obj in response.get("Contents", []):
    print(obj["Key"], obj["Size"])

# Download
result = s3.get_object(Bucket="my-project", Key="data.json")
print(result["Body"].read())

Go-esimerkki

package main

import (
    "context"
    "fmt"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    client := s3.New(s3.Options{
        BaseEndpoint: aws.String("https://s3.ipfs.ninja"),
        Region:       "us-east-1",
        Credentials:  credentials.NewStaticCredentialsProvider("bws_628bba35", "bws_628bba35e9e0...", ""),
        UsePathStyle: true,
    })

    _, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
        Bucket:      aws.String("my-project"),
        Key:         aws.String("hello.txt"),
        Body:        strings.NewReader("Hello, IPFS!"),
        ContentType: aws.String("text/plain"),
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Uploaded!")
}

Määritä CORS (selain-SDK-käyttö)

Jos kutsut S3 API:a suoraan selaimen JavaScriptistä (SPA, lompakkosovellus, hallintapaneelityökalu), sinun on määritettävä CORS bucketille ensin. Muuten selaimet estävät preflight-pyynnön ja lataukset epäonnistuvat virheeseen No 'Access-Control-Allow-Origin' header is present.

Sama rakenne kuin AWS S3:ssa — PutBucketCors / GetBucketCors / DeleteBucketCors-aliresurssit:

PutBucketCors

javascript

import { S3Client, PutBucketCorsCommand } from "@aws-sdk/client-s3";

await s3.send(new PutBucketCorsCommand({
  Bucket: "my-bucket",
  CORSConfiguration: {
    CORSRules: [{
      AllowedOrigins: ["http://localhost:3000", "https://myapp.com"],
      AllowedMethods: ["GET", "HEAD", "PUT", "POST", "DELETE"],
      AllowedHeaders: ["*"],
      ExposeHeaders: ["ETag", "x-amz-meta-cid", "x-amz-request-id"],
      MaxAgeSeconds: 3600,
    }],
  },
}));

GetBucketCors

javascript

import { GetBucketCorsCommand } from "@aws-sdk/client-s3";

const { CORSRules } = await s3.send(new GetBucketCorsCommand({ Bucket: "my-bucket" }));
console.log(CORSRules);

DeleteBucketCors

javascript

import { DeleteBucketCorsCommand } from "@aws-sdk/client-s3";

await s3.send(new DeleteBucketCorsCommand({ Bucket: "my-bucket" }));

Yläraja ja oletukset

Enintään 5 sääntöä per bucket (spesifikaatio sallii 100:aa, me rajoitamme 5:een pitääksemme selaimen preflight-vastauksen kompaktina).
Kokonaismääritys rajattu 64 KB:iin serialisoituna.
Jos CORS-määritystä ei ole asetettu, selaimen preflight-pyynnöt hylätään — vastaten AWS S3:n oletuskäytäntöä. Määritä eksplisiittiset säännöt niille alkuperille, joista todella palvelet.

Käytännön turvallisuushuomio

CORS on selainpuolen mukavuuskerros, ei turvallisuusraja. Jokainen S3 API -kutsu vaatii silti kelvollisen SigV4-allekirjoituksen, joka on laskettu API-avaimestasi — sallivakin CORS-määritys ei anna kenenkään käyttää buckettiasi ilman tätä tunnistetietoa. Mitä CORS estää: tahaton alkuperä (esim. vanhentunut kopio sovelluksestasi osoitteessa dev.myapp.com) lähettämästä allekirjoitettuja pyyntöjä selainkontekstista.

Hallintapaneelin vaihtoehto

Tiedostot-sivulla on S3 CORS -toiminto jokaisen kansion toimintovalikossa. Sama taustatallennus; jos et halua kirjoittaa PutBucketCors-koodia, määritä se siellä.

Erot Amazon S3:een verrattuna

Ominaisuus	Amazon S3	IPFS Ninja S3
Tallennusmalli	Muokattavat objektit	Sisältöosoitettu (muuttumattomat CID:t)
Päällekirjoituskäyttäytyminen	Korvaa objektin paikallaan	Luo uuden CID:n, vanha CID on edelleen saavutettavissa
Versiointi	Tuettu	Ei tuettu (käytä CID:itä versiointiin)
Palvelinpuolen salaus	Tuettu	Ei tuettu (sisältö on IPFS:ssä)
Elinkaarikäytännöt	Tuettu	Ei tuettu
Bucket-käytännöt / ACL:t	Tuettu	Käytä gatewayn käyttötiloja
Ennakkoallekirjoitetut URL:t	Tuettu	Käytä allekirjoitettuja lataustokeneita
Objektin enimmäiskoko	5 Tt	5 Gt (monivaiheinen), 100 Mt (yksittäinen PUT)
Alueet	Usean alueen	Vain `us-east-1`
`ETag`-arvo	MD5-tiiviste	IPFS CID
Lisäotsakkeet	Vakio S3	`x-amz-meta-cid` (IPFS CID)
CID-muoto	N/A	Nykyaikainen CIDv1 (`bafy…`) uusille latauksille; vanha `Qm…` pysyy kelvollisena syötteenä
Bucket-nimiavaruus	Globaali (koko AWS)	Globaali (kaikkien IPFS Ninja -tilien kesken) — sama semantiikka
CORS	`PutBucketCors` tuettu	`PutBucketCors` tuettu (5 säännön yläraja)

Siirtyminen Amazon S3:sta

Korvaa S3-asiakasohjelman määritykset:

diff

 const s3 = new S3Client({
+  endpoint: "https://s3.ipfs.ninja",
   credentials: {
-    accessKeyId: "AKIA...",
-    secretAccessKey: "wJalrX..."
+    accessKeyId: "bws_628bba35",
+    secretAccessKey: "bws_628bba35e9e0..."
   },
   region: "us-east-1",
+  forcePathStyle: true
 });

Olemassa olevat PutObject-, GetObject-, ListObjectsV2- ja DeleteObject-kutsusi toimivat sellaisenaan.

Siirtyminen Filebasesta

Korvaa endpoint-URL:

diff

 const s3 = new S3Client({
-  endpoint: "https://s3.filebase.com",
+  endpoint: "https://s3.ipfs.ninja",
   credentials: {
-    accessKeyId: "FILEBASE_KEY",
-    secretAccessKey: "FILEBASE_SECRET"
+    accessKeyId: "bws_628bba35",
+    secretAccessKey: "bws_628bba35e9e0..."
   },
   region: "us-east-1",
   forcePathStyle: true
 });

S3-yhteensopivuus ​

Endpoint ​

Tunnistetiedot ​

Tunnistetietojen hankkiminen ​

Yhdistäminen AWS-tunnistetietoihin ​

Pikaopas ​

Bucket = Kansiot ​

Bucket-nimet ovat maailmanlaajuisesti yksilöllisiä ​

Tuetut operaatiot ​

PutObject ​

GetObject ​

HeadObject ​

DeleteObject ​

ListObjectsV2 ​

Multipart Upload ​

Python-esimerkki ​

Go-esimerkki ​

Määritä CORS (selain-SDK-käyttö) ​

PutBucketCors ​

GetBucketCors ​

DeleteBucketCors ​

Yläraja ja oletukset ​

Käytännön turvallisuushuomio ​

Hallintapaneelin vaihtoehto ​

Erot Amazon S3:een verrattuna ​

Siirtyminen Amazon S3:sta ​

Siirtyminen Filebasesta ​

S3-yhteensopivuus

Endpoint

Tunnistetiedot

Tunnistetietojen hankkiminen

Yhdistäminen AWS-tunnistetietoihin

Pikaopas

Bucket = Kansiot

Bucket-nimet ovat maailmanlaajuisesti yksilöllisiä

Tuetut operaatiot

PutObject

GetObject

HeadObject

DeleteObject

ListObjectsV2

Multipart Upload

Python-esimerkki

Go-esimerkki

Määritä CORS (selain-SDK-käyttö)

PutBucketCors

GetBucketCors

DeleteBucketCors

Yläraja ja oletukset

Käytännön turvallisuushuomio

Hallintapaneelin vaihtoehto

Erot Amazon S3:een verrattuna

Siirtyminen Amazon S3:sta

Siirtyminen Filebasesta