Kompatibilita s S3

Použite AWS SDK na nahrávanie, sťahovanie a správu súborov na IPFS Ninja s rovnakým kódom, aký používate pre Amazon S3.

Endpoint

https://s3.ipfs.ninja

Prihlasovacie údaje

API S3 používa váš API kľúč IPFS Ninja na autentifikáciu. Váš API kľúč slúži ako access key aj ako secret key.

Ako získať prihlasovacie údaje

Prejdite na Dashboard > API Keys
Kliknite na Create API key a zadajte názov (napr. "S3 access")
Okamžite skopírujte celý kľúč — zobrazí sa iba raz a neskôr ho nie je možné získať

Váš kľúč vyzerá takto:

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

Mapovanie na prihlasovacie údaje AWS

Parameter AWS	Hodnota	Príklad
`accessKeyId`	Prvých 12 znakov vášho API kľúča	`bws_628bba35`
`secretAccessKey`	Celý API kľúč (všetkých 36 znakov)	`bws_628bba35e9e0079d9ff9c392b1b55a7b`
`region`	Vždy `us-east-1`	`us-east-1`

WARNING

Celý API kľúč sa zobrazí iba raz pri vytvorení. Ak ho stratíte, vymažte kľúč a vytvorte nový na stránke API Keys.

Rýchly štart

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

Buckety = Priečinky

S3 buckety zodpovedajú vašim priečinkom v IPFS Ninja. Keď nahráte súbor do bucketu, uloží sa do zodpovedajúceho priečinka. Keď vypíšete objekty v bucket-e, vidíte súbory v danom priečinku.

Operácia S3	Ekvivalent v IPFS Ninja
`CreateBucket`	Vytvorenie nového priečinka
`ListBuckets`	Zoznam vašich priečinkov
`DeleteBucket`	Vymazanie priečinka a všetkých súborov v ňom
`PutObject` do bucketu	Nahranie súboru do priečinka
`ListObjectsV2` na bucket-e	Zoznam súborov v priečinku

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

Priečinky vytvorené cez API S3 sú tie isté priečinky, ktoré vidíte vo svojom Dashboard. Súbory môžete organizovať cez API S3, REST API alebo webové rozhranie — všetky zdieľajú rovnaký systém priečinkov.

INFO

Na rozdiel od Amazon S3 sú priečinky IPFS Ninja štandardne ploché. Pre vytvorenie vnorených štruktúr použite endpointy priečinkov REST API s parentFolderId. Cez API S3 použite prefixy kľúčov (napr. images/photo.png) na organizáciu v rámci priečinka.

Názvy bucketov sú globálne jedinečné

Názvy bucketov žijú v globálnom menšom priestore naprieč všetkými zákazníkmi, čo zodpovedá sémantike AWS S3. To znamená:

Prvý používateľ, ktorý vytvorí bucket s daným názvom, si tento názov globálne zaberá.
Neskoršie volania CreateBucket s rovnakým názvom z ľubovoľného účtu vrátia BucketAlreadyExists (409).
Ak sa pokúsite znova vytvoriť svoj vlastný bucket, dostanete BucketAlreadyOwnedByYou (409).
Váš priečinok v ovládacom paneli je viazaný na účet a môže mať stále ľubovoľný názov — cez globálny menný priestor prechádza iba S3-viditeľný bucket názov.

Ak je názov, ktorý chcete, obsadený, zvoľte inak rozsahovo definovaný názov (myapp-photos-2026, acme-nft-metadata) — rovnaký zvyk, aký by ste použili na Amazon S3.

Podporované operácie

PutObject

Nahrá súbor na IPFS. Súbor je pripnutý, bezpečnostne skenovaný a CID je vrátené v hlavičkách ETag a x-amz-meta-cid.

Pre import súboru CAR namiesto bežného súboru pridajte metadátovú hlavičku x-amz-meta-import: car. Podrobnosti nájdete v Import CAR.

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

Stiahne súbor podľa jeho kľúča (názvu súboru) alebo 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

Získa metadáta súboru bez sťahovania obsahu.

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

Odpne súbor z IPFS a vymaže ho z vášho účtu.

javascript

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

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

ListObjectsV2

Vypíše súbory v bucket-e s voliteľným filtrovaním podľa prefixu a stránkovaním.

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

Nahrávajte veľké súbory (do 5 GB) pomocou viacdielneho nahrávania. AWS SDK to spracuje automaticky:

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

Alebo ovládajte časti manuálne:

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

Príklad v Pythone

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

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

Konfigurácia CORS (prístup z prehliadačového SDK)

Ak voláte API S3 priamo z prehliadačového JavaScriptu (SPA, wallet aplikácia, nástroj ovládacieho panelu), musíte najprv nakonfigurovať CORS na bucket-e. Inak prehliadače zablokujú preflight a vaše nahrávania zlyhajú s chybou No 'Access-Control-Allow-Origin' header is present.

