S3 saderība

Izmantojiet AWS SDK, lai augšupielādētu, lejupielādētu un pārvaldītu failus IPFS Ninja platformā ar to pašu kodu, ko izmantojat Amazon S3.

Endpoint

https://s3.ipfs.ninja

Akreditācijas dati

S3 API autentifikācijai izmanto jūsu IPFS Ninja API atslēgu. Jūsu API atslēga kalpo gan kā piekļuves atslēga, gan kā slepenā atslēga.

Kā iegūt akreditācijas datus

Dodieties uz Dashboard > API Keys
Noklikšķiniet uz Create API key un piešķiriet tai nosaukumu (piemēram, "S3 access")
Nekavējoties nokopējiet pilno atslēgu — tā tiek parādīta tikai vienu reizi un vēlāk nav atgūstama

Jūsu atslēga izskatās šādi:

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

Pārveidošana uz AWS akreditācijas datiem

AWS parametrs	Vērtība	Piemērs
`accessKeyId`	Pirmās 12 jūsu API atslēgas rakstzīmes	`bws_628bba35`
`secretAccessKey`	Pilna API atslēga (visas 36 rakstzīmes)	`bws_628bba35e9e0079d9ff9c392b1b55a7b`
`region`	Vienmēr `us-east-1`	`us-east-1`

WARNING

Pilna API atslēga tiek parādīta tikai vienu reizi, kad to izveidojat. Ja to pazaudējat, izdzēsiet atslēgu un izveidojiet jaunu API Keys lapā.

Ātrais sākums

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 = mapes

S3 bucket atbilst jūsu IPFS Ninja mapēm. Kad augšupielādējat failu bucket, tas tiek saglabāts atbilstošajā mapē. Kad uzskaitāt objektus bucket, jūs redzat failus šajā mapē.

S3 operācija	IPFS Ninja ekvivalents
`CreateBucket`	Izveidot jaunu mapi
`ListBuckets`	Uzskaitīt jūsu mapes
`DeleteBucket`	Dzēst mapi un visus tajā esošos failus
`PutObject` uz bucket	Augšupielādēt failu mapē
`ListObjectsV2` uz bucket	Uzskaitīt failus mapē

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

Mapes, kas izveidotas caur S3 API, ir tās pašas mapes, kas redzamas jūsu Dashboard. Jūs varat organizēt failus gan caur S3 API, gan REST API, gan tīmekļa saskarni — tās visas izmanto vienu un to pašu mapju sistēmu.

INFO

Atšķirībā no Amazon S3, IPFS Ninja mapes pēc noklusējuma ir plakanas. Lai izveidotu ligzdotas struktūras, izmantojiet REST API mapju endpoint ar parentFolderId. No S3 API izmantojiet atslēgu prefiksus (piemēram, images/photo.png), lai organizētu failus mapē.

Bucket nosaukumi ir globāli unikāli

Bucket nosaukumi atrodas globālā nosaukumtelpā starp visiem klientiem, atbilstoši AWS S3 semantikai. Tas nozīmē:

Pirmais lietotājs, kas izveido bucket ar noteiktu nosaukumu, pieprasa šo nosaukumu globāli.
Vēlāki CreateBucket izsaukumi ar to pašu nosaukumu no jebkura konta atgriež BucketAlreadyExists (409).
Ja mēģināt atkārtoti izveidot savu paša bucket, jūs saņemat BucketAlreadyOwnedByYou (409).
Jūsu mapes nosaukums informācijas panelī ir specifisks kontam un var joprojām būt jebkāds — tikai S3 redzamais bucket nosaukums iziet caur globālo nosaukumtelpu.

Ja vēlamais nosaukums ir aizņemts, izvēlieties citādi definētu nosaukumu (myapp-photos-2026, acme-nft-metadata) — tāda pati konvencija, kādu izmantotu Amazon S3.

Atbalstītās operācijas

PutObject

Augšupielādējiet failu uz IPFS. Fails tiek piesprausts, drošības pārbaudīts, un CID tiek atgriezts ETag un x-amz-meta-cid galvenēs.

Lai importētu CAR failu parasta faila vietā, pievienojiet x-amz-meta-import: car metadatu galveni. Skatiet CAR imports detaļām.

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

Lejupielādējiet failu pēc tā atslēgas (faila nosaukuma) vai CID.

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

Iegūstiet faila metadatus, nelejupielādējot saturu.

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

Atspraudiet failu no IPFS un dzēsiet to no sava konta.

javascript

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

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

ListObjectsV2

Uzskaitiet failus bucket ar neobligātu prefiksu filtrēšanu un lappušošanu.

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

Augšupielādējiet lielus failus (līdz 5 GB), izmantojot vairākdaļu augšupielādi. AWS SDK to apstrādā automātiski:

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

Vai manuāli kontrolējiet daļas:

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 piemērs

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 piemērs

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

Konfigurēt CORS (pārlūka SDK piekļuve)

Ja izsaucat S3 API tieši no pārlūka JavaScript (SPA, maka lietotne, informācijas paneļa rīks), vispirms jākonfigurē CORS uz bucket. Pretējā gadījumā pārlūki bloķē preflight, un jūsu augšupielādes neizdodas ar kļūdu No 'Access-Control-Allow-Origin' header is present.

