Mapes

Mapes organizē jūsu augšupielādētos failus informācijas panelī. Tās pēc noklusējuma ir tikai metadati — faili saglabā savus paša CID un netiek pārvietoti IPFS tīklā — bet jūs varat arī uzņemt mapes momentuzņēmumu (snapshot), lai to materializētu kā īstu UnixFS direktoriju un iegūtu vienu CID visam kopā.

Kad vajadzētu uzņemt mapes momentuzņēmumu

Mapes momentuzņēmums ir viens IPFS direktorijas CID, kas satur katru mapes failu, adresējamu pēc nosaukuma. Ar to jūs varat:

• Kopīgot visu mapi caur vienu URL: https://ipfs.ninja/ipfs/{dirCid}/
• Atrisināt https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (vai jebkuru citu gateway) tieši
• Ievietot CID ENS contenthash, lai izmitinātu statisku vietni
• Izmantot to kā NFT kolekcijas bāzes CID, lai katrs tokens atsauktos uz ipfs://{dirCid}/<id>.json
• Piespraust direktoriju jebkur citur — katrs IPFS gateway pasaulē zina, kā atrisināt UnixFS direktorijas CID

Momentuzņēmumi ir satura adresēti: identisks mapes saturs vienmēr rada to pašu CID. Atkārtoti uzņemot momentuzņēmumu mapei, ko neesat mainījis, atgriezīsies tas pats CID, kas atgriezts iepriekš. Faila pievienošana/noņemšana/pārdēvēšana rada jaunu CID; iepriekšējais CID paliek piesprausts un atrisināms, kamēr vien nedzēšat tā failus.

Izveidot mapi

POST /folders

Parametrs	Tips	Obligāts	Apraksts
name	string	Jā	Displeja nosaukums.
parentFolderId	string | null	Nē	Vecākmapes ID ligzdotām mapēm. Izlaidiet saknes līmeņa mapei.

Piemērs

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

Atgriež:

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

Tikko izveidotām mapēm nav momentuzņēmuma. Lauks latestSnapshot parādās mapei, tiklīdz izsaucat POST /folders/{id}/snapshot (skatiet zemāk) un turpmākajās GET /folders atbildēs.

Uzskaitīt mapes

GET /folders

Atgriež katru mapi jūsu kontā, gan saknes līmeņa, gan ligzdotu, ar katras pēdējā momentuzņēmuma CID (ja tāds ir).

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

fileCount atspoguļo mapes pašreizējo saturu; latestSnapshot.fileCount atspoguļo saturu pēdējā momentuzņēmuma uzņemšanas brīdī. Ja tie atšķiras, momentuzņēmuma CID joprojām atrisinās, bet ir novecojis — uzņemiet jaunu momentuzņēmumu, lai atsvaidzinātu.

Pārvietot failu uz mapi

PUT /files/{cid}/move

Parametrs	Tips	Obligāts	Apraksts
folderId	string | null	Jā	Mērķa mapes ID, vai null, lai pārvietotu failu uz sakni.

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

Uzņemt mapes momentuzņēmumu (iegūt UnixFS direktorijas CID)

POST /folders/{folderId}/snapshot

Materializējiet mapi kā īstu UnixFS direktoriju IPFS klasterī un piespraudiet rezultātu. Atgriež vienu CID visai mapei. Bērnelementu nosaukumi tiek ņemti no katra faila fileName; dublikāti tiek automātiski atrisināti.

Pieprasījuma ķermenis nav vajadzīgs; ceļa parametrs identificē mapi.

Piemērs

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

Atgriež:

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

CID tiek arī saglabāts mapes ierakstā, tāpēc turpmāki GET /folders izsaukumi to atgriež kā latestSnapshot.cid, neveidojot jaunu momentuzņēmumu.

Momentuzņēmuma atrisināšana

Kad momentuzņēmums ir piesprausts, direktorijas CID atrisinās caur jebkuru IPFS gateway. Vienkāršākais URL modelis:

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

Klasteris piespraužas rekursīvi, tāpēc bērnelementi arī ir atrisināmi — pat ja vēlāk izdzēšat oriģinālo failu no sava konta, momentuzņēmuma kopija saglabājas, jo tā ir atsevišķa piespraude, kas rekursīvi iet cauri direktorijai.

Atkārtota momentuzņēmuma uzņemšana

Atkārtoti uzņemot momentuzņēmumu nemainītai mapei, atgriezīsies tas pats CID — direktoriju CID ir satura adresēti, tāpēc identisks saturs vienmēr rada to pašu jaucējkodu, un klastera piespraušanas izsaukums atpazīst dublikātu un no tā puses ir bezdarbība.

Piezīme: pats momentuzņēmuma ceļš nav bez izmaksām pat tad, ja rezultāts ir tas pats CID. Katrs izsaukums nolasa katra faila baitus atpakaļ no IPFS un augšupielādē tos atkārtoti kā vairākdaļu uz klastera /add galapunktu — tur notiek ietīšana direktorijā. Tipiskām mapēm (≤100 mazu failu) tas joprojām pabeidzas dažu sekunžu laikā; ļoti lielām mapēm labāk izsaukt momentuzņēmumu tikai tad, kad saturs faktiski ir mainījies.