Rovnaký tvar ako AWS S3 — subresources PutBucketCors / GetBucketCors / DeleteBucketCors:

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

Limit a predvolené hodnoty

Až 5 pravidiel na bucket (špecifikácia povoľuje 100; obmedzujeme na 5, aby odpoveď na prehliadačový preflight zostala kompaktná).
Celková konfigurácia obmedzená na 64 KB po serializácii.
Ak nie je nastavená žiadna CORS konfigurácia, prehliadačové preflight požiadavky sú zamietnuté — rovnako ako predvolené správanie AWS S3. Nakonfigurujte explicitné pravidlá pre pôvody, z ktorých skutočne obsluhujete.

Poznámka k bezpečnosti z praxe

CORS je vrstva pohodlia na strane prehliadača, nie bezpečnostná hranica. Každé volanie API S3 stále vyžaduje platný podpis SigV4 vypočítaný z vášho API kľúča — permisívna CORS konfigurácia nedovolí nikomu použiť váš bucket bez tohto poverenia. Čo CORS skutočne bráni: neúmyselnému pôvodu (napr. zastaranej kópii vašej aplikácie na dev.myapp.com) odosielať podpísané požiadavky z kontextu prehliadača.

Alternatíva v ovládacom paneli

Stránka Súbory má v ponuke akcií každého priečinka položku S3 CORS. Rovnaké podkladové úložisko; ak nechcete písať kód pre PutBucketCors, nakonfigurujte to tam.

Rozdiely oproti Amazon S3

Funkcia	Amazon S3	IPFS Ninja S3
Model úložiska	Meniteľné objekty	Adresovanie podľa obsahu (nemenné CID)
Správanie pri prepísaní	Nahradí objekt na mieste	Vytvorí nové CID, staré CID zostáva prístupné
Verziovanie	Podporované	Nepodporované (použite CID na verziovanie)
Šifrovanie na strane servera	Podporované	Nepodporované (obsah je na IPFS)
Politiky životného cyklu	Podporované	Nepodporované
Politiky bucketov / ACL	Podporované	Použite režimy prístupu gateway
Predpodpísané URL	Podporované	Použite podpísané tokeny na nahrávanie
Maximálna veľkosť objektu	5 TB	5 GB (multipart), 100 MB (jeden PUT)
Regióny	Multiregión	Iba `us-east-1`
Hodnota `ETag`	MD5 hash	IPFS CID
Dodatočné hlavičky	Štandardné S3	`x-amz-meta-cid` (IPFS CID)
Formát CID	N/A	Moderné CIDv1 (`bafy…`) pre nové nahrávania; staršie `Qm…` zostáva platné ako vstup
Menný priestor bucketov	Globálny (naprieč AWS)	Globálny (naprieč všetkými účtami IPFS Ninja) — rovnaká sémantika
CORS	`PutBucketCors` podporované	`PutBucketCors` podporované (limit 5 pravidiel)

Migrácia z Amazon S3

Nahraďte konfiguráciu svojho S3 klienta:

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

Vaše existujúce volania PutObject, GetObject, ListObjectsV2 a DeleteObject fungujú bez zmien.

Migrácia z Filebase

Nahraďte URL endpointu:

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

Kompatibilita s S3 ​

Endpoint ​

Prihlasovacie údaje ​

Ako získať prihlasovacie údaje ​

Mapovanie na prihlasovacie údaje AWS ​

Rýchly štart ​

Buckety = Priečinky ​

Názvy bucketov sú globálne jedinečné ​

Podporované operácie ​

PutObject ​

GetObject ​

HeadObject ​

DeleteObject ​

ListObjectsV2 ​

Multipart Upload ​

Príklad v Pythone ​

Príklad v Go ​

Konfigurácia CORS (prístup z prehliadačového SDK) ​

PutBucketCors ​

GetBucketCors ​

DeleteBucketCors ​

Limit a predvolené hodnoty ​

Poznámka k bezpečnosti z praxe ​

Alternatíva v ovládacom paneli ​

Rozdiely oproti Amazon S3 ​

Migrácia z Amazon S3 ​

Migrácia z Filebase ​

Kompatibilita s S3

Endpoint

Prihlasovacie údaje

Ako získať prihlasovacie údaje

Mapovanie na prihlasovacie údaje AWS

Rýchly štart

Buckety = Priečinky

Názvy bucketov sú globálne jedinečné

Podporované operácie

PutObject

GetObject

HeadObject

DeleteObject

ListObjectsV2

Multipart Upload

Príklad v Pythone

Príklad v Go

Konfigurácia CORS (prístup z prehliadačového SDK)

PutBucketCors

GetBucketCors

DeleteBucketCors

Limit a predvolené hodnoty

Poznámka k bezpečnosti z praxe

Alternatíva v ovládacom paneli

Rozdiely oproti Amazon S3

Migrácia z Amazon S3

Migrácia z Filebase