Klasörler

Klasörler, yüklediğiniz dosyaları dashboard'da düzenler. Varsayılan olarak yalnızca meta veridirler — dosyalar kendi CID'lerini korur ve IPFS üzerinde taşınmaz — ancak bir klasörü snapshot'layarak onu gerçek bir UnixFS dizinine dönüştürebilir ve tüm içerik için tek bir CID elde edebilirsiniz.

Bir klasörü ne zaman snapshot'larsınız

Bir klasör snapshot'ı, ada göre adreslenebilen, klasördeki her dosyayı içeren tek bir IPFS dizin CID'sidir. Bununla şunları yapabilirsiniz:

• Tüm klasörü tek bir URL ile paylaşın: https://ipfs.ninja/ipfs/{dirCid}/
• https://ipfs.ninja/ipfs/{dirCid}/photo.jpg'yi (veya başka herhangi bir gateway'i) doğrudan çözümleyin
• CID'yi statik bir siteyi barındırmak için bir ENS contenthash'ine bırakın
• Her token'ın ipfs://{dirCid}/<id>.json'a referans vermesi için bir NFT koleksiyonunun temel CID'si olarak kullanın
• Dizini başka herhangi bir yerde sabitleyin — dünyadaki her IPFS gateway'i bir UnixFS dizin CID'sini nasıl çözümleyeceğini bilir

Snapshot'lar içerik adreslidir: aynı klasör içeriği her zaman aynı CID'yi üretir. Değiştirmediğiniz bir klasörü yeniden snapshot'lamak daha önce döndürdüğü aynı CID'yi döndürür. Bir dosya eklemek/kaldırmak/yeniden adlandırmak yeni bir CID üretir; dosyalarını silmediğiniz sürece önceki CID sabitlenmiş ve çözümlenebilir kalır.

Klasör oluştur

POST /folders

Parametre	Tür	Zorunlu	Açıklama
name	string	Evet	Görüntüleme adı.
parentFolderId	string | null	Hayır	İç içe klasörler için üst klasör ID'si. Kök düzeyinde bir klasör için atlayın.

Örnek

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

Döndürür:

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

Yeni oluşturulan klasörlerin snapshot'ı yoktur. latestSnapshot alanı, POST /folders/{id}/snapshot'ı çağırdığınızda (aşağıya bakın) ve sonraki GET /folders yanıtlarında klasörde görünür.

Klasörleri listele

GET /folders

Hesabınızdaki her klasörü, kök düzeyinde ve iç içe olanları, her biri için son snapshot CID'siyle (varsa) döndürür.

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

fileCount, klasörün mevcut içeriğini yansıtır; latestSnapshot.fileCount ise son snapshot alındığındaki içeriği yansıtır. Farklıysa, snapshot CID'si hâlâ çözümlenir ancak güncel değildir — yenilemek için yeniden snapshot alın.

Bir dosyayı bir klasöre taşı

PUT /files/{cid}/move

Parametre	Tür	Zorunlu	Açıklama
folderId	string | null	Evet	Hedef klasör ID'si veya dosyayı köke taşımak için null.

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

Bir klasörü snapshot'la (bir UnixFS dizin CID'si edin)

POST /folders/{folderId}/snapshot

Klasörü IPFS kümesinde gerçek bir UnixFS dizini olarak dönüştürün ve sonucu sabitleyin. Tüm klasör için tek bir CID döndürür. Alt öğelerin adları her dosyanın fileName'inden gelir; yinelenenler otomatik olarak çakışmadan arındırılır.

İstek gövdesi gerekmez; yol parametresi klasörü tanımlar.

Örnek

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

Döndürür:

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

CID ayrıca klasör satırında kalıcı hale getirilir, böylece sonraki GET /folders çağrıları başka bir snapshot almaya gerek kalmadan bunu latestSnapshot.cid olarak döndürür.

Bir snapshot'ı çözümleme

Bir snapshot sabitlendikten sonra, dizin CID'si herhangi bir IPFS gateway'i üzerinden çözümlenir. En basit URL kalıbı:

https://ipfs.ninja/ipfs/{dirCid}/         → dizin listesi
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → o tek dosya

Küme özyinelemeli olarak sabitler, bu yüzden alt öğeler de çözümlenebilir — daha sonra hesabınızdan orijinal dosyayı silseniz bile, snapshot'ın kopyası hayatta kalır çünkü dizinde özyinelemeli olarak ayrı bir sabitlemedir.

Yeniden snapshot'lama

Değişmemiş bir klasörü yeniden snapshot'lamak aynı CID'yi döndürür — dizin CID'leri içerik adreslidir, bu yüzden aynı içerik her zaman aynı hash'i üretir ve kümenin sabitleme çağrısı yinelenmeyi tanır ve kendi ucunda hiçbir şey yapmaz.

Not: sonuç aynı CID olsa bile snapshot yolunun kendisi bedava değildir. Her çağrı, her dosyanın baytlarını IPFS'ten geri okur ve bunları kümenin /add uç noktasına multipart olarak yeniden yükler — dizinle sarma işlemi burada gerçekleşir. Tipik klasörler için (≤100 küçük dosya) bu hâlâ birkaç saniyede tamamlanır; çok büyük klasörler için snapshot'ı yalnızca içerik gerçekten değiştiğinde çağırmayı tercih edin.

