Mape

Mape organizirajo vaše naložene datoteke v nadzorni plošči. Privzeto vsebujejo samo metapodatke — datoteke ohranijo lastne CID-je in niso premaknjene na IPFS-u — vendar lahko posnamete mapo in jo materializirate kot pravi UnixFS imenik ter dobite en CID za celoten sklop.

Kdaj bi posneli mapo

Posnetek mape je en sam CID IPFS imenika, ki vsebuje vse datoteke v mapi, naslovljive po imenu. Z njim lahko:

• Delite celotno mapo prek enega URL-ja: https://ipfs.ninja/ipfs/{dirCid}/
• Neposredno razrešite https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (ali prek katerega koli drugega prehoda)
• Vstavite CID v ENS contenthash za gostovanje statične spletne strani
• Uporabite ga kot osnovni CID zbirke NFT, tako da vsak žeton kaže na ipfs://{dirCid}/<id>.json
• Pripnete imenik kjer koli drugje — vsak IPFS prehod na svetu zna razrešiti CID UnixFS imenika

Posnetki so naslovljeni po vsebini: enaka vsebina mape vedno proizvede isti CID. Ponovno snemanje mape, ki je niste spreminjali, vrne isti CID kot prej. Dodajanje/odstranjevanje/preimenovanje datoteke ustvari nov CID; prejšnji CID ostane pripet in razrešljiv, dokler ne izbrišete njegovih datotek.

Ustvarjanje mape

POST /folders

Parameter	Tip	Obvezno	Opis
name	string	Da	Prikazno ime.
parentFolderId	string | null	Ne	ID nadrejene mape za gnezdene mape. Izpustite za mapo na korenski ravni.

Primer

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

Vrne:

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

Novo ustvarjene mape nimajo posnetka. Polje latestSnapshot se pojavi na mapi, ko pokličete POST /folders/{id}/snapshot (glejte spodaj), in v poznejših odgovorih GET /folders.

Seznam map

GET /folders

Vrne vsako mapo v vašem računu, na korenski ravni in gnezdeno, s CID-jem zadnjega posnetka za vsako (če obstaja).

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

fileCount odraža trenutno vsebino mape; latestSnapshot.fileCount odraža vsebino v času zadnjega posnetka. Če se razlikujeta, se CID posnetka še vedno razreši, vendar je zastarel — ponovno posnemite za osvežitev.

Premikanje datoteke v mapo

PUT /files/{cid}/move

Parameter	Tip	Obvezno	Opis
folderId	string | null	Da	ID ciljne mape ali null za premik datoteke v koren.

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

Snemanje mape (pridobitev CID UnixFS imenika)

POST /folders/{folderId}/snapshot

Materializira mapo kot pravi UnixFS imenik na IPFS grozdu in rezultat pripne. Vrne en CID za celotno mapo. Imena otrok izhajajo iz fileName vsake datoteke; dvojniki se samodejno razrešijo brez trkov.

Telo zahteve ni potrebno; parameter poti identificira mapo.

Primer

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

Vrne:

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

CID se prav tako shrani na vrstici mape, tako da ga poznejši klici GET /folders vrnejo kot latestSnapshot.cid, ne da bi bilo potrebno novo snemanje.

Razreševanje posnetka

Ko je posnetek pripet, se CID imenika razreši prek katerega koli IPFS prehoda. Najpreprostejši vzorec URL-ja:

https://ipfs.ninja/ipfs/{dirCid}/         → seznam imenika
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → ta ena datoteka

Grozd pripenja rekurzivno, tako da so tudi otroci razrešljivi — tudi če pozneje izbrišete izvirno datoteko iz svojega računa, kopija v posnetku preživi, ker je ločeno pripenjanje, ki rekurzivno prehaja skozi imenik.

Ponovno snemanje

Ponovno snemanje nespremenjene mape vrne isti CID — CID-ji imenikov so naslovljeni po vsebini, tako da enaka vsebina vedno proizvede isto zgoščeno vrednost, in klic pripenjanja v grozdu prepozna dvojnik ter je na njegovi strani prazna operacija.

Opomba: pot snemanja sama po sebi ni brezplačna, tudi ko je rezultat isti CID. Vsak klic prebere bajte vsake datoteke nazaj iz IPFS-a in jih ponovno naloži kot večdelno vsebino na končno točko /add grozda — tam se izvede ovijanje z imenikom (wrap-with-directory). Za tipične mape (≤100 majhnih datotek) se to še vedno zaključi v nekaj sekundah; za zelo velike mape raje pokličite snemanje samo, ko se vsebina dejansko spremeni.

