Kaustad

Kaustad korraldavad sinu üleslaaditud faile töölaual. Vaikimisi on need ainult metaandmed — failid säilitavad oma CID-d ega liigu IPFS-is —, kuid saad ka kaustast hetktõmmise teha, et materialiseerida see reaalse UnixFS-kataloogina ja saada terve kausta jaoks üks CID.

Millal kaustast hetktõmmist teha

Kausta hetktõmmis on üksik IPFS-kataloogi CID, mis sisaldab kõiki kausta faile, nime järgi adresseeritavana. Sellega saad:

• Jagada kogu kausta ühe URL-i kaudu: https://ipfs.ninja/ipfs/{dirCid}/
• Lahendada https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (või mis tahes muu gateway) otse
• Panna CID-i ENS contenthash'i staatilise saidi majutamiseks
• Kasutada seda NFT-kollektsiooni baas-CID-na, nii et iga token viitab ipfs://{dirCid}/<id>.json
• Kinnitada kataloogi kus tahes mujal — iga maailma IPFS gateway teab, kuidas UnixFS-kataloogi CID-i lahendada

Hetktõmmised on sisupõhiselt adresseeritud: identsed kausta sisud toodavad alati sama CID-i. Muutmata kaustast uue hetktõmmise tegemine tagastab sama CID-i, mille see varem tagastas. Faili lisamine/eemaldamine/ümbernimetamine toodab uue CID-i; eelmine CID jääb kinnitatuks ja lahendatavaks seni, kuni te ei kustuta selle faile.

Looge kaust

POST /folders

Parameeter	Tüüp	Nõutud	Kirjeldus
name	string	Jah	Kuvatav nimi.
parentFolderId	string | null	Ei	Vanemkausta ID pesastatud kaustade jaoks. Jätke välja juurtasandi kausta jaoks.

Näide

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" }'

Tagastab:

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

Äsja loodud kaustadel pole hetktõmmist. Väli latestSnapshot ilmub kaustale pärast POST /folders/{id}/snapshot kutsumist (vt allpool) ja järgnevates GET /folders vastustes.

Loetlege kaustad

GET /folders

Tagastab iga kausta sinu kontol, nii juurtasandil kui pesastatud, koos iga kausta viimase hetktõmmise CID-ga (kui see on olemas).

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

fileCount peegeldab kausta praegust sisu; latestSnapshot.fileCount peegeldab sisu viimase hetktõmmise ajal. Kui need erinevad, lahendub hetktõmmise CID endiselt, kuid on aegunud — tee uus hetktõmmis värskendamiseks.

Liigutage fail kausta

PUT /files/{cid}/move

Parameeter	Tüüp	Nõutud	Kirjeldus
folderId	string | null	Jah	Sihtkausta ID, või null, et liigutada fail juurtasandile.

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-…" }'

Tehke kaustast hetktõmmis (hankige UnixFS-kataloogi CID)

POST /folders/{folderId}/snapshot

Materialiseerige kaust reaalse UnixFS-kataloogina IPFS-klastris ja kinnitage tulemus. Tagastab ühe CID-i kogu kausta jaoks. Laste nimed tulevad iga faili fileName-väljast; duplikaadid eristatakse automaatselt.

Päringu keha pole vaja; tee parameeter identifitseerib kausta.

Näide

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

Tagastab:

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

CID salvestatakse ka kausta reale, nii et järgnevad GET /folders kutsed tagastavad selle väljal latestSnapshot.cid ilma uut hetktõmmist tegemata.

Hetktõmmise lahendamine

Kui hetktõmmis on kinnitatud, lahendub kataloogi CID mis tahes IPFS gateway kaudu. Lihtsaim URL-muster:

https://ipfs.ninja/ipfs/{dirCid}/         → directory listing
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → that one file

Klaster kinnitab rekursiivselt, nii et lapsed on samuti lahendatavad — isegi kui kustutate hiljem algfaili oma kontolt, jääb hetktõmmise koopia püsima, kuna see on eraldi kinnitus, mis kordub läbi kataloogi.

Uue hetktõmmise tegemine

Muutmata kaustast uue hetktõmmise tegemine tagastab sama CID-i — kataloogi CID-d on sisupõhiselt adresseeritud, nii et identne sisu toodab alati sama räsi, ja klastri kinnituskutse tunneb duplikaadi ära ning selle poolel on see tegevusetu.

Märkus: hetktõmmise tee ise ei ole tasuta ka siis, kui tulemus on sama CID. Iga kutse loeb iga faili baite tagasi IPFS-ist ja laadib need uuesti mitmeosalisena klastri /add lõpp-punkti — seal toimub kataloogiga mähkimine. Tavaliste kaustade puhul (≤100 väikest faili) lõpeb see ikka mõne sekundiga; väga suurte kaustade puhul tee hetktõmmis ainult siis, kui sisu tegelikult muutus.

