S3 Uyumluluğu

Amazon S3 için kullandığınız aynı kodla IPFS Ninja üzerinde dosya yüklemek, indirmek ve yönetmek için AWS SDK kullanın.

Endpoint

https://s3.ipfs.ninja

Kimlik Bilgileri

S3 API, kimlik doğrulama için IPFS Ninja API anahtarınızı kullanır. API anahtarınız hem erişim anahtarı hem de gizli anahtar olarak işlev görür.

Kimlik bilgilerinizi nasıl alırsınız

1. Dashboard > API Keys sayfasına gidin
2. Create API key butonuna tıklayın ve bir isim verin (ör. "S3 erişimi")
3. Anahtarın tamamını hemen kopyalayın — yalnızca bir kez gösterilir ve daha sonra geri alınamaz

Anahtarınız şuna benzer:

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

AWS kimlik bilgileriyle eşleştirme

AWS Parametresi	Değer	Örnek
accessKeyId	API anahtarınızın ilk 12 karakteri	bws_628bba35
secretAccessKey	Tam API anahtarı (36 karakterin tamamı)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Her zaman us-east-1	us-east-1

WARNING

Tam API anahtarı yalnızca oluşturduğunuzda bir kez gösterilir. Kaybederseniz anahtarı silip API Keys sayfasından yeni bir tane oluşturun.

Hızlı Başlangıç

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'lar = Klasörler

S3 bucket'ları IPFS Ninja klasörlerinize karşılık gelir. Bir bucket'a dosya yüklediğinizde, ilgili klasörde saklanır. Bir bucket'taki nesneleri listelediğinizde, o klasördeki dosyaları görürsünüz.

S3 İşlemi	IPFS Ninja Karşılığı
CreateBucket	Yeni bir klasör oluştur
ListBuckets	Klasörlerinizi listele
DeleteBucket	Bir klasörü ve içindeki tüm dosyaları sil
PutObject ile bucket'a	Klasöre dosya yükle
ListObjectsV2 ile bucket'ta	Klasördeki dosyaları listele

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 üzerinden oluşturulan klasörler, Dashboard'unuzda görünen klasörlerle aynıdır. Dosyalarınızı S3 API, REST API veya web arayüzü üzerinden düzenleyebilirsiniz — hepsi aynı klasör sistemini paylaşır.

INFO

Amazon S3'ten farklı olarak, IPFS Ninja klasörleri varsayılan olarak düzdür. İç içe yapılar oluşturmak için REST API'nin parentFolderId ile klasör endpoint'lerini kullanın. S3 API'den, bir klasör içinde düzenlemek için anahtar ön ekleri kullanın (ör. images/photo.png).

Desteklenen İşlemler

PutObject

IPFS'e dosya yükleyin. Dosya sabitlenir, güvenlik taramasından geçirilir ve CID ETag ile x-amz-meta-cid başlıklarında döndürülür.

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

Bir dosyayı anahtar adı (dosya adı) veya CID ile indirin.

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

İçeriği indirmeden dosya meta verilerini alın.

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

Bir dosyanın IPFS'teki sabitlemesini kaldırın ve hesabınızdan silin.

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

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

ListObjectsV2

İsteğe bağlı ön ek filtreleme ve sayfalama ile bucket'taki dosyaları listeleyin.

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

Büyük dosyaları (5 GB'a kadar) multipart upload ile yükleyin. AWS SDK bunu otomatik olarak yönetir:

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

Ya da parçaları manuel olarak kontrol edin:

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 Örneği

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 Örneği

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

Amazon S3 ile Farklar

Özellik	Amazon S3	IPFS Ninja S3
Depolama modeli	Değiştirilebilir nesneler	İçerik adresli (değişmez CID'ler)
Üzerine yazma davranışı	Nesneyi yerinde değiştirir	Yeni CID oluşturur, eski CID hala erişilebilir
Sürümleme	Desteklenir	Desteklenmez (sürümleme için CID'leri kullanın)
Sunucu tarafı şifreleme	Desteklenir	Desteklenmez (içerik IPFS üzerinde)
Yaşam döngüsü politikaları	Desteklenir	Desteklenmez
Bucket politikaları / ACL'ler	Desteklenir	Gateway erişim modlarını kullanın
Ön imzalı URL'ler	Desteklenir	İmzalı yükleme token'larını kullanın
Maksimum nesne boyutu	5 TB	5 GB (multipart), 100 MB (tekli PUT)
Bölgeler	Çok bölgeli	Yalnızca us-east-1
ETag değeri	MD5 hash	IPFS CID
Ek başlıklar	Standart S3	x-amz-meta-cid (IPFS CID)

Amazon S3'ten Geçiş

S3 istemci yapılandırmanızı değiştirin:

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

Mevcut PutObject, GetObject, ListObjectsV2 ve DeleteObject çağrılarınız değişiklik olmadan çalışır.

Filebase'den Geçiş

Endpoint URL'sini değiştirin:

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