S3 ühilduvus

Kasuta AWS SDK-d failide üleslaadimiseks, allalaadimiseks ja haldamiseks IPFS Ninja's — sama koodiga, mida kasutad Amazon S3 jaoks.

Endpoint

https://s3.ipfs.ninja

Volitused

S3 API kasutab autentimiseks sinu IPFS Ninja API-võtit. Sinu API-võti toimib nii access key kui ka secret key'na.

Kuidas volitusi saada

Mine Dashboard > API Keys
Kliki Create API key ja anna sellele nimi (nt „S3 ligipääs")
Kopeeri kogu võti kohe — seda näidatakse ainult üks kord ja hiljem ei saa seda enam taastada

Sinu võti näeb välja selline:

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

Vastendamine AWS volitustega

AWS parameeter	Väärtus	Näide
`accessKeyId`	Sinu API-võtme esimesed 12 tähemärki	`bws_628bba35`
`secretAccessKey`	Täielik API-võti (kõik 36 tähemärki)	`bws_628bba35e9e0079d9ff9c392b1b55a7b`
`region`	Alati `us-east-1`	`us-east-1`

WARNING

Täielikku API-võtit näidatakse ainult üks kord selle loomisel. Kui kaotad selle, kustuta võti ja loo uus API Keys lehelt.

Kiirstart

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

Buckets = Kaustad

S3 bucket'id vastavad sinu IPFS Ninja kaustadele. Kui laadid faili bucket'isse, salvestatakse see vastavasse kausta. Kui loetled bucket'i objekte, näed selle kausta faile.

S3 operatsioon	IPFS Ninja vaste
`CreateBucket`	Uue kausta loomine
`ListBuckets`	Sinu kaustade loetlemine
`DeleteBucket`	Kausta ja kõigi selle failide kustutamine
`PutObject` bucket'isse	Faili üleslaadimine kausta
`ListObjectsV2` bucket'il	Kausta failide loetlemine

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 kaudu loodud kaustad on samad kaustad, mis on nähtavad sinu Dashboard'is. Saad faile korraldada nii S3 API, REST API kui ka veebiliidese kaudu — kõik jagavad sama kaustasüsteemi.

INFO

Erinevalt Amazon S3-st on IPFS Ninja kaustad vaikimisi lamedad. Pesastatud struktuuride loomiseks kasuta REST API kausta endpoint'e parameetriga parentFolderId. S3 API kaudu kasuta võtmeprefikseid (nt images/photo.png) kausta siseseks korraldamiseks.

Bucket'i nimed on globaalselt unikaalsed

Bucket'ite nimed elavad globaalses nimeruumis kõigi klientide vahel, vastavalt AWS S3 semantikale. See tähendab:

Esimene kasutaja, kes loob bucket'i antud nimega, omastab selle nime globaalselt.
Hilisemad CreateBucket kutsed sama nimega mis tahes kontolt tagastavad BucketAlreadyExists (409).
Kui proovid oma bucket'it uuesti luua, saad BucketAlreadyOwnedByYou (409).
Sinu kausta nimi töölaual on konto-põhine ja võib olla ikka mis tahes — ainult S3-s nähtav bucket'i nimi läbib globaalset nimeruumi.

Kui soovitud nimi on juba võetud, vali erineva ulatusega nimi (myapp-photos-2026, acme-nft-metadata) — sama konventsioon, mida kasutaksid Amazon S3-l.

Toetatud operatsioonid

PutObject

Laadi fail IPFS-i üles. Fail kinnitatakse, turvaskannitakse ja CID tagastatakse päistes ETag ja x-amz-meta-cid.

CAR-faili importimiseks tavalise faili asemel lisa metaandmete päis x-amz-meta-import: car. Vaadake CAR Import üksikasjade saamiseks.

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

Laadi fail alla selle võtme (failinime) või CID järgi.

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

Hangi faili metaandmed ilma sisu allalaadimata.

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

Eemalda faili kinnitamine IPFS-ist ja kustuta see oma kontolt.

javascript

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

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

ListObjectsV2

Loetele bucket'i failid valikulise prefiksi filtreerimise ja lehekülgjaotusega.

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

Laadi üles suuri faile (kuni 5 GB) multipart upload'iga. AWS SDK teeb seda automaatselt:

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);

Või juhi osi käsitsi:

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 }]
  }
}));

Pythoni näide

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 näide

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!")
}

Konfigureeri CORS (brauseri SDK ligipääs)

Kui kutsud S3 API-t otse brauseri JavaScript-ist (SPA, wallet-rakendus, töölaua tööriist), pead esmalt bucket'ile CORS-i konfigureerima. Vastasel juhul blokeerivad brauserid preflight-päringu ja üleslaadimised ebaõnnestuvad veaga No 'Access-Control-Allow-Origin' header is present.