Tāda pati struktūra kā AWS S3 — PutBucketCors / GetBucketCors / DeleteBucketCors apakšresursi:

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

Ierobežojumi un noklusējumi

Līdz 5 noteikumiem katram bucket (specifikācija pieļauj 100; mēs ierobežojam līdz 5, lai pārlūka preflight atbilde paliktu kompakta).
Kopējā konfigurācija ierobežota līdz 64 KB serializētā veidā.
Ja CORS konfigurācija nav iestatīta, pārlūka preflight tiek noraidīti — atbilstoši AWS S3 noklusējuma nostājai. Konfigurējiet skaidrus noteikumus izcelsmēm, no kurām faktiski apkalpojat.

Piezīme par drošību reālajā pasaulē

CORS ir pārlūka puses ērtības slānis, nevis drošības robeža. Katram S3 API izsaukumam joprojām ir nepieciešams derīgs SigV4 paraksts, kas aprēķināts no jūsu API atslēgas — atļaujoša CORS konfigurācija neļauj nevienam izmantot jūsu bucket bez šī akreditācijas datu. Ko CORS gan novērš: neparedzēta izcelsme (piemēram, novecojusi jūsu lietotnes kopija dev.myapp.com), kas sūta parakstītus pieprasījumus no pārlūka konteksta.

Alternatīva informācijas panelī

Failu lapā katras mapes darbību izvēlnē ir ieraksts S3 CORS. Tas pats pamatā esošais glabātuves risinājums; ja nevēlaties rakstīt PutBucketCors kodu, konfigurējiet to tur.

Atšķirības no Amazon S3

Funkcija	Amazon S3	IPFS Ninja S3
Glabāšanas modelis	Maināmi objekti	Satura adresēts (nemainīgi CID)
Pārrakstīšanas uzvedība	Aizvieto objektu vietā	Izveido jaunu CID, vecais CID joprojām pieejams
Versiju pārvaldība	Atbalstīta	Nav atbalstīta (izmantojiet CID versiju pārvaldībai)
Servera puses šifrēšana	Atbalstīta	Nav atbalstīta (saturs ir IPFS tīklā)
Dzīves cikla politikas	Atbalstītas	Nav atbalstītas
Bucket politikas / ACL	Atbalstītas	Izmantojiet vārtejas piekļuves režīmus
Iepriekš parakstīti URL	Atbalstīti	Izmantojiet parakstītus augšupielādes tokenus
Maksimālais objekta izmērs	5 TB	5 GB (vairākdaļu), 100 MB (viens PUT)
Reģioni	Vairāku reģionu	Tikai `us-east-1`
`ETag` vērtība	MD5 hash	IPFS CID
Papildu galvenes	Standarta S3	`x-amz-meta-cid` (IPFS CID)
CID formāts	N/A	Modernais CIDv1 (`bafy…`) jaunām augšupielādēm; vecmodīgais `Qm…` joprojām derīgs kā ievade
Bucket nosaukumtelpa	Globāla (visā AWS)	Globāla (starp visiem IPFS Ninja kontiem) — tāda pati semantika
CORS	`PutBucketCors` atbalstīts	`PutBucketCors` atbalstīts (5 noteikumu limits)

Migrācija no Amazon S3

Nomainiet savu S3 klienta konfigurāciju:

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

Jūsu esošie PutObject, GetObject, ListObjectsV2 un DeleteObject izsaukumi darbojas bez izmaiņām.

Migrācija no Filebase

Nomainiet 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 saderība ​

Endpoint ​

Akreditācijas dati ​

Kā iegūt akreditācijas datus ​

Pārveidošana uz AWS akreditācijas datiem ​

Ātrais sākums ​

Bucket = mapes ​

Bucket nosaukumi ir globāli unikāli ​

Atbalstītās operācijas ​

PutObject ​

GetObject ​

HeadObject ​

DeleteObject ​

ListObjectsV2 ​

Multipart Upload ​

Python piemērs ​

Go piemērs ​

Konfigurēt CORS (pārlūka SDK piekļuve) ​

PutBucketCors ​

GetBucketCors ​

DeleteBucketCors ​

Ierobežojumi un noklusējumi ​

Piezīme par drošību reālajā pasaulē ​

Alternatīva informācijas panelī ​

Atšķirības no Amazon S3 ​

Migrācija no Amazon S3 ​

Migrācija no Filebase ​

S3 saderība

Endpoint

Akreditācijas dati

Kā iegūt akreditācijas datus

Pārveidošana uz AWS akreditācijas datiem

Ātrais sākums

Bucket = mapes

Bucket nosaukumi ir globāli unikāli

Atbalstītās operācijas

PutObject

GetObject

HeadObject

DeleteObject

ListObjectsV2

Multipart Upload

Python piemērs

Go piemērs

Konfigurēt CORS (pārlūka SDK piekļuve)

PutBucketCors

GetBucketCors

DeleteBucketCors

Ierobežojumi un noklusējumi

Piezīme par drošību reālajā pasaulē

Alternatīva informācijas panelī

Atšķirības no Amazon S3

Migrācija no Amazon S3

Migrācija no Filebase