Sabitleme

Mevcut IPFS içeriğini hesabınıza sabitleyin. Bir CID'yi sabitlediğinizde, kümemiz içeriği IPFS ağından alır ve kalıcı olarak erişilebilir tutar.

CID ile Sabitle

POST /pin

Parametre	Tür	Zorunlu	Açıklama
cid	string	Evet	IPFS içerik tanımlayıcısı. Her form kabul edilir: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… ve diğer codec'ler).
description	string	Hayır	Referansınız için kısa açıklama.
metadata	object	Hayır	Sabitlemeye eklenecek özel anahtar-değer çiftleri. Maksimum 10 anahtar. Anahtarlar alfanumerik veya alt çizgi olmalıdır, 1-64 karakter. Değerler dize olmalıdır, her biri maksimum 256 karakter. Toplam meta veri boyutu 4 KB'yi aşmamalıdır.
multiaddresses	string[]	Hayır	İsteğe bağlı swarm-connect ipuçları. CID'yi barındıran eşlerin en fazla 5 libp2p multiadresi. Kümemiz sabitlemeden önce her biri için paralel olarak swarm connect çalıştırır, böylece özel / DHT dışı eşlerdeki içeriğe DHT keşfini beklemeden ulaşılabilir. En iyi çaba prensibiyle çalışır — başarısız bir bağlantı sabitlemeyi başarısız kılmaz. Bkz. Özel bir düğümden sabitleme.

Örnek istek

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Yanıt 202 Accepted

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "description": "NFT metadata",
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Büyük DAG'ler için (>500 blok veya >50 MB), yanıt bir async: true bayrağı içerir:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "async": true,
  "note": "Large DAG detected — pin running in background. Check status via GET /pin/bafybei…",
  "uris": { ... }
}

Özel bir düğümden sabitleme

Sabitlemek istediğiniz CID, genel DHT'ye katılmayan bir eş üzerinde yaşıyorsa — özel bir hazırlık (staging) düğümü, bir VPN üzerindeki kendi barındırdığınız bir makine veya NAT arkasındaki bir iş istasyonu — varsayılan sabitleme akışı onu bulamaz. Bir veya daha fazla multiaddresses göndermek kümemize tam olarak nereye bakacağını söyler.

Sabitleme çalışmadan önce her ipucu için paralel olarak ipfs swarm connect <multiaddr> çalıştırırız. Bağlantı başarılı olursa, sabitlemenin DAG alımı DHT'de arama yapmak yerine doğrudan eşinizle konuşabilir. Başarısız olursa, sabitleme yine de genel ağa karşı devam eder (en iyi çaba semantiği).

Örnek: belirli bir eşten sabitleme

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

Yanıt, her ipucu için durum içerir

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "swarmConnected": [
    { "multiaddr": "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooW…", "ok": true,  "strings": ["connect 12D3KooW… success"] },
    { "multiaddr": "/dns4/node.internal.example/tcp/443/…",   "ok": false, "error": "dial to peer: no route" }
  ],
  "uris": { … }
}

Kabul edilen multiadres biçimleri

Yaygın biçimler desteklenir: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr taşıyıcıları; /tcp veya /udp protokolleri; isteğe bağlı /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct yükseltmeleri. Multiadres mutlaka /p2p/<peerId> ile bitmelidir. Sınır: sabitleme başına en fazla 5 ipucu.

Düğümünüzün multiadresini alma

Sabitlemek istediğiniz eş üzerinde ipfs id çalıştırın ve /p2p/<PeerID> ile biten Addresses girdilerinden birini kopyalayın. Kümemizin eşe AWS'den ulaşabilmesi için genel yönlendirilebilir adresleri (/ip4/YOUR_PUBLIC_IP/…) veya DNS tabanlı olanları (/dnsaddr/your.domain/…) tercih edin.

Çok büyük dizinleri sabitleme

POST /pin, zaten IPFS ağında bulunan içerik içindir — küme, DAG'ı eşlerden blok blok alır, bu da 1.000+ dosya içeren dizinler için birkaç dakika sürebilir. Bu alma penceresi sırasında, bazı alt dosyalar henüz yerel olarak kullanılamayabilir ve bunlara yapılan gateway istekleri zaman aşımına uğrayabilir. Üst öğenin status'ü pinned olarak değiştiğinde, her alt öğe yerel olarak kullanılabilir ve gateway'iniz üzerinden erişilebilir olur.

Dosyalar yerelinizde mevcutsa (yalnızca bir CID yerine), büyük NFT koleksiyonları veya veri kümeleri için CAR içe aktarma tercih edin — tüm DAG'ı tek bir atomik istekte IPFS Ninja'ya yükler, böylece bir alma penceresi ve kısmi sabitleme durumu olmaz. Bir CAR oluşturun:

npx ipfs-car pack ./my-collection -o collection.car

Ardından car: true ile POST /upload/new aracılığıyla içe aktarın.

TIP

Sabitleme eşzamansızdır. Yanıt pinning durumuyla hemen döner. Sabitlemenin ne zaman tamamlanacağını kontrol etmek için durum uç noktasını sorgulayın.

Sabitleme Durumunu Kontrol Et

GET /pin/:cid

Parametre	Tür	Zorunlu	Açıklama
cid	string	Evet	Kontrol ettiğiniz CID.

Yanıt 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Durum değerleri

Durum	Anlamı
pinning	İçerik IPFS ağından alınıyor. Birkaç saniye sonra tekrar sorgulayın.
pinned	İçerik sabitlendi ve hesabınız ile gateway üzerinden erişilebilir.
failed	İçerik IPFS ağında bulunamadı. CID geçersiz olabilir veya içerik artık mevcut değil.

Sabitleme nasıl çalışır

1. POST /pin ile bir CID gönderirsiniz
2. IPFS kümemiz, içeriğe sahip düğümler için ağı arar
3. Küme içeriği indirir ve yerel olarak sabitler
4. Sabitlendiğinde, dosya dosya listenizde görünür ve gateway üzerinden erişilebilir olur
5. Depolama kullanımı sabitleme tamamlandığında kaydedilir

WARNING

Sabitleme süresi dosya boyutuna ve ağ erişilebilirliğine bağlıdır. Küçük dosyalar genellikle saniyeler içinde sabitlenir. Büyük dosyalar veya nadiren sabitlenmiş içerik dakikalar alabilir.

Depolama

Sabitlenmiş içerik planınızın depolama sınırına dahildir. Dosya boyutu sabitleme tamamlandığında kaydedilir — depolama alanınız sınıra yakın olsa bile sabitleme başlatabilirsiniz, ancak sabitleme sınırı aşmanıza neden olursa sonraki yüklemeler engellenir.