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

1. Mine Dashboard > API Keys
2. Kliki Create API key ja anna sellele nimi (nt „S3 ligipääs")
3. 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

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: QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy

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

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.

Toetatud operatsioonid

PutObject

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

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

# 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.

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.

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.

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.

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:

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:

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

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

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)

Migreerimine Amazon S3-st

Asenda oma S3 kliendi konfiguratsioon:

 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:

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