Momentuzņēmuma izsaukšana pēc failu pievienošanas vai noņemšanas rada citu CID; iepriekšējais turpina atrisināties, kamēr vien nedzēšat tā pamatā esošos failus.

Ierobežojumi

• Mapē jābūt vismaz vienam failam. Tukšas mapes atgriež 400 — folder is empty.
• Faila nosaukuma rakstzīmes tiek URL kodētas vairākdaļu augšupielādē, ko pieņem Kubo; gateway URL var būt nepieciešams procentu kodējums atstarpēm vai ne-ASCII rakstzīmēm jūsu faila nosaukumos.
• Momentuzņēmumi ieskaitās jūsu plāna piespraušanas kopsummā tieši vienreiz katram unikālam CID — faila bloki tiek de-dublicēti, tāpēc momentuzņēmums pārsvarā pievieno tikai nelielu direktorijas mezglu virs failiem, kurus jau piespraužat.

Atjaunināt mapi

PUT /folders/{folderId}

Parametrs	Tips	Obligāts	Apraksts
name	string	Nē	Jaunais displeja nosaukums.
parentFolderId	string | null	Nē	Mainīt mapes vecāku. null pārvieto to uz sakni.

Dzēst mapi

DELETE /folders/{folderId}

Dzēš mapi un rekursīvi kaskadē noņem katru tajā esošo failu un apakšmapi. Piemēro to pašu koplietotā CID drošības aizsardzību kā atsevišķu failu dzēšanai — ja citi lietotāji joprojām piespraudā jūsu augšupielādēto CID, jūsu atspraude to viņiem nenoņem.

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

Konfigurēt S3 CORS mapei / bucket

Mapes, kas atklātas caur S3 saderīgo API, darbojas kā bucket. Ja vadāt šo API no pārlūka JavaScript, jums jākonfigurē CORS noteikumi bucket, lai pārlūka preflight tiktu apstiprināts. Divas ekvivalentas virsmas saglabā to pašā krātuvē:

• PUT /folders/{folderId}/cors — šis REST galapunkts, autentificēts ar JWT (izmanto informācijas panelis)
• S3 apakšresurss PUT /{bucket}?cors — autentificēts ar SigV4 (izmanto AWS SDK, skatiet s3-compatibility.md)

PUT uz šo galapunktu arī pieprasa mapes nosaukumu kā globāli unikālu bucket, ja tas vēl nav pieprasīts.

PUT /folders/{folderId}/cors

Iestatiet CORS noteikumus mapes S3 bucket. Līdz 5 noteikumiem katram bucket, kopā 64 KB.

Parametrs	Tips	Obligāts	Apraksts
rules	CorsRule[]	Jā	AWS formas CORS noteikumu masīvs (skatiet zemāk). Nedrīkst būt tukšs.
bucketName	string	Nē	Skaidrs S3 bucket nosaukums. Pēc noklusējuma — mapes displeja nosaukums. Ja vēlamais nosaukums jau ir globāli pieprasīts, norādiet šeit alternatīvu.

Katrs CorsRule:

Lauks	Tips	Obligāts	Apraksts
AllowedOrigins	string[]	Jā	Izcelsmes, kurām atļauts sūtīt pieprasījumus. Atbalsta aizstājējzīmes (https://*.myapp.com). Izmantojiet * jebkurai izcelsmei.
AllowedMethods	string[]	Jā	Viena vai vairākas no GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nē	Galvenes, ko pārlūki drīkst iekļaut pieprasījumos. Noklusējums: nav. Izmantojiet ["*"], lai atļautu visas (ieteicams AWS SDK v3, kas sūta Authorization, x-amz-* u.c.).
ExposeHeaders	string[]	Nē	Atbildes galvenes, padarītas lasāmas pārlūka JavaScript. Iekļaujiet ETag un x-amz-meta-cid, ja jūsu lietotnei vajadzīgs atgrieztais CID.
MaxAgeSeconds	number	Nē	Cik ilgi pārlūki kešo preflight. 0-86400. Noklusējums 3600.
ID	string	Nē	Brīvi izvēlēta noteikuma etiķete.

Pieprasījuma piemērs

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

Atbilde 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

Atgriež pašreizējos CORS noteikumus un bucket nosaukumu (ja pieprasīts).

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

DELETE /folders/{folderId}/cors

Noņem visus CORS noteikumus. Pārlūka preflight pieprasījumi pret bucket neizdosies, kamēr netiks iestatīti jauni noteikumi.

Alternatīva informācijas panelī

Failu lapā katras mapes darbību izvēlnē ir ieraksts S3 CORS, kas atver formā balstītu redaktoru. Tā pati pamatā esošā krātuve kā šim REST galapunktam un PutBucketCors caur S3 API.