Prisegimas

Prisekite esamą IPFS turinį prie savo paskyros. Kai prisegate CID, mūsų klasteris gauna turinį iš IPFS tinklo ir laiko jį nuolat prieinamą.

Prisegti pagal CID

POST /pin

Parametras	Tipas	Privalomas	Aprašymas
cid	string	Taip	IPFS turinio identifikatorius. Priimama bet kokia forma: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… ir kiti kodekai).
description	string	Ne	Trumpas aprašymas jūsų nuorodai.
metadata	object	Ne	Pritaikytos rakto-reikšmės poros, pridedamos prie prisegimo. Maks. 10 raktų. Raktai turi būti raidiniai-skaitiniai arba pabraukimas, 1-64 simboliai. Reikšmės turi būti eilutės, maks. 256 simbolių kiekviena. Bendras metaduomenų dydis negali viršyti 4 KB.
multiaddresses	string[]	Ne	Pasirenkamos swarm-connect užuominos. Iki 5 libp2p daugiaadresių mazgų, turinčių CID. Mūsų klasteris paleidžia swarm connect kiekvienam iš jų lygiagrečiai prieš prisegimą, todėl turinys privačiuose / ne-DHT mazguose pasiekiamas nelaukiant DHT aptikimo. Geriausių pastangų principu — nepavykęs prisijungimas neblokuoja prisegimo. Žiūrėkite Prisegimas iš privataus mazgo.

Užklausos pavyzdys

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

Atsakymas 202 Accepted

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

Didelėms DAG struktūroms (>500 blokų arba >50 MB) atsakyme įtraukiama async: true žymė:

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

Prisegimas iš privataus mazgo

Jei CID, kurį norite prisegti, yra mazge, nedalyvaujančiame viešajame DHT — privačiame etapiniame (staging) mazge, savarankiškai talpinamoje mašinoje VPN tinkle ar darbo stotyje už NAT — numatytoji prisegimo eiga jo neras. Perduodami vieną ar kelis multiaddresses nurodote mūsų klasteriui tiksliai, kur ieškoti.

Kiekvienai užuominai lygiagrečiai paleidžiame ipfs swarm connect <multiaddr> prieš prisegimą. Jei prisijungimas pavyksta, prisegimo DAG gavimas gali kalbėtis su jūsų mazgu tiesiogiai, o ne ieškoti per DHT. Jei nepavyksta, prisegimas vis tiek vykdomas viešajame tinkle (geriausių pastangų principu).

Pavyzdys: prisegti iš konkretaus mazgo

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

Atsakyme pateikiama kiekvienos užuominos būsena

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

Priimamos daugiaadresių formos

Palaikomos įprastos formos: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr transportai; /tcp arba /udp protokolai; pasirenkami /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct papildymai. Daugiaadresis privalo baigtis /p2p/<peerId>. Riba: iki 5 užuominų vienam prisegimui.

Kaip gauti savo mazgo daugiaadresį

Mazge, iš kurio norite prisegti, paleiskite ipfs id ir nukopijuokite bet kurį Addresses įrašą, kuris baigiasi /p2p/<PeerID>. Rinkitės viešai pasiekiamus adresus (/ip4/YOUR_PUBLIC_IP/…) arba DNS pagrįstus (/dnsaddr/your.domain/…), kad mūsų klasteris galėtų pasiekti mazgą iš AWS.

Labai didelių katalogų prisegimas

POST /pin skirtas turiniui, kuris jau yra IPFS tinkle — klasteris gauna DAG bloką po bloko iš mazgų, o tai gali užtrukti kelias minutes katalogams su 1000+ failų. Šio gavimo lango metu kai kurie vaikiniai failai gali būti dar nepasiekiami lokaliai, ir gateway užklausos jiems gali baigtis laiko limitu. Kai tėvinio elemento status pasikeičia į pinned, kiekvienas vaikinis failas yra pasiekiamas lokaliai ir per jūsų gateway.

Jei failus turite lokaliai (o ne tik CID), didelėms NFT kolekcijoms ar duomenų rinkiniams rinkitės CAR importą — jis įkelia visą DAG į IPFS Ninja vienu atomišku užklausos metu, todėl nėra nei gavimo lango, nei dalinio prisegimo būsenos. Sukurkite CAR su:

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

Tada importuokite jį per POST /upload/new su car: true.

TIP

Prisegimas yra asinchroninis. Atsakymas grąžinamas iš karto su būsena pinning. Apklauskite būsenos galinį tašką, kad patikrintumėte, kada prisegimas baigtas.

Patikrinti prisegimo būseną

GET /pin/:cid

Parametras	Tipas	Privalomas	Aprašymas
cid	string	Taip	CID, kurį tikrinate.

Atsakymas 200 OK

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

Būsenos reikšmės

Būsena	Reikšmė
pinning	Turinys gaunamas iš IPFS tinklo. Apklauskite dar kartą po kelių sekundžių.
pinned	Turinys prisegtas ir prieinamas per jūsų paskyrą ir gateway.
failed	Turinio nepavyko rasti IPFS tinkle. CID gali būti neteisingas arba turinys nebeprieinamas.

Kaip prisegimas veikia

1. Pateikiate CID per POST /pin
2. Mūsų IPFS klasteris ieško tinkle mazgų, turinčių turinį
3. Klasteris atsisiunčia ir prisega turinį lokaliai
4. Prisegus, failas rodomas jūsų failų sąraše ir prieinamas per gateway
5. Saugyklos naudojimas registruojamas prisegimui pasibaigus

WARNING

Prisegimo laikas priklauso nuo failo dydžio ir tinklo prieinamumo. Maži failai paprastai prisegami per sekundes. Dideli failai ar retai prisegtas turinys gali užtrukti minutes.

Saugykla

Prisegtas turinys skaičiuojamas į jūsų plano saugyklos ribą. Failo dydis registruojamas prisegimui pasibaigus. Jei artėjate prie saugyklos ribos, galite atlaisvinti vietos ištrindami nenaudojamus failus arba atnaujinti planą didesnei talpai gauti.