Združljivost s S3

Uporabite AWS SDK za nalaganje, prenašanje in upravljanje datotek na IPFS Ninja z enako kodo, kot jo uporabljate za Amazon S3.

Endpoint

https://s3.ipfs.ninja

Poverilnice

S3 API za avtentikacijo uporablja vaš API ključ IPFS Ninja. Vaš API ključ služi kot ključ za dostop (access key) in kot skrivni ključ (secret key).

Kako pridobiti poverilnice

1. Pojdite na Nadzorna plošča > API ključi
2. Kliknite Create API key in mu dodelite ime (npr. "S3 dostop")
3. Takoj kopirajte celoten ključ — prikazan je samo enkrat in ga pozneje ni mogoče pridobiti

Vaš ključ je videti takole:

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

Preslikava v AWS poverilnice

AWS parameter	Vrednost	Primer
accessKeyId	Prvih 12 znakov vašega API ključa	bws_628bba35
secretAccessKey	Celoten API ključ (vseh 36 znakov)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Vedno us-east-1	us-east-1

WARNING

Celoten API ključ je prikazan samo enkrat, ko ga ustvarite. Če ga izgubite, izbrišite ključ in ustvarite novega na strani API ključev.

Hiter začetek

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

Bucket-i = Mape

S3 bucket-i se preslikajo v vaše mape na IPFS Ninja. Ko naložite datoteko v bucket, se ta shrani v ustrezno mapo. Ko izpišete objekte v bucket-u, vidite datoteke v tej mapi.

S3 operacija	Ustreznik v IPFS Ninja
CreateBucket	Ustvari novo mapo
ListBuckets	Izpiši vaše mape
DeleteBucket	Izbriši mapo in vse datoteke v njej
PutObject v bucket	Naloži datoteko v mapo
ListObjectsV2 na bucket-u	Izpiši datoteke v mapi

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

Mape, ustvarjene prek S3 API, so iste mape, ki so vidne na vaši nadzorni plošči. Datoteke lahko organizirate prek S3 API, REST API ali spletnega vmesnika — vsi delijo isti sistem map.

INFO

Za razliko od Amazon S3 so mape v IPFS Ninja privzeto ravne. Za ustvarjanje ugnezdenih struktur uporabite endpoint-e za mape v REST API z parentFolderId. Prek S3 API uporabite predpone ključev (npr. images/photo.png) za organizacijo znotraj mape.

Podprte operacije

PutObject

Naložite datoteko na IPFS. Datoteka je pripeta (pinned), varnostno pregledana, CID pa je vrnjen v glavah ETag in 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

Prenesite datoteko po njenem ključu (imenu datoteke) ali CID.

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

Pridobite metapodatke datoteke brez prenašanja vsebine.

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

Odpnite datoteko z IPFS in jo izbrišite iz svojega računa.

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

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

ListObjectsV2

Izpišite datoteke v bucket-u z neobveznim filtriranjem po predponi in paginacijo.

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
}

Večdelno nalaganje (Multipart Upload)

Naložite velike datoteke (do 5 GB) z večdelnim nalaganjem. AWS SDK to opravi samodejno:

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

Ali ročno upravljajte dele:

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

Primer v Pythonu

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

Primer v Go

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

Razlike od Amazon S3

Funkcionalnost	Amazon S3	IPFS Ninja S3
Model shranjevanja	Spremenljivi objekti	Vsebinsko naslovljeni (nespremenljivi CID-ji)
Vedenje pri prepisu	Zamenja objekt na mestu	Ustvari nov CID, stari CID ostane dostopen
Verzioniranje	Podprto	Ni podprto (uporabite CID-je za verzioniranje)
Šifriranje na strežniku	Podprto	Ni podprto (vsebina je na IPFS)
Politike življenjskega cikla	Podprto	Ni podprto
Politike bucket-ov / ACL-ji	Podprto	Uporabite načine dostopa prek prehoda
Vnaprej podpisani URL-ji	Podprto	Uporabite podpisane žetone za nalaganje
Največja velikost objekta	5 TB	5 GB (večdelno), 100 MB (posamičen PUT)
Regije	Več regij	Samo us-east-1
Vrednost ETag	MD5 hash	IPFS CID
Dodatne glave	Standardne S3	x-amz-meta-cid (IPFS CID)

Selitev z Amazon S3

Zamenjajte konfiguracijo vašega S3 odjemalca:

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

Vaši obstoječi klici PutObject, GetObject, ListObjectsV2 in DeleteObject delujejo brez sprememb.

Selitev s Filebase

Zamenjajte URL endpoint-a:

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