Mapper

Mapper organiserer de opplastede filene dine i dashbordet. De er kun metadata som standard — filer beholder sine egne CID-er og flyttes ikke på IPFS — men du kan også ta et øyeblikksbilde av en mappe for å materialisere den som en ekte UnixFS-katalog og få én CID for hele greia.

Når bør du ta et øyeblikksbilde av en mappe

Et mappe-øyeblikksbilde er én IPFS-katalog-CID som inneholder alle filer i mappen, adresserbare etter navn. Med den kan du:

• Dele hele mappen via én URL: https://ipfs.ninja/ipfs/{dirCid}/
• Løse opp https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (eller enhver annen gateway) direkte
• Legge CID-en inn i en ENS contenthash for å hoste et statisk nettsted
• Bruke den som basis-CID for en NFT-samling, slik at hvert token refererer til ipfs://{dirCid}/<id>.json
• Feste katalogen hvor som helst ellers — hver IPFS-gateway i verden vet hvordan man løser opp en UnixFS-katalog-CID

Øyeblikksbilder er innholdsadresserte: identisk mappeinnhold produserer alltid samme CID. Å ta et nytt øyeblikksbilde av en mappe du ikke har endret, returnerer samme CID som sist. Å legge til/fjerne/gi nytt navn til en fil produserer en ny CID; den forrige CID-en forblir festet og oppløselig så lenge du ikke sletter filene dens.

Opprett mappe

POST /folders

Parameter	Type	Påkrevd	Beskrivelse
name	string	Ja	Visningsnavn.
parentFolderId	string | null	Nei	Foreldermappe-ID for nestede mapper. Utelat for en mappe på rotnivå.

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
}

Nyopprettede mapper har ingen øyeblikksbilder. Feltet latestSnapshot dukker opp på mappen når du kaller POST /folders/{id}/snapshot (se nedenfor), og på påfølgende GET /folders-svar.

List mapper

GET /folders

Returnerer hver mappe i kontoen din, både på rotnivå og nestet, med den siste øyeblikksbilde-CID-en for hver (hvis noen).

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

fileCount reflekterer mappens nåværende innhold; latestSnapshot.fileCount reflekterer innholdet på tidspunktet for det siste øyeblikksbildet. Hvis de avviker, løses øyeblikksbilde-CID-en fortsatt opp, men er utdatert — ta et nytt øyeblikksbilde for å oppdatere.

Flytt en fil til en mappe

PUT /files/{cid}/move

Parameter	Type	Påkrevd	Beskrivelse
folderId	string | null	Ja	Mål-mappe-ID, eller null for å flytte filen til roten.

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

Ta et øyeblikksbilde av en mappe (få en UnixFS-katalog-CID)

POST /folders/{folderId}/snapshot

Materialiser mappen som en ekte UnixFS-katalog på IPFS-klyngen og fest resultatet. Returnerer én CID for hele mappen. Navn på underliggende filer kommer fra hver fils fileName; duplikater skilles automatisk fra hverandre.

Det trengs ingen forespørselskropp; stiparameteren identifiserer 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-en lagres også på mapperaden, så påfølgende GET /folders-kall returnerer den som latestSnapshot.cid uten behov for et nytt øyeblikksbilde.

Løse opp et øyeblikksbilde

Når et øyeblikksbilde er festet, løses katalog-CID-en opp via hvilken som helst IPFS-gateway. Det enkleste URL-mønsteret:

https://ipfs.ninja/ipfs/{dirCid}/         → katalogoppføring
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → den ene filen

Klyngen fester rekursivt, så underliggende filer er også oppløselige — selv om du senere sletter originalfilen fra kontoen din, overlever øyeblikksbildets kopi fordi den er en separat festing som rekurserer gjennom katalogen.

Å ta et nytt øyeblikksbilde

Å ta et nytt øyeblikksbilde av en uendret mappe returnerer samme CID — katalog-CID-er er innholdsadresserte, så identisk innhold produserer alltid samme hash, og klyngens festingskall gjenkjenner duplikatet og blir en no-op på sin side.

Merk: selve øyeblikksbildestien er ikke gratis selv når resultatet er samme CID. Hvert kall leser hver fils bytes tilbake fra IPFS og laster dem opp på nytt som en multipart til klyngens /add-endepunkt — det er der katalog-innpakningen skjer. For typiske mapper (≤100 små filer) fullføres dette fortsatt på noen sekunder; for svært store mapper bør du foretrekke å kalle øyeblikksbilde bare når innholdet faktisk har endret seg.

