Pagkakatugma sa S3

Gamitin ang AWS SDK para mag-upload, mag-download, at mamahala ng mga file sa IPFS Ninja gamit ang parehong code na ginagamit mo para sa Amazon S3.

Endpoint

https://s3.ipfs.ninja

Mga Kredensyal

Ginagamit ng S3 API ang iyong IPFS Ninja API key para sa authentication. Ang iyong API key ay nagsisilbing access key at secret key.

Paano kunin ang iyong mga kredensyal

1. Pumunta sa Dashboard > API Keys
2. I-click ang Create API key at bigyan ito ng pangalan (hal. "S3 access")
3. Kopyahin agad ang buong key — isang beses lang itong ipapakita at hindi na maaaring makuha ulit

Ganito ang hitsura ng iyong key:

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

Pag-map sa AWS credentials

AWS Parameter	Halaga	Halimbawa
accessKeyId	Unang 12 character ng iyong API key	bws_628bba35
secretAccessKey	Ang buong API key (lahat ng 36 na character)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Laging us-east-1	us-east-1

WARNING

Ang buong API key ay ipapakita lang isang beses kapag ginawa mo ito. Kung mawala ito, burahin ang key at gumawa ng bago mula sa pahina ng API Keys.

Mabilis na Simula

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

Mga Bucket = Mga Folder

Ang mga S3 bucket ay nagma-map sa iyong mga folder sa IPFS Ninja. Kapag nag-upload ka ng file sa isang bucket, inilalagay ito sa kaukulang folder. Kapag inilista mo ang mga object sa isang bucket, makikita mo ang mga file sa folder na iyon.

S3 Operation	Katumbas sa IPFS Ninja
CreateBucket	Gumawa ng bagong folder
ListBuckets	Ilista ang iyong mga folder
DeleteBucket	Burahin ang folder at lahat ng file dito
PutObject sa bucket	Mag-upload ng file sa folder
ListObjectsV2 sa bucket	Ilista ang mga file sa folder

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

Ang mga folder na ginawa sa pamamagitan ng S3 API ay pareho ring mga folder na nakikita sa iyong Dashboard. Maaari mong ayusin ang mga file mula sa S3 API, REST API, o web interface — lahat sila ay gumagamit ng iisang folder system.

INFO

Hindi tulad ng Amazon S3, ang mga IPFS Ninja folder ay flat bilang default. Para gumawa ng nested na mga istruktura, gamitin ang mga folder endpoint ng REST API na may parentFolderId. Mula sa S3 API, gumamit ng key prefix (hal. images/photo.png) para mag-organisa sa loob ng isang folder.

Mga Sinusuportahang Operation

PutObject

Mag-upload ng file sa IPFS. Ang file ay pine-pin, sine-scan para sa seguridad, at ang CID ay ibinabalik sa ETag at x-amz-meta-cid header.

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

Mag-download ng file gamit ang key nito (filename) o 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

Kunin ang metadata ng file nang hindi dina-download ang content.

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

I-unpin ang file mula sa IPFS at burahin ito mula sa iyong account.

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

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

ListObjectsV2

Ilista ang mga file sa isang bucket na may opsyonal na prefix filtering at pagination.

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

Mag-upload ng malalaking file (hanggang 5 GB) gamit ang multipart upload. Awtomatikong hina-handle ito ng 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);

O manu-manong kontrolin ang mga bahagi:

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

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

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

Mga Pagkakaiba mula sa Amazon S3

Feature	Amazon S3	IPFS Ninja S3
Modelo ng storage	Mga nababagong object	Content-addressed (hindi nababagong mga CID)
Pag-uugali sa pag-overwrite	Pinapalitan ang object sa lugar	Gumagawa ng bagong CID, ang lumang CID ay naa-access pa rin
Versioning	Sinusuportahan	Hindi sinusuportahan (gamitin ang mga CID para sa versioning)
Server-side encryption	Sinusuportahan	Hindi sinusuportahan (ang content ay nasa IPFS)
Lifecycle policy	Sinusuportahan	Hindi sinusuportahan
Bucket policy / ACL	Sinusuportahan	Gamitin ang mga gateway access mode
Presigned URL	Sinusuportahan	Gamitin ang mga signed upload token
Pinakamataas na laki ng object	5 TB	5 GB (multipart), 100 MB (single PUT)
Mga region	Maraming region	us-east-1 lang
Halaga ng ETag	MD5 hash	IPFS CID
Karagdagang header	Standard S3	x-amz-meta-cid (IPFS CID)

Paglipat mula sa Amazon S3

Palitan ang iyong S3 client configuration:

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

Ang iyong mga kasalukuyang PutObject, GetObject, ListObjectsV2, at DeleteObject na mga tawag ay gagana nang walang pagbabago.

Paglipat mula sa Filebase

Palitan ang endpoint URL:

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