Mapper

Mapper organiserer dine uploadede filer i dashboardet. De er kun metadata som standard — filer beholder deres egne CID'er og flyttes ikke på IPFS — men du kan også tage et snapshot af en mappe for at materialisere den som en rigtig UnixFS-mappe og få ét CID for det hele.

Hvornår du skal snapshotte en mappe

Et mappe-snapshot er ét IPFS-mappe-CID, der indeholder hver fil i mappen, adresserbar efter navn. Med det kan du:

• Dele hele mappen via én URL: https://ipfs.ninja/ipfs/{dirCid}/
• Opløse https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (eller enhver anden gateway) direkte
• Sætte CID'et ind i en ENS-contenthash for at hoste et statisk websted
• Bruge det som base-CID for en NFT-samling, så hver token refererer til ipfs://{dirCid}/<id>.json
• Fastgøre mappen andre steder — enhver IPFS-gateway i verden ved, hvordan man opløser et UnixFS-mappe-CID

Snapshots er indholdsadresserede: identisk mappeindhold producerer altid det samme CID. Gentag et snapshot af en mappe, du ikke har ændret, og du får det samme CID, som du fik før. Tilføjelse/fjernelse/omdøbning af en fil producerer et nyt CID; det forrige CID forbliver fastgjort og opløseligt, så længe du ikke sletter dets filer.

Opret mappe

POST /folders

Parameter	Type	Påkrævet	Beskrivelse
name	string	Ja	Visningsnavn.
parentFolderId	string | null	Nej	Overordnet mappe-ID for indlejrede mapper. Udelad for en rodmappe.

Eksempel

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

Returnerer:

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

Nyoprettede mapper har intet snapshot. Feltet latestSnapshot vises på mappen, når du kalder POST /folders/{id}/snapshot (se nedenfor), og på efterfølgende GET /folders-svar.

List mapper

GET /folders

Returnerer alle mapper i din konto, både på rodniveau og indlejrede, med det seneste snapshot-CID for hver (hvis nogen).

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

fileCount afspejler mappens nuværende indhold; latestSnapshot.fileCount afspejler indholdet på tidspunktet for det seneste snapshot. Hvis de afviger, opløses snapshot-CID'et stadig, men er forældet — tag et nyt snapshot for at opdatere det.

Flyt en fil til en mappe

PUT /files/{cid}/move

Parameter	Type	Påkrævet	Beskrivelse
folderId	string | null	Ja	Mål-mappe-ID, eller null for at flytte filen til roden.

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

Tag et snapshot af en mappe (få et UnixFS-mappe-CID)

POST /folders/{folderId}/snapshot

Materialiser mappen som en rigtig UnixFS-mappe på IPFS-klyngen og fastgør resultatet. Returnerer ét CID for hele mappen. Navne på underliggende elementer kommer fra hver fils fileName; dubletter afkollideres automatisk.

Ingen forespørgselskrop er nødvendig; stiparameteren identificerer mappen.

Eksempel

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

Returnerer:

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

CID'et gemmes også på mapperækken, så efterfølgende GET /folders-kald returnerer det som latestSnapshot.cid uden behov for endnu et snapshot.

Opløsning af et snapshot

Når et snapshot er fastgjort, opløses mappe-CID'et via enhver IPFS-gateway. Det simpleste URL-mønster:

https://ipfs.ninja/ipfs/{dirCid}/         → mappevisning
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → den ene fil

Klyngen fastgør rekursivt, så underliggende elementer også kan opløses — selv hvis du senere sletter den oprindelige fil fra din konto, overlever snapshottets kopi, fordi det er en separat fastgørelse, der rekurserer gennem mappen.

Gentagelse af snapshot

Gentagelse af et snapshot af en uændret mappe returnerer det samme CID — mappe-CID'er er indholdsadresserede, så identisk indhold producerer altid den samme hash, og klyngens fastgørelseskald genkender dubletten og er en no-op i den ende.

Bemærk: selve snapshot-stien er ikke gratis, selvom resultatet er det samme CID. Hvert kald læser hver fils bytes tilbage fra IPFS og genuploader dem som en multipart til klyngens /add-endpoint — det er der, indpakning-med-mappe sker. For typiske mapper (≤100 små filer) er dette stadig færdigt på et par sekunder; for meget store mapper er det bedst kun at kalde snapshot, når indholdet faktisk er ændret.

