Aplankai

Aplankai tvarko jūsų įkeltus failus prietaisų skydelyje. Pagal numatytuosius nustatymus jie yra tik metaduomenys — failai išlaiko savo CID ir nėra perkeliami IPFS tinkle — tačiau taip pat galite padaryti aplanko momentinę nuotrauką (snapshot), kad jį materializuotumėte kaip tikrą UnixFS katalogą ir gautumėte vieną CID visam turiniui.

Kada verta daryti aplanko momentinę nuotrauką

Aplanko momentinė nuotrauka (snapshot) yra vienas IPFS katalogo CID, kuris apima kiekvieną aplanko failą, adresuojamą pagal pavadinimą. Su juo galite:

• Bendrinti visą aplanką per vieną URL: https://ipfs.ninja/ipfs/{dirCid}/
• Tiesiogiai išspręsti https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (arba per bet kurį kitą gateway)
• Įdėti CID į ENS contenthash statiniai svetainei talpinti
• Naudoti jį kaip NFT kolekcijos bazinį CID, kad kiekvienas žetonas nurodytų ipfs://{dirCid}/<id>.json
• Prisegti katalogą bet kur kitur — kiekvienas IPFS gateway pasaulyje žino, kaip išspręsti UnixFS katalogo CID

Momentinės nuotraukos yra turiniu adresuojamos: identiškas aplanko turinys visada duoda tą patį CID. Pakartotinai darant nepakeisto aplanko momentinę nuotrauką grąžinamas tas pats CID, koks buvo grąžintas anksčiau. Pridėjus/pašalinus/pervadinus failą sukuriamas naujas CID; ankstesnis CID lieka prisegtas ir išsprendžiamas tol, kol neištrinate jo failų.

Sukurti aplanką

POST /folders

Parametras	Tipas	Privalomas	Aprašymas
name	string	Taip	Rodomas pavadinimas.
parentFolderId	string | null	Ne	Tėvinio aplanko ID įdėtiniams aplankams. Praleiskite šakniniam (root) aplankui.

Pavyzdys

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

Grąžina:

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

Naujai sukurti aplankai neturi momentinės nuotraukos. Laukas latestSnapshot atsiranda aplanke, kai iškviečiate POST /folders/{id}/snapshot (žr. žemiau), taip pat vėlesniuose GET /folders atsakymuose.

Pateikti aplankų sąrašą

GET /folders

Grąžina kiekvieną jūsų paskyros aplanką, tiek šakninio lygio, tiek įdėtinius, su paskutinės momentinės nuotraukos CID kiekvienam (jei yra).

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

fileCount atspindi dabartinį aplanko turinį; latestSnapshot.fileCount atspindi turinį paskutinės momentinės nuotraukos metu. Jei jie skiriasi, momentinės nuotraukos CID vis tiek išsprendžiamas, bet yra pasenęs — padarykite naują momentinę nuotrauką, kad atnaujintumėte.

Perkelti failą į aplanką

PUT /files/{cid}/move

Parametras	Tipas	Privalomas	Aprašymas
folderId	string | null	Taip	Paskirties aplanko ID, arba null, kad perkeltumėte failą į šaknį.

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

Padaryti aplanko momentinę nuotrauką (gauti UnixFS katalogo CID)

POST /folders/{folderId}/snapshot

Materializuoja aplanką kaip tikrą UnixFS katalogą IPFS klasteryje ir prisega rezultatą. Grąžina vieną CID visam aplankui. Vaikinių elementų pavadinimai gaunami iš kiekvieno failo fileName; dublikatai automatiškai išskiriami.

Užklausos turinys nereikalingas; kelio parametras identifikuoja aplanką.

Pavyzdys

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

Grąžina:

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

CID taip pat išsaugomas aplanko įraše, todėl vėlesni GET /folders iškvietimai grąžina jį kaip latestSnapshot.cid be poreikio daryti dar vieną momentinę nuotrauką.

Momentinės nuotraukos išsprendimas

Kai momentinė nuotrauka prisegta, katalogo CID išsprendžiamas per bet kurį IPFS gateway. Paprasčiausias URL šablonas:

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

Klasteris prisega rekursyviai, todėl vaikiniai elementai taip pat išsprendžiami — net jei vėliau ištrinsite originalų failą iš savo paskyros, momentinės nuotraukos kopija išlieka, nes tai atskiras prisegimas, rekursuojantis per katalogą.

Pakartotinis momentinės nuotraukos darymas

Pakartotinai darant nepakeisto aplanko momentinę nuotrauką grąžinamas tas pats CID — katalogo CID yra turiniu adresuojami, todėl identiškas turinys visada duoda tą pačią maišą, ir klasterio prisegimo iškvietimas atpažįsta dublikatą bei nedaro nieko naujo.

