Kansiot

Kansiot järjestävät ladatut tiedostosi hallintapaneelissa. Ne ovat oletuksena vain metatietoja — tiedostot säilyttävät omat CID:nsä eikä niitä siirretä IPFS:ssä — mutta voit myös ottaa kansiosta tilannevedoksen materialisoidaksesi sen todelliseksi UnixFS-hakemistoksi ja saadaksesi yhden CID:n koko sisällölle.

Milloin kannattaa ottaa tilannevedos kansiosta

Kansion tilannevedos on yksi IPFS-hakemisto-CID, joka sisältää jokaisen kansion tiedoston, osoitettavissa nimen perusteella. Sen avulla voit:

• Jakaa koko kansion yhdellä URL-osoitteella: https://ipfs.ninja/ipfs/{dirCid}/
• Ratkaista osoitteen https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (tai minkä tahansa muun gatewayn kautta) suoraan
• Pudottaa CID:n ENS-contenthashiin staattisen sivuston isännöimiseksi
• Käyttää sitä NFT-kokoelman peruskansiona niin, että jokainen token viittaa osoitteeseen ipfs://{dirCid}/<id>.json
• Kiinnittää hakemiston mihin tahansa muualle — jokainen IPFS-gateway maailmassa osaa ratkaista UnixFS-hakemisto-CID:n

Tilannevedokset ovat sisältöosoitettuja: identtinen kansion sisältö tuottaa aina saman CID:n. Tilannevedoksen ottaminen uudelleen muuttumattomasta kansiosta palauttaa saman CID:n kuin aiemmin. Tiedoston lisääminen/poistaminen/nimeäminen uudelleen tuottaa uuden CID:n; edellinen CID pysyy kiinnitettynä ja ratkaistavana niin kauan kuin et poista sen tiedostoja.

Luo kansio

POST /folders

Parametri	Tyyppi	Pakollinen	Kuvaus
name	string	Kyllä	Näyttönimi.
parentFolderId	string | null	Ei	Emokansion tunnus sisäkkäisille kansioille. Jätä pois juuritason kansiolle.

Esimerkki

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

Palauttaa:

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

Vastaluoduilla kansioilla ei ole tilannevedosta. latestSnapshot-kenttä ilmestyy kansioon, kun kutsut POST /folders/{id}/snapshot (katso alla), ja myöhemmissä GET /folders-vastauksissa.

Listaa kansiot

GET /folders

Palauttaa jokaisen tilisi kansion, juuritason ja sisäkkäiset, kunkin viimeisimmän tilannevedoksen CID:n kanssa (jos sellainen on).

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

fileCount heijastaa kansion nykyistä sisältöä; latestSnapshot.fileCount heijastaa sisältöä viimeisimmän tilannevedoksen ottohetkellä. Jos ne poikkeavat toisistaan, tilannevedoksen CID ratkeaa silti, mutta on vanhentunut — ota uusi tilannevedos päivittääksesi sen.

Siirrä tiedosto kansioon

PUT /files/{cid}/move

Parametri	Tyyppi	Pakollinen	Kuvaus
folderId	string | null	Kyllä	Kohdekansion tunnus, tai null siirtääksesi tiedoston juureen.

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

Ota tilannevedos kansiosta (hae UnixFS-hakemisto-CID)

POST /folders/{folderId}/snapshot

Materialisoi kansio todelliseksi UnixFS-hakemistoksi IPFS-klusterissa ja kiinnitä tulos. Palauttaa yhden CID:n koko kansiolle. Lasten nimet tulevat kunkin tiedoston fileName-kentästä; kaksoiskappaleet puretaan automaattisesti.

Pyynnön runkoa ei tarvita; polkuparametri tunnistaa kansion.

Esimerkki

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

Palauttaa:

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

CID tallennetaan myös kansiorivin yhteyteen, joten myöhemmät GET /folders-kutsut palauttavat sen kenttänä latestSnapshot.cid ilman uuden tilannevedoksen ottamista.

Tilannevedoksen ratkaiseminen

Kun tilannevedos on kiinnitetty, hakemisto-CID ratkeaa minkä tahansa IPFS-gatewayn kautta. Yksinkertaisin URL-kaava:

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

Klusteri kiinnittää rekursiivisesti, joten lapset ovat myös ratkaistavissa — vaikka poistaisit myöhemmin alkuperäisen tiedoston tililtäsi, tilannevedoksen kopio säilyy, koska se on erillinen kiinnitys, joka rekursoituu hakemiston läpi.

Tilannevedoksen ottaminen uudelleen

Tilannevedoksen ottaminen uudelleen muuttumattomasta kansiosta palauttaa saman CID:n — hakemisto-CID:t ovat sisältöosoitettuja, joten identtinen sisältö tuottaa aina saman tiivisteen, ja klusterin kiinnityskutsu tunnistaa kaksoiskappaleen ja on omalta osaltaan no-op.

Huomaa: tilannevedospolku itsessään ei ole ilmainen, vaikka lopputulos olisi sama CID. Jokainen kutsu lukee jokaisen tiedoston tavut takaisin IPFS:stä ja lataa ne uudelleen monivaiheisena klusterin /add-päätepisteeseen — siellä hakemistoon käärintä tapahtuu. Tavanomaisille kansioille (≤100 pientä tiedostoa) tämä on silti valmis muutamassa sekunnissa; hyvin suurille kansioille kannattaa kutsua tilannevedosta vain, kun sisältö on todella muuttunut.

