Mappák

A mappák a feltöltött fájljait rendezik az irányítópulton. Alapértelmezetten csak metaadatok — a fájlok megtartják saját CID-jüket, és nem kerülnek áthelyezésre az IPFS-en —, de egy mappáról pillanatképet is készíthet, hogy valódi UnixFS könyvtárrá alakítsa, és egyetlen CID-et kapjon az egészhez.

Mikor érdemes pillanatképet készíteni egy mappáról

A mappa pillanatkép egyetlen IPFS könyvtár CID, amely a mappa minden fájlját tartalmazza, névvel címezhetően. Ezzel a következőket teheti:

• Ossza meg az egész mappát egyetlen URL-lel: https://ipfs.ninja/ipfs/{dirCid}/
• Oldja fel közvetlenül a https://ipfs.ninja/ipfs/{dirCid}/photo.jpg címet (vagy bármely más gateway-en)
• Illessze be a CID-et egy ENS contenthash-be egy statikus webhely üzemeltetéséhez
• Használja NFT gyűjtemény alap CID-jeként, hogy minden token a ipfs://{dirCid}/<id>.json címre hivatkozzon
• Rögzítse a könyvtárat máshol is — a világ minden IPFS gateway-e tudja, hogyan oldjon fel egy UnixFS könyvtár CID-et

A pillanatképek tartalom-alapúan címzettek: azonos mappatartalom mindig ugyanazt a CID-et adja. Egy mappa, amit nem módosított, ugyanazt a CID-et adja, mint korábban. Egy fájl hozzáadása/eltávolítása/átnevezése új CID-et eredményez; az előző CID rögzítve és feloldható marad, amíg nem törli a fájljait.

Mappa létrehozása

POST /folders

Paraméter	Típus	Kötelező	Leírás
name	string	Igen	Megjelenítési név.
parentFolderId	string | null	Nem	Szülő mappa ID egymásba ágyazott mappákhoz. Hagyja el gyökérszintű mappához.

Példa

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

Visszaadja:

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

Az újonnan létrehozott mappáknak nincs pillanatképük. A latestSnapshot mező akkor jelenik meg a mappán, amikor meghívja a POST /folders/{id}/snapshot végpontot (lásd alább), valamint a későbbi GET /folders válaszokban.

Mappák listázása

GET /folders

Visszaadja a fiókjában lévő összes mappát, gyökérszintűt és egymásba ágyazottat egyaránt, mindegyikhez az utolsó pillanatkép CID-jével (ha van).

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

A fileCount a mappa jelenlegi tartalmát tükrözi; a latestSnapshot.fileCount az utolsó pillanatkép idejéni tartalmat. Ha eltérnek, a pillanatkép CID-je továbbra is feloldható, de elavult — készítsen új pillanatképet a frissítéshez.

Fájl áthelyezése egy mappába

PUT /files/{cid}/move

Paraméter	Típus	Kötelező	Leírás
folderId	string | null	Igen	Célmappa ID, vagy null a fájl gyökérbe helyezéséhez.

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

Mappa pillanatkép készítése (UnixFS könyvtár CID lekérése)

POST /folders/{folderId}/snapshot

Alakítsa a mappát valódi UnixFS könyvtárrá az IPFS klaszteren, és rögzítse az eredményt. Egy CID-et ad vissza az egész mappához. A gyermekek nevei az egyes fájlok fileName értékéből származnak; a duplikátumok ütközése automatikusan feloldásra kerül.

Nincs szükség kérés törzsre; az útvonal paraméter azonosítja a mappát.

Példa

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

Visszaadja:

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

A CID a mappa során is tárolásra kerül, így a későbbi GET /folders hívások latestSnapshot.cid-ként adják vissza, újabb pillanatkép nélkül is.

Egy pillanatkép feloldása

Ha egy pillanatkép rögzítésre került, a könyvtár CID bármely IPFS gateway-en keresztül feloldható. A legegyszerűbb URL-minta:

https://ipfs.ninja/ipfs/{dirCid}/         → könyvtárlistázás
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → az adott fájl

A klaszter rekurzívan rögzít, így a gyermekek is feloldhatók — még akkor is, ha később törli az eredeti fájlt a fiókjából, a pillanatkép másolata megmarad, mert az egy külön rögzítés, amely rekurzívan végigmegy a könyvtáron.

Újbóli pillanatképkészítés

Egy változatlan mappa újbóli pillanatképkészítése ugyanazt a CID-et adja vissza — a könyvtár CID-ek tartalom-alapúan címzettek, így azonos tartalom mindig ugyanazt a hash-t eredményezi, és a klaszter rögzítési hívása felismeri a duplikátumot, ami a végén no-op.

Megjegyzés: maga a pillanatkép útvonal nem ingyenes, még akkor sem, ha az eredmény ugyanaz a CID. Minden hívás visszaolvassa minden fájl byte-jait az IPFS-ről, és multipart formában újra feltölti azokat a klaszter /add végpontjára — itt történik a könyvtárba csomagolás. Tipikus mappáknál (≤100 kisebb fájl) ez néhány másodperc alatt lezajlik; nagyon nagy mappák esetén csak akkor érdemes pillanatképet készíteni, ha a tartalom valóban megváltozott.