Sama kuju mis AWS S3-l — PutBucketCors / GetBucketCors / DeleteBucketCors alamressursid:

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" }));

Piirmäär ja vaikeväärtused

Kuni 5 reeglit bucket'i kohta (spetsifikatsioon lubab 100, meie piirame 5-le, et hoida brauseri preflight-vastus kompaktsena).
Kogu konfiguratsioon piiratud 64 KB-ni serialiseeritult.
Kui CORS-seadistust pole määratud, lükatakse brauseri preflight-päringud tagasi — vastavalt AWS S3 vaikekäitumisele. Konfigureeri selgesõnalised reeglid päritolude jaoks, millelt tegelikult teenindad.

Turvamärkus reaalses maailmas

CORS on brauseripoolne mugavuskiht, mitte turvapiir. Iga S3 API kutse nõuab ikkagi kehtivat SigV4-allkirja, mis on arvutatud sinu API-võtmest — leebe CORS-seadistus ei luba kellelgi sinu bucket'it ilma selle volituseta kasutada. Mida CORS aitab vältida: soovimatu päritolu (nt sinu rakenduse aegunud koopia domeenil dev.myapp.com) allkirjastatud päringute saatmist brauserikontekstist.

Töölaua alternatiiv

Failide lehel on igas kausta toimingumenüüs kirje S3 CORS. Sama aluseks olev salvestus; kui sa ei taha PutBucketCors koodi kirjutada, konfigureeri see seal.

Erinevused Amazon S3-st

Omadus	Amazon S3	IPFS Ninja S3
Salvestusmudel	Muudetavad objektid	Sisupõhine adresseerimine (muutumatud CID-d)
Ülekirjutamise käitumine	Asendab objekti koha peal	Loob uue CID, vana CID jääb kättesaadavaks
Versioonihaldus	Toetatud	Ei toetata (kasuta CID-e versioonimiseks)
Serveripoolne krüptimine	Toetatud	Ei toetata (sisu on IPFS-is)
Elutsükli reeglid	Toetatud	Ei toetata
Bucket'i reeglid / ACL-id	Toetatud	Kasuta gateway ligipääsureegleid
Eelallkirjastatud URL-id	Toetatud	Kasuta allkirjastatud üleslaadimise tokeneid
Maksimaalne objekti suurus	5 TB	5 GB (multipart), 100 MB (üksik PUT)
Regioonid	Mitu regiooni	Ainult `us-east-1`
`ETag` väärtus	MD5 räsi	IPFS CID
Lisapäised	Standardne S3	`x-amz-meta-cid` (IPFS CID)
CID formaat	Puudub	Kaasaegne CIDv1 (`bafy…`) uute üleslaadimiste jaoks; vanapärane `Qm…` jääb sisendina kehtivaks
Bucket'i nimeruum	Globaalne (üle kogu AWS-i)	Globaalne (üle kõigi IPFS Ninja kontode) — sama semantika
CORS	`PutBucketCors` toetatud	`PutBucketCors` toetatud (5-reegli piirmäär)

Migreerimine Amazon S3-st

Asenda oma S3 kliendi konfiguratsioon:

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
 });

Sinu olemasolevad PutObject, GetObject, ListObjectsV2 ja DeleteObject kutsed töötavad muutmata kujul edasi.

Migreerimine Filebase'ist

Asenda 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 ühilduvus ​

Endpoint ​

Volitused ​

Kuidas volitusi saada ​

Vastendamine AWS volitustega ​

Kiirstart ​

Buckets = Kaustad ​

Bucket'i nimed on globaalselt unikaalsed ​

Toetatud operatsioonid ​

PutObject ​

GetObject ​

HeadObject ​

DeleteObject ​

ListObjectsV2 ​

Multipart Upload ​

Pythoni näide ​

Go näide ​

Konfigureeri CORS (brauseri SDK ligipääs) ​

PutBucketCors ​

GetBucketCors ​

DeleteBucketCors ​

Piirmäär ja vaikeväärtused ​

Turvamärkus reaalses maailmas ​

Töölaua alternatiiv ​

Erinevused Amazon S3-st ​

Migreerimine Amazon S3-st ​

Migreerimine Filebase'ist ​

S3 ühilduvus

Endpoint

Volitused

Kuidas volitusi saada

Vastendamine AWS volitustega

Kiirstart

Buckets = Kaustad

Bucket'i nimed on globaalselt unikaalsed

Toetatud operatsioonid

PutObject

GetObject

HeadObject

DeleteObject

ListObjectsV2

Multipart Upload

Pythoni näide

Go näide

Konfigureeri CORS (brauseri SDK ligipääs)

PutBucketCors

GetBucketCors

DeleteBucketCors

Piirmäär ja vaikeväärtused

Turvamärkus reaalses maailmas

Töölaua alternatiiv

Erinevused Amazon S3-st

Migreerimine Amazon S3-st

Migreerimine Filebase'ist