Pastaba: pats momentinės nuotraukos kelias nėra nemokamas, net jei rezultatas yra tas pats CID. Kiekvienas iškvietimas nuskaito kiekvieno failo baitus iš IPFS ir vėl juos įkelia kaip multipart į klasterio /add galinį tašką — būtent ten vyksta suvyniojimas į katalogą. Įprastiems aplankams (≤100 mažų failų) tai vis dar užtrunka kelias sekundes; labai dideliems aplankams geriau iškviesti momentinę nuotrauką tik tada, kai turinys iš tikrųjų pasikeitė.

Iškvietus momentinę nuotrauką po failų pridėjimo ar pašalinimo gaunamas kitoks CID; ankstesnis toliau išsprendžiamas tol, kol neištrinate jo pagrindinių failų.

Ribos

• Aplanke turi būti bent vienas failas. Tušti aplankai grąžina 400 — folder is empty.
• Failo pavadinimo simboliai yra URL užkoduojami multipart įkėlime, kurį priima Kubo; gateway URL gali reikėti procentinio kodavimo tarpams ar ne ASCII simboliams jūsų failų pavadinimuose.
• Momentinės nuotraukos skaičiuojamos į jūsų plano prisegimų limitą lygiai vieną kartą kiekvienam unikaliam CID — failų blokai yra dedublikuojami, todėl momentinė nuotrauka daugiausia prideda mažą katalogo mazgą virš failų, kuriuos jau prisegate.

Atnaujinti aplanką

PUT /folders/{folderId}

Parametras	Tipas	Privalomas	Aprašymas
name	string	Ne	Naujas rodomas pavadinimas.
parentFolderId	string | null	Ne	Pakeisti aplanko tėvinį aplanką. null perkelia jį į šaknį.

Ištrinti aplanką

DELETE /folders/{folderId}

Ištrina aplanką ir rekursyviai peržengia kiekvieną jame esantį failą ir poaplankį. Taikomas tas pats bendro CID saugumo apsaugos mechanizmas kaip ir atskirų failų trynimui — jei kiti naudotojai vis dar prisega jūsų įkeltą CID, jūsų atsegimas jo jiems nepašalina.

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

Konfigūruoti S3 CORS aplankui / bucket

Aplankai, atveriami per S3 suderinamą API, veikia kaip bucket. Jei tą API valdote iš naršyklės JavaScript, jums reikia CORS taisyklių bucket, kad naršyklės preflight užklausos praeitų. Dvi lygiavertės sąsajos išsaugo į tą pačią saugyklą:

• PUT /folders/{folderId}/cors — šis REST galinis taškas, autentifikuojamas JWT (naudojamas prietaisų skydelio)
• S3 subresursas PUT /{bucket}?cors — autentifikuojamas SigV4 (naudojamas AWS SDK, žr. s3-compatibility.md)

PUT šiame galiniame taške taip pat užsiima aplanko pavadinimą kaip globaliai unikalų bucket, jei jis dar nebuvo užimtas.

PUT /folders/{folderId}/cors

Nustato CORS taisykles aplanko S3 bucket. Iki 5 taisyklių vienam bucket, iš viso 64 KB.

Parametras	Tipas	Privalomas	Aprašymas
rules	CorsRule[]	Taip	AWS formos CORS taisyklių masyvas (žr. žemiau). Ne tuščias.
bucketName	string	Ne	Aiškus S3 bucket pavadinimas. Numatytasis — aplanko rodomas pavadinimas. Jei norimas pavadinimas jau užimtas globaliai, perduokite čia alternatyvą.

Kiekvienas CorsRule:

Laukas	Tipas	Privalomas	Aprašymas
AllowedOrigins	string[]	Taip	Kilmės, kurioms leidžiama siųsti užklausas. Palaiko pakaitos simbolius (https://*.myapp.com). Naudokite * bet kuriai kilmei.
AllowedMethods	string[]	Taip	Vienas ar daugiau iš GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Ne	Antraštės, kurias naršyklės gali įtraukti į užklausas. Numatytasis — jokių. Naudokite ["*"], kad leistumėte visas (rekomenduojama AWS SDK v3, kuris siunčia Authorization, x-amz-* ir kt.).
ExposeHeaders	string[]	Ne	Atsakymo antraštės, padarytos skaitomos naršyklės JavaScript. Įtraukite ETag ir x-amz-meta-cid, jei jūsų programai reikia grąžinto CID.
MaxAgeSeconds	number	Ne	Kiek laiko naršyklės talpina preflight rezultatą podėlyje. 0-86400. Numatytasis 3600.
ID	string	Ne	Laisvo teksto taisyklės žymė.

Užklausos pavyzdys

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

Atsakymas 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

Grąžina dabartines CORS taisykles bei bucket pavadinimą (jei užimtas).

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

DELETE /folders/{folderId}/cors

Pašalina visas CORS taisykles. Naršyklės preflight užklausos į bucket nepavyks (fail closed), kol nebus nustatytos naujos taisyklės.

Alternatyva prietaisų skydelyje

Failų puslapyje kiekvieno aplanko veiksmų meniu turi įrašą S3 CORS, kuris atveria formos pagrindu veikiantį redaktorių. Ta pati pagrindinė saugykla kaip šio REST galinio taško ir kaip PutBucketCors per S3 API.