ความเข้ากันได้กับ S3

ใช้ AWS SDK เพื่ออัปโหลด ดาวน์โหลด และจัดการไฟล์บน IPFS Ninja ด้วยโค้ดเดียวกับที่คุณใช้กับ Amazon S3

Endpoint

https://s3.ipfs.ninja

ข้อมูลประจำตัว

S3 API ใช้ API key ของ IPFS Ninja สำหรับการยืนยันตัวตน API key ของคุณทำหน้าที่เป็นทั้ง access key และ secret key

วิธีรับข้อมูลประจำตัว

1. ไปที่ แดชบอร์ด > API Keys
2. คลิก Create API key และตั้งชื่อ (เช่น "S3 access")
3. คัดลอก key ทั้งหมดทันที — จะแสดงเพียงครั้งเดียวและไม่สามารถเรียกดูได้ภายหลัง

key ของคุณมีรูปแบบดังนี้:

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

การแมปกับข้อมูลประจำตัว AWS

พารามิเตอร์ AWS	ค่า	ตัวอย่าง
accessKeyId	12 ตัวอักษรแรกของ API key	bws_628bba35
secretAccessKey	API key ทั้งหมด (36 ตัวอักษร)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	ใช้ us-east-1 เสมอ	us-east-1

WARNING

API key ทั้งหมดจะแสดงเพียงครั้งเดียวเมื่อคุณสร้างมัน หากสูญหาย ให้ลบ key นั้นและสร้างใหม่จากหน้า API Keys

เริ่มต้นอย่างรวดเร็ว

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 = โฟลเดอร์

S3 bucket แมปกับโฟลเดอร์ของคุณใน IPFS Ninja เมื่อคุณอัปโหลดไฟล์ไปยัง bucket ไฟล์จะถูกเก็บในโฟลเดอร์ที่สอดคล้องกัน เมื่อคุณลิสต์ออบเจกต์ใน bucket คุณจะเห็นไฟล์ในโฟลเดอร์นั้น

การดำเนินการ S3	เทียบเท่าใน IPFS Ninja
CreateBucket	สร้างโฟลเดอร์ใหม่
ListBuckets	ลิสต์โฟลเดอร์ของคุณ
DeleteBucket	ลบโฟลเดอร์และไฟล์ทั้งหมดในนั้น
PutObject ไปยัง bucket	อัปโหลดไฟล์เข้าโฟลเดอร์
ListObjectsV2 บน bucket	ลิสต์ไฟล์ในโฟลเดอร์

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 คือโฟลเดอร์เดียวกับที่แสดงบนแดชบอร์ดของคุณ คุณสามารถจัดระเบียบไฟล์จาก S3 API, REST API หรือเว็บอินเทอร์เฟซ — ทุกช่องทางใช้ระบบโฟลเดอร์เดียวกัน

INFO

ต่างจาก Amazon S3 โฟลเดอร์ของ IPFS Ninja เป็นแบบแบนโดยค่าเริ่มต้น หากต้องการสร้างโครงสร้างซ้อน ให้ใช้ endpoint โฟลเดอร์ของ REST API กับ parentFolderId จาก S3 API ให้ใช้ prefix ของ key (เช่น images/photo.png) เพื่อจัดระเบียบภายในโฟลเดอร์

การดำเนินการที่รองรับ

PutObject

อัปโหลดไฟล์ไปยัง IPFS ไฟล์จะถูก pin สแกนความปลอดภัย และ CID จะถูกส่งกลับใน header ETag และ 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

ดาวน์โหลดไฟล์ด้วย key (ชื่อไฟล์) หรือ 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

รับข้อมูลเมตาของไฟล์โดยไม่ต้องดาวน์โหลดเนื้อหา

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

ถอน pin ไฟล์จาก IPFS และลบออกจากบัญชีของคุณ

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

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

ListObjectsV2

ลิสต์ไฟล์ใน bucket พร้อมการกรองด้วย prefix และการแบ่งหน้า

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)

อัปโหลดไฟล์ขนาดใหญ่ (สูงสุด 5 GB) โดยใช้การอัปโหลดแบบหลายส่วน AWS SDK จัดการสิ่งนี้โดยอัตโนมัติ:

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

หรือควบคุมแต่ละส่วนด้วยตนเอง:

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

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

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

ฟีเจอร์	Amazon S3	IPFS Ninja S3
โมเดลการจัดเก็บ	ออบเจกต์ที่เปลี่ยนแปลงได้	ระบุตำแหน่งด้วยเนื้อหา (CID ที่เปลี่ยนแปลงไม่ได้)
พฤติกรรมการเขียนทับ	แทนที่ออบเจกต์ในที่เดิม	สร้าง CID ใหม่ CID เก่ายังเข้าถึงได้
การกำหนดเวอร์ชัน	รองรับ	ไม่รองรับ (ใช้ CID สำหรับการกำหนดเวอร์ชัน)
การเข้ารหัสฝั่งเซิร์ฟเวอร์	รองรับ	ไม่รองรับ (เนื้อหาอยู่บน IPFS)
นโยบายวงจรชีวิต	รองรับ	ไม่รองรับ
นโยบาย bucket / ACL	รองรับ	ใช้โหมดการเข้าถึง gateway
URL ที่ลงนามล่วงหน้า	รองรับ	ใช้โทเค็นอัปโหลดที่ลงนาม
ขนาดออบเจกต์สูงสุด	5 TB	5 GB (หลายส่วน), 100 MB (PUT เดียว)
ภูมิภาค	หลายภูมิภาค	us-east-1 เท่านั้น
ค่า ETag	MD5 hash	IPFS CID
Header เพิ่มเติม	S3 มาตรฐาน	x-amz-meta-cid (IPFS CID)

การย้ายจาก Amazon S3

เปลี่ยนการตั้งค่า S3 client ของคุณ:

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

การเรียก PutObject, GetObject, ListObjectsV2 และ DeleteObject ที่มีอยู่ของคุณจะทำงานได้โดยไม่ต้องเปลี่ยนแปลง

การย้ายจาก Filebase

เปลี่ยน URL ของ endpoint:

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