Hetktõmmise tegemine pärast failide lisamist või eemaldamist toodab erineva CID-i; eelmine jätkab lahendamist seni, kuni te ei kustuta selle aluseks olevaid faile.

Piirangud

• Kaust peab sisaldama vähemalt ühte faili. Tühjad kaustad tagastavad 400 — folder is empty.
• Failinime tähemärgid on URL-kodeeritud mitmeosalises üleslaadimises, mida Kubo aktsepteerib; gateway URL-id võivad vajada protsent-kodeeringut tühikute või mitte-ASCII tähemärkide jaoks teie failinimedes.
• Hetktõmmised arvestatakse teie plaani kinnituste kogusumma hulka täpselt üks kord unikaalse CID kohta — failiplokid deduplitseeritakse, nii et hetktõmmis lisab enamasti vaid väikese kataloogisõlme failidele, mida juba kinnitate.

Uuendage kausta

PUT /folders/{folderId}

Parameeter	Tüüp	Nõutud	Kirjeldus
name	string	Ei	Uus kuvatav nimi.
parentFolderId	string | null	Ei	Muutke kausta vanemat. null liigutab selle juurtasandile.

Kustutage kaust

DELETE /folders/{folderId}

Kustutab kausta ja kaskaadib rekursiivselt läbi kõigi selles sisalduvate failide ja alamkaustade. Kehtib sama jagatud-CID turvakaitse, mis üksikute failide kustutamisel — kui teised kasutajad kinnitavad ikka CID-i, mille te üles laadisite, ei eemalda teie kinnituse tühistamine seda nende jaoks.

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

Konfigureerige S3 CORS kausta / bucket'i jaoks

Kaustad, mis on paljastatud S3-ühilduva API kaudu, toimivad bucket'itena. Kui juhite seda API-t brauseri JavaScript-ist, vajate bucket'il CORS-reegleid, et brauseri preflight-päringud läbiksid. Kaks samaväärset liidest säilitavad sama poe:

• PUT /folders/{folderId}/cors — see REST lõpp-punkt, JWT-autenditud (kasutab töölaud)
• S3 alamressurss PUT /{bucket}?cors — SigV4-autenditud (kasutavad AWS SDK-d, vt s3-compatibility.md)

PUT sellel lõpp-punktil ka omastab kausta nime globaalselt unikaalse bucket'ina, kui see pole veel omastatud.

PUT /folders/{folderId}/cors

Määrake kausta S3 bucket'i CORS-reeglid. Kuni 5 reeglit bucket'i kohta, 64 KB kokku.

Parameeter	Tüüp	Nõutud	Kirjeldus
rules	CorsRule[]	Jah	AWS-kujuliste CORS-reeglite massiiv (vt allpool). Mittetühi.
bucketName	string	Ei	Selgesõnaline S3 bucket'i nimi. Vaikimisi kausta kuvatav nimi. Kui soovitud nimi on juba globaalselt omastatud, edastage siin alternatiiv.

Iga CorsRule:

Väli	Tüüp	Nõutud	Kirjeldus
AllowedOrigins	string[]	Jah	Päritolud, kellel on lubatud päringuid saata. Toetab metamärke (https://*.myapp.com). Kasuta * mis tahes päritolu jaoks.
AllowedMethods	string[]	Jah	Üks või mitu: GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Ei	Päised, mida brauserid võivad päringutesse lisada. Vaikimisi: puudub. Kasuta ["*"], et lubada kõik (soovitatav AWS SDK v3-le, mis saadab Authorization, x-amz-* jne).
ExposeHeaders	string[]	Ei	Vastuse päised, mis muudetakse brauseri JavaScript-ile loetavaks. Lisa ETag ja x-amz-meta-cid, kui su rakendus vajab tagastatud CID-i.
MaxAgeSeconds	number	Ei	Kui kaua brauserid preflight'i vahemällu salvestavad. 0-86400. Vaikimisi 3600.
ID	string	Ei	Vabatekstiline silt reeglile.

Näidispäring

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
    }]
  }'

Vastus 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

Tagastab praegused CORS-reeglid pluss bucket'i nime (kui see on omastatud).

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

DELETE /folders/{folderId}/cors

Eemaldab kõik CORS-reeglid. Brauseri preflight-päringud bucket'i vastu ebaõnnestuvad, kuni uued reeglid on määratud.

Töölaua alternatiiv

Failide lehel on igas kausta toimingumenüüs kirje S3 CORS, mis avab vormipõhise redaktori. Sama aluseks olev pood, mis sellel REST lõpp-punktil ja PutBucketCors-il S3 API kaudu.