Klic snemanja po dodajanju ali odstranjevanju datotek proizvede drugačen CID; prejšnji se še naprej razreši, dokler ne izbrišete njegovih temeljnih datotek.

Omejitve

• Mapa mora vsebovati vsaj eno datoteko. Prazne mape vrnejo 400 — folder is empty.
• Znaki v imenih datotek so URL-kodirani v večdelnem nalaganju, ki ga sprejema Kubo; URL-ji prehoda lahko potrebujejo procentno kodiranje za presledke ali znake, ki niso ASCII, v vaših imenih datotek.
• Posnetki se štejejo v skupno število pripenjanj vašega načrta natanko enkrat na edinstven CID — bloki datotek so deduplicirani, tako da posnetek večinoma doda le majhno vozlišče imenika povrh datotek, ki jih že pripenjate.

Posodobitev mape

PUT /folders/{folderId}

Parameter	Tip	Obvezno	Opis
name	string	Ne	Novo prikazno ime.
parentFolderId	string | null	Ne	Ponovno določi nadrejeno mapo. null jo premakne v koren.

Brisanje mape

DELETE /folders/{folderId}

Izbriše mapo in rekurzivno kaskadno izbriše vsako datoteko in podmapo, ki jo vsebuje. Za brisanje velja enak varnostni ukrep za deljene CID-je kot pri posameznih brisanjih datotek — če drugi uporabniki še vedno pripenjajo CID, ki ste ga naložili, vaš odpin ne odstrani vsebine zanje.

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

Konfiguracija S3 CORS za mapo / vedro

Mape, izpostavljene prek S3-združljivega API-ja, delujejo kot vedra. Če ta API poganjate iz brskalniškega JavaScripta, potrebujete CORS pravila na vedru, da prehodne preverbe (preflight) v brskalniku uspejo. Dva enakovredna vmesnika shranjujeta v isto zbirko:

• PUT /folders/{folderId}/cors — ta REST končna točka, avtenticirana z JWT (uporablja jo nadzorna plošča)
• S3 podvir PUT /{bucket}?cors — avtenticiran s SigV4 (uporabljajo ga AWS SDK-ji, glejte s3-compatibility.md)

PUT na tej končni točki tudi zahteva ime mape kot globalno edinstveno ime vedra, če to še ni zahtevano.

PUT /folders/{folderId}/cors

Nastavi CORS pravila za S3 vedro mape. Do 5 pravil na vedro, skupaj 64 KB.

Parameter	Tip	Obvezno	Opis
rules	CorsRule[]	Da	Polje CORS pravil v obliki AWS (glejte spodaj). Ne sme biti prazno.
bucketName	string	Ne	Eksplicitno ime S3 vedra. Privzeto je prikazno ime mape. Če je želeno ime že globalno zasedeno, tukaj podajte alternativo.

Vsako CorsRule:

Polje	Tip	Obvezno	Opis
AllowedOrigins	string[]	Da	Izvori, ki lahko pošiljajo zahteve. Podpira nadomestne znake (https://*.myapp.com). Uporabite * za kateri koli izvor.
AllowedMethods	string[]	Da	Eden ali več od GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Ne	Glave, ki jih brskalniki lahko vključijo v zahteve. Privzeto: nobene. Uporabite ["*"], da dovolite vse (priporočeno za AWS SDK v3, ki pošilja Authorization, x-amz-* itd.).
ExposeHeaders	string[]	Ne	Glave odgovora, ki so berljive brskalniškemu JavaScriptu. Vključite ETag in x-amz-meta-cid, če vaša aplikacija potrebuje vrnjeni CID.
MaxAgeSeconds	number	Ne	Kako dolgo brskalniki predpomnijo prehodno preverbo. 0-86400. Privzeto 3600.
ID	string	Ne	Prostotekstna oznaka za pravilo.

Primer zahteve

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

Odgovor 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

Vrne trenutna CORS pravila in ime vedra (če je zahtevano).

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

DELETE /folders/{folderId}/cors

Odstrani vsa CORS pravila. Prehodne preverbe brskalnika proti vedru bodo zaprte, dokler niso nastavljena nova pravila.

Alternativa v nadzorni plošči

Na strani Datoteke ima meni dejanj vsake mape vnos S3 CORS, ki odpre urejevalnik v obliki obrazca. Ista temeljna zbirka kot ta REST končna točka in kot PutBucketCors prek S3 API-ja.