Dosya ekledikten veya kaldırdıktan sonra snapshot çağırmak farklı bir CID üretir; altındaki dosyaları silmediğiniz sürece önceki CID çözümlenmeye devam eder.

Sınırlar

• Klasör en az bir dosya içermelidir. Boş klasörler 400 — folder is empty döndürür.
• Dosya adı karakterleri, Kubo'nun kabul ettiği multipart yüklemede URL kodludur; gateway URL'leri dosya adlarınızdaki boşluklar veya ASCII olmayan karakterler için yüzde kodlaması gerektirebilir.
• Snapshot'lar, benzersiz CID başına yalnızca bir kez planınızın toplam sabitleme sayısına dahildir — dosya blokları tekilleştirilir, bu yüzden snapshot çoğunlukla zaten sabitlediğiniz dosyaların üzerine küçük bir dizin düğümü ekler.

Bir klasörü güncelle

PUT /folders/{folderId}

Parametre	Tür	Zorunlu	Açıklama
name	string	Hayır	Yeni görüntüleme adı.
parentFolderId	string | null	Hayır	Klasörü yeniden üst öğeye bağlayın. null onu köke taşır.

Bir klasörü sil

DELETE /folders/{folderId}

Klasörü ve içerdiği her dosya ve alt klasörü özyinelemeli olarak siler. Bireysel dosya silmelerdeki aynı paylaşılan-CID güvenlik korumasına tabidir — başka kullanıcılar yüklediğiniz bir CID'yi hâlâ sabitliyorsa, sabitlemeyi kaldırmanız onu onlar için silmez.

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

Bir klasör / bucket için S3 CORS yapılandırma

S3 uyumlu API üzerinden gösterilen klasörler bucket olarak davranır. Bu API'yi tarayıcı JavaScript'inden çalıştırıyorsanız, tarayıcı preflight isteklerinin geçmesi için bucket üzerinde CORS kurallarına ihtiyacınız vardır. Aynı depoya kalıcı hale gelen iki eşdeğer yüzey:

• PUT /folders/{folderId}/cors — bu REST uç noktası, JWT ile kimlik doğrulamalı (dashboard tarafından kullanılır)
• S3 alt kaynağı PUT /{bucket}?cors — SigV4 ile kimlik doğrulamalı (AWS SDK'ları tarafından kullanılır, bkz. s3-compatibility.md)

Bu uç noktadaki PUT, henüz talep edilmemişse klasörün adını global olarak benzersiz bir bucket olarak da talep eder.

PUT /folders/{folderId}/cors

Klasörün S3 bucket'ı için CORS kurallarını ayarlayın. Bucket başına en fazla 5 kural, toplam 64 KB.

Parametre	Tür	Zorunlu	Açıklama
rules	CorsRule[]	Evet	AWS biçimli CORS kuralları dizisi (aşağıya bakın). Boş olamaz.
bucketName	string	Hayır	Açık S3 bucket adı. Varsayılan olarak klasörün görüntüleme adı kullanılır. İstenen ad global olarak zaten talep edilmişse, burada bir alternatif geçirin.

Her CorsRule:

Alan	Tür	Zorunlu	Açıklama
AllowedOrigins	string[]	Evet	İstek göndermesine izin verilen kaynaklar. Joker karakterleri destekler (https://*.myapp.com). Herhangi bir kaynak için * kullanın.
AllowedMethods	string[]	Evet	GET, HEAD, PUT, POST, DELETE'den bir veya daha fazlası.
AllowedHeaders	string[]	Hayır	Tarayıcıların isteklere dahil edebileceği başlıklar. Varsayılan: yok. Tümüne izin vermek için ["*"] kullanın (Authorization, x-amz-* vb. gönderen AWS SDK v3 için önerilir).
ExposeHeaders	string[]	Hayır	Tarayıcı JavaScript'ine okunabilir hale getirilen yanıt başlıkları. Uygulamanız döndürülen CID'ye ihtiyaç duyuyorsa ETag ve x-amz-meta-cid'i dahil edin.
MaxAgeSeconds	number	Hayır	Tarayıcıların preflight isteğini ne kadar süre önbelleğe alacağı. 0-86400. Varsayılan 3600.
ID	string	Hayır	Kural için serbest metin etiket.

Örnek istek

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

Yanıt 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

Mevcut CORS kurallarını ve bucket adını (talep edilmişse) döndürür.

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

DELETE /folders/{folderId}/cors

Tüm CORS kurallarını kaldırır. Yeni kurallar ayarlanana kadar bucket'a yönelik tarayıcı preflight istekleri kapalı şekilde başarısız olur.

Dashboard alternatifi

Dosyalar sayfasında, her klasörün eylem menüsünde form tabanlı bir düzenleyici açan bir S3 CORS girişi vardır. Bu REST uç noktası ve S3 API üzerinden PutBucketCors ile aynı temel depo.