Папки

Папките организират качените ви файлове в таблото за управление. По подразбиране те съдържат само метаданни — файловете запазват собствените си CID и не се преместват в IPFS — но можете също да направите снимка (snapshot) на папка, за да я материализирате като истинска UnixFS директория и да получите един CID за цялото ѝ съдържание.

Кога да направите снимка на папка

Снимката на папка е един IPFS CID на директория, съдържащ всеки файл в папката, адресируем по име. С него можете да:

Споделите цялата папка чрез един URL: https://ipfs.ninja/ipfs/{dirCid}/
Разрешите директно https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (или чрез всеки друг gateway)
Поставите CID-а в ENS contenthash, за да хоствате статичен сайт
Го използвате като базов CID на NFT колекция, така че всеки токен да реферира ipfs://{dirCid}/<id>.json
Закачите директорията навсякъде другаде — всеки IPFS gateway в света знае как да разреши UnixFS CID на директория

Снимките са адресирани по съдържание: идентично съдържание на папката винаги произвежда същия CID. Повторно снимане на непроменена папка връща същия CID, върнат преди. Добавянето/премахването/преименуването на файл произвежда нов CID; предишният CID остава закачен и разрешим, докато не изтриете файловете му.

Създаване на папка

POST /folders

Параметър	Тип	Задължителен	Описание
`name`	string	Да	Показвано име.
`parentFolderId`	string \| null	Не	ID на родителска папка за вложени папки. Пропуснете за папка от най-високо ниво.

Пример

bash

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

Връща:

json

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

Новосъздадените папки нямат снимка. Полето latestSnapshot се появява на папката, след като извикате POST /folders/{id}/snapshot (вижте по-долу), и в последващите отговори на GET /folders.

Списък на папки

GET /folders

Връща всяка папка във вашия акаунт, както от най-високо ниво, така и вложена, с CID-а на последната снимка за всяка от тях (ако има такава).

json

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

fileCount отразява текущото съдържание на папката; latestSnapshot.fileCount отразява съдържанието към момента на последната снимка. Ако се различават, CID-ът на снимката все още се разрешава, но е остарял — направете нова снимка, за да го обновите.

Преместване на файл в папка

PUT /files/{cid}/move

Параметър	Тип	Задължителен	Описание
`folderId`	string \| null	Да	ID на целевата папка, или `null`, за да преместите файла в корена.

bash

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

Снимка на папка (получаване на UnixFS CID на директория)

POST /folders/{folderId}/snapshot

Материализира папката като истинска UnixFS директория в IPFS клъстера и закача резултата. Връща един CID за цялата папка. Имената на децата идват от fileName на всеки файл; дублиращите се имена се разграничават автоматично.

Не е необходимо тяло на заявката; параметърът в пътя идентифицира папката.

Пример

bash

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

Връща:

json

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

CID-ът се съхранява постоянно и в реда на папката, така че последващите извиквания на GET /folders го връщат като latestSnapshot.cid без нужда от нова снимка.

Разрешаване на снимка

След като снимката е закачена, CID-ът на директорията се разрешава чрез всеки IPFS gateway. Най-простият модел на URL:

https://ipfs.ninja/ipfs/{dirCid}/         → списък на директорията
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → конкретния файл

Клъстерът закача рекурсивно, така че децата също са разрешими — дори ако по-късно изтриете оригиналния файл от акаунта си, копието в снимката оцелява, защото е отделно закачане, рекурсиращо през директорията.

Повторно снимане

Повторното снимане на непроменена папка връща същия CID — CID-овете на директории са адресирани по съдържание, така че идентично съдържание винаги произвежда същия хеш, а извикването за закачане на клъстера разпознава дублирането и не прави нищо от своя страна.

Забележка: самият път за снимане не е безплатен дори когато резултатът е същият CID. Всяко извикване чете байтовете на всеки файл обратно от IPFS и ги качва отново като multipart към крайната точка /add на клъстера — там се случва опаковането в директория. За типични папки (≤100 малки файла) това все още завършва за няколко секунди; за много големи папки предпочитайте да извиквате снимка само когато съдържанието наистина се е променило.

Извикването на снимка след добавяне или премахване на файлове произвежда различен CID; предишният продължава да се разрешава, докато не изтриете файловете, стоящи в основата му.

Ограничения

Папката трябва да съдържа поне един файл. Празните папки връщат 400 — folder is empty.
Знаците в имената на файловете се URL-кодират в multipart качването, което Kubo приема; URL-адресите на gateway може да се нуждаят от процентно кодиране за интервали или ASCII-извън символи в имената на файловете ви.
Снимките се отчитат в общия брой закачания на плана ви точно веднъж на уникален CID — блоковете на файловете се дедублират, така че снимката най-вече добавя малък възел за директория върху файлове, които вече закачате.