Tilannevedoksen ottaminen tiedostojen lisäämisen tai poistamisen jälkeen tuottaa eri CID:n; edellinen jatkaa ratkeamista niin kauan kuin et poista sen taustalla olevia tiedostoja.

Rajoitukset

• Kansiossa on oltava vähintään yksi tiedosto. Tyhjät kansiot palauttavat 400 — folder is empty.
• Tiedostonimen merkit URL-koodataan monivaiheisessa latauksessa, jonka Kubo hyväksyy; gateway-URL:t saattavat tarvita prosenttikoodausta välilyönneille tai muille kuin ASCII-merkeille tiedostonimissäsi.
• Tilannevedokset lasketaan suunnitelmasi kiinnitysrajaan täsmälleen kerran per yksilöllinen CID — tiedostolohkot deduplikoidaan, joten tilannevedos lisää lähinnä pienen hakemistosolmun jo kiinnittämiesi tiedostojen päälle.

Päivitä kansio

PUT /folders/{folderId}

Parametri	Tyyppi	Pakollinen	Kuvaus
name	string	Ei	Uusi näyttönimi.
parentFolderId	string | null	Ei	Vaihda kansion emokansio. null siirtää sen juureen.

Poista kansio

DELETE /folders/{folderId}

Poistaa kansion ja kaskadoi rekursiivisesti jokaisen sen sisältämän tiedoston ja alikansion läpi. Sama jaetun CID:n turvavarmistus koskee tätä kuin yksittäisten tiedostojen poistoja — jos muut käyttäjät kiinnittävät edelleen lataamaasi CID:tä, kiinnityksesi poistaminen ei riisu sitä heiltä.

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

Määritä S3 CORS kansiolle / bucketille

S3-yhteensopivan API:n kautta paljastetut kansiot toimivat buckettina. Jos ohjaat tätä API:a selaimen JavaScriptistä, tarvitset CORS-säännöt bucketille, jotta selaimen preflight-pyynnöt läpäisevät. Kaksi vastaavaa rajapintaa tallentavat samaan tietovarastoon:

• PUT /folders/{folderId}/cors — tämä REST-päätepiste, JWT-todennettu (hallintapaneelin käyttämä)
• S3-aliresurssi PUT /{bucket}?cors — SigV4-todennettu (AWS SDK:iden käyttämä, katso s3-compatibility.md)

PUT tähän päätepisteeseen myös varaa kansion nimen globaalisti yksilölliseksi bucket-nimeksi, jos sitä ei ole vielä varattu.

PUT /folders/{folderId}/cors

Aseta kansion S3-bucketin CORS-säännöt. Enintään 5 sääntöä per bucket, 64 KB yhteensä.

Parametri	Tyyppi	Pakollinen	Kuvaus
rules	CorsRule[]	Kyllä	Taulukko AWS-muotoisia CORS-sääntöjä (katso alla). Ei saa olla tyhjä.
bucketName	string	Ei	Eksplisiittinen S3-bucket-nimi. Oletusarvona kansion näyttönimi. Jos haluttu nimi on jo varattu globaalisti, anna vaihtoehtoinen nimi tähän.

Jokainen CorsRule:

Kenttä	Tyyppi	Pakollinen	Kuvaus
AllowedOrigins	string[]	Kyllä	Alkuperät, joilta pyyntöjen lähettäminen sallitaan. Tukee jokerimerkkejä (https://*.myapp.com). Käytä * sallimaan mikä tahansa alkuperä.
AllowedMethods	string[]	Kyllä	Yksi tai useampi seuraavista: GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Ei	Otsakkeet, joita selaimet saavat sisällyttää pyyntöihin. Oletus: ei mitään. Käytä ["*"] sallimaan kaikki (suositellaan AWS SDK v3:lle, joka lähettää Authorization, x-amz-* jne.).
ExposeHeaders	string[]	Ei	Vastausotsakkeet, jotka tehdään luettavaksi selaimen JavaScriptille. Sisällytä ETag ja x-amz-meta-cid, jos sovelluksesi tarvitsee palautetun CID:n.
MaxAgeSeconds	number	Ei	Kuinka kauan selaimet välimuistittavat preflight-pyynnön. 0-86400. Oletus 3600.
ID	string	Ei	Vapaamuotoinen nimike säännölle.

Esimerkkipyyntö

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

Vastaus 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

Palauttaa nykyiset CORS-säännöt sekä bucket-nimen (jos varattu).

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

DELETE /folders/{folderId}/cors

Poistaa kaikki CORS-säännöt. Selaimen preflight-pyynnöt buckettia vastaan epäonnistuvat, kunnes uudet säännöt asetetaan.

Hallintapaneelin vaihtoehto

Tiedostot-sivulla jokaisen kansion toimintovalikossa on S3 CORS -toiminto, joka avaa lomakepohjaisen editorin. Sama taustatallennus kuin tässä REST-päätepisteessä ja PutBucketCors-komennossa S3 API:n kautta.