Å kalle øyeblikksbilde etter at du har lagt til eller fjernet filer produserer en annen CID; den forrige fortsetter å løse opp så lenge du ikke sletter de underliggende filene dens.

Begrensninger

• Mappen må inneholde minst én fil. Tomme mapper returnerer 400 — folder is empty.
• Filnavn-tegn URL-kodes i multipart-opplastingen Kubo godtar; gateway-URL-er kan trenge prosent-koding for mellomrom eller ikke-ASCII-tegn i filnavnene dine.
• Øyeblikksbilder teller mot planens totale festingsantall nøyaktig én gang per unike CID — filblokker dedupliseres, så øyeblikksbildet legger for det meste bare til en liten katalognode oppå filer du allerede fester.

Oppdater en mappe

PUT /folders/{folderId}

Parameter	Type	Påkrevd	Beskrivelse
name	string	Nei	Nytt visningsnavn.
parentFolderId	string | null	Nei	Gi mappen ny forelder. null flytter den til roten.

Slett en mappe

DELETE /folders/{folderId}

Sletter mappen og kaskaderer rekursivt gjennom hver fil og undermappe den inneholder. Underlagt den samme delt-CID-sikkerhetssperren som individuelle filslettinger — hvis andre brukere fortsatt fester en CID du lastet opp, fjerner ikke din avfesting den for dem.

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

Konfigurer S3 CORS for en mappe / bucket

Mapper eksponert gjennom det S3-kompatible API-et fungerer som buckets. Hvis du styrer det API-et fra nettleser-JavaScript, trenger du CORS-regler på bucketen slik at nettleserens preflight-forespørsler går gjennom. To ekvivalente overflater lagrer til den samme datalageret:

• PUT /folders/{folderId}/cors — dette REST-endepunktet, JWT-autentisert (brukt av dashbordet)
• S3-underressurs PUT /{bucket}?cors — SigV4-autentisert (brukt av AWS SDK-er, se s3-compatibility.md)

PUT-en på dette endepunktet krever også mappens navn som et globalt unikt bucket-navn hvis det ikke allerede er krevd.

PUT /folders/{folderId}/cors

Sett CORS-reglene for mappens S3-bucket. Opptil 5 regler per bucket, 64 KB totalt.

Parameter	Type	Påkrevd	Beskrivelse
rules	CorsRule[]	Ja	Array av AWS-formede CORS-regler (se nedenfor). Ikke tom.
bucketName	string	Nei	Eksplisitt S3-bucket-navn. Standard er mappens visningsnavn. Hvis ønsket navn allerede er krevd globalt, oppgi et alternativ her.

Hver CorsRule:

Felt	Type	Påkrevd	Beskrivelse
AllowedOrigins	string[]	Ja	Opprinnelser som har lov til å sende forespørsler. Støtter jokertegn (https://*.myapp.com). Bruk * for enhver opprinnelse.
AllowedMethods	string[]	Ja	Én eller flere av GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nei	Headere nettlesere kan inkludere i forespørsler. Standard: ingen. Bruk ["*"] for å tillate alle (anbefalt for AWS SDK v3, som sender Authorization, x-amz-*, osv.).
ExposeHeaders	string[]	Nei	Svarheadere gjort lesbare for nettleser-JavaScript. Inkluder ETag og x-amz-meta-cid hvis appen din trenger den returnerte CID-en.
MaxAgeSeconds	number	Nei	Hvor lenge nettlesere cacher preflight-forespørselen. 0-86400. Standard 3600.
ID	string	Nei	Fritekst-etikett for regelen.

Eksempelforespørsel

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 gjeldende CORS-regler pluss bucket-navnet (hvis krevd).

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

DELETE /folders/{folderId}/cors

Fjerner alle CORS-regler. Nettleserens preflight-forespørsler mot bucketen vil feile (lukket som standard) inntil nye regler settes.

Dashbord-alternativ

På Filer-siden har hver mappes handlingsmeny en S3 CORS-oppføring som åpner en skjemabasert editor. Samme underliggende datalager som dette REST-endepunktet og som PutBucketCors via S3 API-et.