Актуализиране на папка

PUT /folders/{folderId}

Параметър	Тип	Задължителен	Описание
`name`	string	Не	Ново показвано име.
`parentFolderId`	string \| null	Не	Промяна на родителската папка. `null` я премества в корена.

Изтриване на папка

DELETE /folders/{folderId}

Изтрива папката и рекурсивно преминава през всеки файл и подпапка, които съдържа. Подлежи на същата защита за споделени CID, както при изтриване на отделни файлове — ако други потребители все още закачват CID, който сте качили, вашето откачване не го премахва за тях.

json

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

Конфигуриране на S3 CORS за папка / bucket

Папките, изложени чрез S3-съвместимия API, действат като bucket-и. Ако управлявате този API от JavaScript в браузъра, ви трябват CORS правила на bucket-а, за да преминават preflight заявките на браузъра. Две еквивалентни повърхности записват в едно и също хранилище:

PUT /folders/{folderId}/cors — тази REST крайна точка, удостоверена с JWT (използвана от таблото за управление)
S3 субресурс PUT /{bucket}?cors — удостоверен с SigV4 (използван от AWS SDK, вижте s3-compatibility.md)

PUT към тази крайна точка също заявява името на папката като глобално уникален bucket, ако все още не е заявено.

PUT /folders/{folderId}/cors

Задава CORS правилата за S3 bucket-а на папката. До 5 правила на bucket, общо 64 KB.

Параметър	Тип	Задължителен	Описание
`rules`	CorsRule[]	Да	Масив от CORS правила във формата на AWS (вижте по-долу). Не може да е празен.
`bucketName`	string	Не	Изрично S3 име на bucket. По подразбиране е показваното име на папката. Ако желаното име вече е заето глобално, подайте тук алтернатива.

Всяко CorsRule:

Поле	Тип	Задължителен	Описание
`AllowedOrigins`	string[]	Да	Произходи, разрешени да изпращат заявки. Поддържа wildcard (`https://.myapp.com`). Използвайте `` за произволен произход.
`AllowedMethods`	string[]	Да	Един или повече от `GET`, `HEAD`, `PUT`, `POST`, `DELETE`.
`AllowedHeaders`	string[]	Не	Заглавия, които браузърите могат да включват в заявките. По подразбиране: няма. Използвайте `[""]`, за да разрешите всички (препоръчително за AWS SDK v3, който изпраща `Authorization`, `x-amz-` и др.).
`ExposeHeaders`	string[]	Не	Заглавия на отговора, направени четими за JavaScript в браузъра. Включете `ETag` и `x-amz-meta-cid`, ако приложението ви се нуждае от върнатия CID.
`MaxAgeSeconds`	number	Не	Колко дълго браузърите кешират preflight заявката. 0-86400. По подразбиране 3600.
`ID`	string	Не	Свободен текстов етикет за правилото.

Пример за заявка

bash

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

Response `200 OK`

json

{ "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

Връща текущите CORS правила плюс името на bucket-а (ако е заявено).

json

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

DELETE /folders/{folderId}/cors

Премахва всички CORS правила. Preflight заявките на браузъра към bucket-а ще се провалят, докато не бъдат зададени нови правила.

Алтернатива в таблото за управление

На страницата с файлове менюто с действия на всяка папка има запис S3 CORS, който отваря редактор с форма. Същото основно хранилище като тази REST крайна точка и като PutBucketCors през S3 API.

Папки ​

Кога да направите снимка на папка ​

Създаване на папка ​

Пример ​

Списък на папки ​

Преместване на файл в папка ​

Снимка на папка (получаване на UnixFS CID на директория) ​

Пример ​

Разрешаване на снимка ​

Повторно снимане ​

Ограничения ​

Актуализиране на папка ​

Изтриване на папка ​

Конфигуриране на S3 CORS за папка / bucket ​

PUT /folders/{folderId}/cors ​

Пример за заявка ​

Response 200 OK ​

GET /folders/{folderId}/cors ​

DELETE /folders/{folderId}/cors ​

Папки

Кога да направите снимка на папка

Създаване на папка

Пример

Списък на папки

Преместване на файл в папка

Снимка на папка (получаване на UnixFS CID на директория)

Пример

Разрешаване на снимка

Повторно снимане

Ограничения

Актуализиране на папка

Изтриване на папка

Конфигуриране на S3 CORS за папка / bucket

PUT /folders/{folderId}/cors

Пример за заявка

Response `200 OK`

GET /folders/{folderId}/cors

DELETE /folders/{folderId}/cors