Folder

Folder menyusun fail yang anda muat naik dalam papan pemuka. Ia bersifat metadata sahaja secara lalai — fail mengekalkan CID masing-masing dan tidak dipindahkan di IPFS — tetapi anda juga boleh snapshot folder untuk mewujudkannya sebagai direktori UnixFS sebenar dan mendapatkan satu CID untuk keseluruhannya.

Bila anda perlu snapshot folder

Snapshot folder ialah satu CID direktori IPFS yang mengandungi setiap fail dalam folder tersebut, boleh dialamatkan mengikut nama. Dengannya anda boleh:

• Kongsi keseluruhan folder melalui satu URL: https://ipfs.ninja/ipfs/{dirCid}/
• Selesaikan https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (atau mana-mana gateway lain) secara terus
• Letakkan CID ke dalam contenthash ENS untuk mengehoskan tapak statik
• Gunakannya sebagai CID asas koleksi NFT supaya setiap token merujuk ipfs://{dirCid}/<id>.json
• Semat direktori tersebut di mana-mana sahaja — setiap gateway IPFS di dunia tahu cara menyelesaikan CID direktori UnixFS

Snapshot adalah beralamat kandungan: kandungan folder yang sama sentiasa menghasilkan CID yang sama. Snapshot semula pada folder yang belum anda ubah mengembalikan CID yang sama seperti sebelumnya. Menambah/membuang/menamakan semula fail menghasilkan CID baharu; CID terdahulu kekal disemat dan boleh diselesaikan selagi anda tidak memadam fail-failnya.

Cipta folder

POST /folders

Parameter	Jenis	Diperlukan	Penerangan
name	string	Ya	Nama paparan.
parentFolderId	string | null	Tidak	ID folder induk untuk folder bersarang. Biarkan kosong untuk folder peringkat akar.

Contoh

curl -X POST https://api.ipfs.ninja/folders \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My NFT collection" }'

Mengembalikan:

{
  "folderId": "1f8e2c3a-…",
  "name": "My NFT collection",
  "parentFolderId": null,
  "createdAt": 1746360000000
}

Folder yang baharu dicipta tidak mempunyai snapshot. Medan latestSnapshot akan muncul pada folder sebaik sahaja anda memanggil POST /folders/{id}/snapshot (lihat di bawah) dan pada respons GET /folders yang berikutnya.

Senaraikan folder

GET /folders

Mengembalikan setiap folder dalam akaun anda, peringkat akar dan bersarang, dengan CID snapshot terkini untuk setiap satu (jika ada).

[
  {
    "folderId": "1f8e2c3a-…",
    "name": "My NFT collection",
    "parentFolderId": null,
    "createdAt": 1746360000000,
    "fileCount": 42,
    "latestSnapshot": {
      "cid": "QmRZx5…",
      "takenAt": 1746421000000,
      "fileCount": 42
    }
  }
]

fileCount mencerminkan kandungan semasa folder; latestSnapshot.fileCount mencerminkan kandungan pada masa snapshot terakhir dibuat. Jika kedua-duanya berbeza, CID snapshot masih boleh diselesaikan tetapi sudah lapuk — snapshot semula untuk mengemas kininya.

Alihkan fail ke dalam folder

PUT /files/{cid}/move

Parameter	Jenis	Diperlukan	Penerangan
folderId	string | null	Ya	ID folder sasaran, atau null untuk mengalihkan fail ke akar.

curl -X PUT https://api.ipfs.ninja/files/Qm.../move \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "1f8e2c3a-…" }'

Snapshot folder (dapatkan CID direktori UnixFS)

POST /folders/{folderId}/snapshot

Wujudkan folder sebagai direktori UnixFS sebenar pada kluster IPFS dan semat hasilnya. Mengembalikan satu CID untuk keseluruhan folder. Nama anak diambil daripada fileName setiap fail; pendua diselesaikan secara automatik.

Tiada badan permintaan diperlukan; parameter laluan mengenal pasti folder tersebut.

Contoh

curl -X POST https://api.ipfs.ninja/folders/1f8e2c3a-.../snapshot \
  -H "X-Api-Key: bws_your_api_key_here"

Mengembalikan:

{
  "ok": true,
  "folderId": "1f8e2c3a-…",
  "cid": "QmRZx5VgFHDsG7ECvaKkZBS4ydmkdAkDyaKyF71RYvh8",
  "fileCount": 42,
  "sizeBytes": 8421376,
  "takenAt": 1746421000000,
  "ipfsUrl": "https://ipfs.ninja/ipfs/QmRZx5.../"
}

CID tersebut turut disimpan pada rekod folder, jadi panggilan GET /folders yang seterusnya mengembalikannya sebagai latestSnapshot.cid tanpa perlu snapshot lagi.

Menyelesaikan snapshot

Setelah snapshot disemat, CID direktori boleh diselesaikan melalui mana-mana gateway IPFS. Corak URL yang paling mudah:

https://ipfs.ninja/ipfs/{dirCid}/         → senarai direktori
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → fail tersebut

Kluster menyemat secara rekursif, jadi anak-anak juga boleh diselesaikan — walaupun anda kemudian memadam fail asal dari akaun anda, salinan snapshot tersebut kekal wujud kerana ia adalah sematan berasingan yang berekursi melalui direktori.

Snapshot semula

Snapshot semula pada folder yang tidak berubah mengembalikan CID yang sama — CID direktori beralamat kandungan, jadi kandungan yang sama sentiasa menghasilkan hash yang sama, dan panggilan sematan kluster mengenal pasti pendua tersebut dan menjadi no-op pada bahagiannya.

