Rögzítés

Rögzítsen meglévő IPFS tartalmat a fiókjához. Amikor rögzít egy CID-et, a klaszterünk lekéri a tartalmat az IPFS hálózatról, és tartósan elérhetővé teszi.

Rögzítés CID alapján

POST /pin

Paraméter	Típus	Kötelező	Leírás
cid	string	Igen	IPFS tartalomazonosító. Bármilyen forma elfogadott: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… és más codec-ek).
description	string	Nem	Rövid leírás az Ön számára.
metadata	object	Nem	Egyéni kulcs-érték párok a rögzítéshez csatolásra. Max 10 kulcs. A kulcsok alfanumerikusak vagy aláhúzás lehetnek, 1-64 karakter. Az értékeknek szövegnek kell lenniük, max 256 karakter. A metaadatok összmérete nem haladhatja meg a 4 KB-ot.
multiaddresses	string[]	Nem	Opcionális swarm-connect hint-ek. Legfeljebb 5 libp2p multiaddress a CID-et tároló peer-ekhez. A klaszterünk mindegyik ellen párhuzamosan futtat swarm connect-et a rögzítés előtt, így a privát / nem-DHT peer-eken lévő tartalom is elérhető anélkül, hogy meg kellene várni a DHT-alapú felfedezést. Best-effort — egy sikertelen kapcsolódás nem hiúsítja meg a rögzítést. Lásd Rögzítés privát csomópontról.

Példa kérés

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

Response 202 Accepted

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

Nagy DAG-ok esetén (>500 blokk vagy >50 MB) a válasz tartalmaz egy async: true jelzőt:

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

Rögzítés privát csomópontról

Ha a rögzíteni kívánt CID egy olyan peer-en él, amely nem vesz részt a nyilvános DHT-ban — egy privát staging csomópont, egy VPN-en keresztül elérhető saját üzemeltetésű gép, vagy egy NAT mögötti munkaállomás — az alapértelmezett rögzítési folyamat nem fogja megtalálni. Ha megad egy vagy több multiaddresses értéket, azzal pontosan megmondja a klaszterünknek, hol keresse.

Minden hint-hez párhuzamosan futtatjuk az ipfs swarm connect <multiaddr> parancsot a rögzítés előtt. Ha a kapcsolódás sikeres, a rögzítés DAG-lekérése közvetlenül a peer-jével tud kommunikálni ahelyett, hogy a DHT-ban keresgélne. Ha sikertelen, a rögzítés akkor is folytatódik a nyilvános hálózat ellen (best-effort szemantika).

Példa: rögzítés egy adott peer-ről

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

A válasz hint-enkénti állapotot tartalmaz

{
  "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": { … }
}

Elfogadott multiaddress formátumok

A gyakori formátumok támogatottak: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr transzportok; /tcp vagy /udp protokollok; opcionális /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct upgrade-ek. A multiaddress-nek kötelezően /p2p/<peerId>-vel kell végződnie. Korlát: legfeljebb 5 hint rögzítésenként.

A csomópont multiaddress-ének megszerzése

Azon a peer-en, amelyről rögzíteni szeretne, futtassa az ipfs id parancsot, és másolja ki bármelyik Addresses bejegyzést, amely /p2p/<PeerID>-vel végződik. Előnyben részesítse a nyilvánosan útválasztható címeket (/ip4/YOUR_PUBLIC_IP/…) vagy a DNS-alapúakat (/dnsaddr/your.domain/…), hogy a klaszterünk elérje a peer-t az AWS-ből.

Nagyon nagy könyvtárak rögzítése

A POST /pin olyan tartalomhoz való, amely már él az IPFS hálózaton — a klaszter blokkonként kéri le a DAG-ot a peer-ektől, ami 1000+ fájlt tartalmazó könyvtárak esetén akár több percig is eltarthat. Ez alatt a lekérési ablak alatt egyes gyermekfájlok még nem feltétlenül érhetők el lokálisan, és a gateway-kérések rájuk időtúllépést okozhatnak. Amint a szülő status-a pinned-re vált, minden gyermek lokálisan elérhetővé válik és hozzáférhető a gateway-én keresztül.

Ha a fájlok lokálisan is megvannak (nem csak a CID), nagy NFT gyűjteményekhez vagy adathalmazokhoz részesítse előnyben a CAR importot — az teljes DAG-ot tölt fel az IPFS Ninja-ra egyetlen atomi kéréssel, így nincs lekérési ablak és nincs részleges rögzítési állapot. Hozzon létre egy CAR-t a következővel:

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

Ezután importálja a POST /upload/new végponton car: true paraméterrel.

TIP

A rögzítés aszinkron. A válasz azonnal visszatér pinning állapottal. A rögzítés befejezésének ellenőrzéséhez kérdezze le az állapot végpontot.

Rögzítési állapot ellenőrzése

GET /pin/:cid

Paraméter	Típus	Kötelező	Leírás
cid	string	Igen	Az ellenőrizendő CID.

Response 200 OK

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

Állapot értékek

Status	Jelentés
pinning	A tartalom lekérés alatt az IPFS hálózatról. Kérdezze le újra néhány másodperc múlva.
pinned	A tartalom rögzítve van és elérhető a fiókján és gateway-én keresztül.
failed	A tartalom nem található az IPFS hálózaton. A CID érvénytelen lehet, vagy a tartalom már nem elérhető.

Hogyan működik a rögzítés

1. Elküldi a CID-et a POST /pin végpontra
2. IPFS klaszterünk megkeresi a hálózaton a tartalommal rendelkező csomópontokat
3. A klaszter letölti és helyben rögzíti a tartalmat
4. Rögzítés után a fájl megjelenik a fájllistájában és elérhető a gateway-en keresztül
5. A tárhelyhasználat a rögzítés befejezésekor kerül rögzítésre

WARNING

A rögzítés ideje a fájl méretétől és a hálózat elérhetőségétől függ. Kis fájlok jellemzően másodpercek alatt rögzítésre kerülnek. Nagy fájlok vagy ritkán rögzített tartalom percekbe telhet.

Tárhely

A rögzített tartalom beleszámít a csomagja tárhelykorlátjába. A fájlméret a rögzítés befejezésekor kerül rögzítésre -- elindíthat egy rögzítést akkor is, ha a tárhelye közel van a korláthoz, de a további feltöltések blokkolva lesznek, ha a rögzítés miatt túllépi azt.