Kald af snapshot, efter du har tilføjet eller fjernet filer, producerer et andet CID; det forrige fortsætter med at kunne opløses, så længe du ikke sletter dets underliggende filer.

Begrænsninger

• Mappen skal indeholde mindst én fil. Tomme mapper returnerer 400 — folder is empty.
• Filnavne-tegn URL-kodes i den multipart-upload, Kubo accepterer; gateway-URL'er kan kræve procent-kodning for mellemrum eller ikke-ASCII-tegn i dine filnavne.
• Snapshots tæller mod dit plans samlede antal fastgørelser præcis én gang per unikt CID — filblokke deduplikeres, så snapshottet mest tilføjer en lille mappe-node oven på filer, du allerede fastgør.

Opdater en mappe

PUT /folders/{folderId}

Parameter	Type	Påkrævet	Beskrivelse
name	string	Nej	Nyt visningsnavn.
parentFolderId	string | null	Nej	Flyt mappen til en ny overordnet mappe. null flytter den til roden.

Slet en mappe

DELETE /folders/{folderId}

Sletter mappen og kaskaderer rekursivt gennem hver fil og undermappe, den indeholder. Underlagt den samme delte-CID-sikkerhedskontrol som individuelle filsletninger — hvis andre brugere stadig fastgør et CID, du uploadede, fjerner din afgørelse ikke fastgørelsen for dem.

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

Konfigurer S3 CORS for en mappe/bucket

Mapper eksponeret via det S3-kompatible API fungerer som buckets. Hvis du styrer det API fra browser-JavaScript, skal du have CORS-regler på bucket'en, så browser-preflights går igennem. To ækvivalente flader gemmer til det samme lager:

• PUT /folders/{folderId}/cors — dette REST-endpoint, JWT-godkendt (bruges af dashboardet)
• S3-underressourcen PUT /{bucket}?cors — SigV4-godkendt (bruges af AWS SDK'er, se s3-compatibility.md)

PUT'et på dette endpoint kræver også mappens navn som en globalt unik bucket, hvis det ikke allerede er krævet.

PUT /folders/{folderId}/cors

Angiv CORS-reglerne for mappens S3-bucket. Op til 5 regler per bucket, 64 KB i alt.

Parameter	Type	Påkrævet	Beskrivelse
rules	CorsRule[]	Ja	Array af AWS-formede CORS-regler (se nedenfor). Må ikke være tom.
bucketName	string	Nej	Eksplicit S3-bucket-navn. Standard er mappens visningsnavn. Hvis det ønskede navn allerede er krævet globalt, angiv et alternativ her.

Hver CorsRule:

Felt	Type	Påkrævet	Beskrivelse
AllowedOrigins	string[]	Ja	Oprindelser, der må sende forespørgsler. Understøtter jokertegn (https://*.myapp.com). Brug * for enhver oprindelse.
AllowedMethods	string[]	Ja	En eller flere af GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nej	Headere, browsere må inkludere på forespørgsler. Standard: ingen. Brug ["*"] for at tillade alle (anbefales til AWS SDK v3, som sender Authorization, x-amz-* osv.).
ExposeHeaders	string[]	Nej	Svar-headere gjort læsbare for browser-JavaScript. Inkluder ETag og x-amz-meta-cid, hvis din app har brug for det returnerede CID.
MaxAgeSeconds	number	Nej	Hvor længe browsere cacher preflighten. 0-86400. Standard 3600.
ID	string	Nej	Fritekst-label til reglen.

Eksempelforespørgsel

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

Svar 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

Returnerer de nuværende CORS-regler plus bucket-navnet (hvis krævet).

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

DELETE /folders/{folderId}/cors

Fjerner alle CORS-regler. Browser-preflights mod bucket'en vil fejle lukket, indtil nye regler sættes.

Alternativ via dashboard

På Filer-siden har hver mappes handlingsmenu en S3 CORS-post, der åbner en formularbaseret editor. Samme underliggende lager som dette REST-endpoint og som PutBucketCors via S3 API.