Nota: laluan snapshot itu sendiri tidak percuma walaupun hasilnya adalah CID yang sama. Setiap panggilan membaca semula bait setiap fail dari IPFS dan memuat naik semula sebagai multipart ke endpoint /add kluster — di situlah pembungkusan-dengan-direktori berlaku. Untuk folder biasa (≤100 fail kecil) ini masih selesai dalam beberapa saat; untuk folder yang sangat besar, utamakan memanggil snapshot hanya apabila kandungan benar-benar berubah.

Memanggil snapshot selepas anda menambah atau membuang fail menghasilkan CID yang berbeza; CID sebelumnya terus boleh diselesaikan selagi anda tidak memadam fail-fail asasnya.

Had

• Folder mestilah mengandungi sekurang-kurangnya satu fail. Folder kosong mengembalikan 400 — folder is empty.
• Aksara nama fail dikodkan-URL dalam muat naik multipart yang diterima Kubo; URL gateway mungkin memerlukan pengekodan peratus untuk ruang atau aksara bukan-ASCII dalam nama fail anda.
• Snapshot dikira ke dalam jumlah sematan pelan anda tepat sekali bagi setiap CID unik — blok fail dinyahduakan, jadi snapshot kebanyakannya hanya menambah satu nod direktori kecil di atas fail yang sudah anda semat.

Kemas kini folder

PUT /folders/{folderId}

Parameter	Jenis	Diperlukan	Penerangan
name	string	Tidak	Nama paparan baharu.
parentFolderId	string | null	Tidak	Tukar induk folder. null mengalihkannya ke akar.

Padam folder

DELETE /folders/{folderId}

Memadam folder dan mencurah secara rekursif melalui setiap fail dan subfolder yang dikandunginya. Tertakluk kepada penjagaan keselamatan CID-berkongsi yang sama seperti pemadaman fail individu — jika pengguna lain masih menyemat CID yang anda muat naik, nyahsematan anda tidak menghapuskannya untuk mereka.

{
  "deleted": true,
  "filesDeleted": 42,
  "foldersDeleted": 3
}

Konfigurasikan CORS S3 untuk folder / bucket

Folder yang didedahkan melalui API serasi S3 bertindak sebagai bucket. Jika anda memacu API tersebut daripada JavaScript pelayar, anda memerlukan peraturan CORS pada bucket supaya preflight pelayar berjaya. Dua permukaan yang setara berkekalan pada storan yang sama:

• PUT /folders/{folderId}/cors — endpoint REST ini, disahkan-JWT (digunakan oleh papan pemuka)
• Subresource S3 PUT /{bucket}?cors — disahkan-SigV4 (digunakan oleh AWS SDK, lihat s3-compatibility.md)

PUT pada endpoint ini turut menuntut nama folder sebagai nama bucket unik-secara-global jika ia belum dituntut lagi.

PUT /folders/{folderId}/cors

Tetapkan peraturan CORS untuk bucket S3 folder tersebut. Sehingga 5 peraturan setiap bucket, 64 KB keseluruhan.

Parameter	Jenis	Diperlukan	Penerangan
rules	CorsRule[]	Ya	Tatasusunan peraturan CORS berbentuk-AWS (lihat di bawah). Tidak boleh kosong.
bucketName	string	Tidak	Nama bucket S3 eksplisit. Lalai kepada nama paparan folder. Jika nama yang dikehendaki sudah dituntut secara global, berikan alternatif di sini.

Setiap CorsRule:

Field	Jenis	Diperlukan	Penerangan
AllowedOrigins	string[]	Ya	Origin yang dibenarkan menghantar permintaan. Menyokong wildcard (https://*.myapp.com). Gunakan * untuk sebarang origin.
AllowedMethods	string[]	Ya	Satu atau lebih daripada GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Tidak	Header yang boleh disertakan pelayar pada permintaan. Lalai: tiada. Gunakan ["*"] untuk membenarkan semua (disyorkan untuk AWS SDK v3 yang menghantar Authorization, x-amz-*, dsb.).
ExposeHeaders	string[]	Tidak	Header respons yang boleh dibaca oleh JavaScript pelayar. Sertakan ETag dan x-amz-meta-cid jika aplikasi anda memerlukan CID yang dikembalikan.
MaxAgeSeconds	number	Tidak	Berapa lama pelayar cache preflight tersebut. 0-86400. Lalai 3600.
ID	string	Tidak	Label teks bebas untuk peraturan tersebut.

Contoh permintaan

curl -X PUT https://api.ipfs.ninja/folders/17f6dfd8-519c-4d0e-8f3a-5988a1d34ef2/cors \
  -H "Authorization: Bearer $COGNITO_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [{
      "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"],
      "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"],
      "MaxAgeSeconds": 3600
    }]
  }'

Respons 200 OK

{ "success": true, "rules": [ { "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"], "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"], "AllowedHeaders": ["*"], "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"], "MaxAgeSeconds": 3600 } ] }

GET /folders/{folderId}/cors

Mengembalikan peraturan CORS semasa berserta nama bucket (jika telah dituntut).

{
  "rules": [ … ],
  "bucketName": "my-project"
}

DELETE /folders/{folderId}/cors

Membuang semua peraturan CORS. Preflight pelayar terhadap bucket akan gagal secara tertutup sehingga peraturan baharu ditetapkan.

Alternatif papan pemuka

Pada halaman Fail, menu tindakan setiap folder mempunyai entri S3 CORS yang membuka editor berasaskan borang. Storan asas yang sama seperti endpoint REST ini dan seperti PutBucketCors melalui S3 API.