Ha fájlokat adott hozzá vagy távolított el, majd pillanatképet készít, az eltérő CID-et eredményez; az előző továbbra is feloldható marad, amíg nem törli az alapul szolgáló fájljait.

Korlátok

• A mappának legalább egy fájlt tartalmaznia kell. Az üres mappák 400 — folder is empty hibát adnak.
• A fájlnév karakterei URL-kódoltak a multipart feltöltésben, amit a Kubo elfogad; a gateway URL-eknek százalék-kódolásra lehet szükségük a szóközökhöz vagy nem ASCII karakterekhez a fájlneveiben.
• A pillanatképek egyedi CID-enként pontosan egyszer számítanak bele a csomagja rögzítési összesítésébe — a fájlblokkok deduplikáltak, így a pillanatkép legtöbbször csak egy apró könyvtárcsomópontot ad hozzá a már rögzített fájlokhoz.

Mappa frissítése

PUT /folders/{folderId}

Paraméter	Típus	Kötelező	Leírás
name	string	Nem	Új megjelenítési név.
parentFolderId	string | null	Nem	A mappa új szülőjének beállítása. A null a gyökérbe helyezi.

Mappa törlése

DELETE /folders/{folderId}

Törli a mappát, és rekurzívan végigmegy minden benne lévő fájlon és almappán. Ugyanaz a megosztott CID biztonsági védelem vonatkozik rá, mint az egyedi fájltörlésekre — ha más felhasználók még mindig rögzítenek egy Ön által feltöltött CID-et, az Ön rögzítésének feloldása nem távolítja el azt náluk.

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

S3 CORS beállítása egy mappához / buckethez

Az S3-kompatibilis API-n keresztül elérhető mappák bucketként viselkednek. Ha ezt az API-t böngésző JavaScriptből vezérli, CORS szabályokra van szüksége a bucketen, hogy a böngésző preflightok átmenjenek. Két egyenértékű felület ugyanabba a tárolóba ír:

• PUT /folders/{folderId}/cors — ez a REST végpont, JWT-hitelesített (az irányítópult használja)
• S3 alerőforrás PUT /{bucket}?cors — SigV4-hitelesített (az AWS SDK-k használják, lásd s3-compatibility.md)

A PUT ezen a végponton egyúttal lefoglalja a mappa nevét globálisan egyedi bucket névként is, ha még nem volt lefoglalva.

PUT /folders/{folderId}/cors

Állítsa be a mappa S3 bucketjének CORS szabályait. Legfeljebb 5 szabály bucketenként, összesen 64 KB.

Paraméter	Típus	Kötelező	Leírás
rules	CorsRule[]	Igen	AWS-formátumú CORS szabályok tömbje (lásd alább). Nem lehet üres.
bucketName	string	Nem	Explicit S3 bucket név. Alapértelmezés szerint a mappa megjelenítési neve. Ha a kívánt név már globálisan foglalt, adjon meg itt egy alternatívát.

Minden CorsRule:

Mező	Típus	Kötelező	Leírás
AllowedOrigins	string[]	Igen	Kéréseket küldhető origin-ek. Wildcardokat támogat (https://*.myapp.com). Használjon *-ot bármely origin engedélyezéséhez.
AllowedMethods	string[]	Igen	Egy vagy több a GET, HEAD, PUT, POST, DELETE közül.
AllowedHeaders	string[]	Nem	A böngészők által a kérésekben megadható fejlécek. Alapértelmezett: egyik sem. Használja a ["*"]-ot az összes engedélyezéséhez (ajánlott az AWS SDK v3-hoz, amely Authorization, x-amz-* stb. fejléceket küld).
ExposeHeaders	string[]	Nem	A böngésző JavaScript számára olvashatóvá tett válasz fejlécek. Adja hozzá az ETag és x-amz-meta-cid fejléceket, ha az alkalmazásának szüksége van a visszaadott CID-re.
MaxAgeSeconds	number	Nem	Meddig gyorsítótárazzák a böngészők a preflight-ot. 0-86400. Alapértelmezett: 3600.
ID	string	Nem	Szabad szöveges címke a szabályhoz.

Példa kérés

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

Response 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

Visszaadja az aktuális CORS szabályokat, valamint a bucket nevét (ha lefoglalt).

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

DELETE /folders/{folderId}/cors

Eltávolítja az összes CORS szabályt. A bucket elleni böngésző preflightok új szabályok beállításáig zárt módban meghiúsulnak.

Irányítópult alternatíva

A Fájlok oldalon minden mappa műveletmenüjében van egy S3 CORS bejegyzés, amely egy űrlap-alapú szerkesztőt nyit meg. Ugyanaz az alapul szolgáló tároló, mint ennél a REST végpontnál és a PutBucketCors-nál az S3 API-n keresztül.