Piespraušana

Piespraudiet esošu IPFS saturu savam kontam. Kad piespraužat CID, mūsu klasteris iegūst saturu no IPFS tīkla un uztur to pastāvīgi pieejamu.

Piespraust pēc CID

POST /pin

Parametrs	Tips	Obligāts	Apraksts
cid	string	Jā	IPFS satura identifikators. Tiek pieņemta jebkura forma: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… un citi kodeki).
description	string	Nē	Īss apraksts jūsu atsaucei.
metadata	object	Nē	Pielāgoti atslēgu-vērtību pāri piespraušanai. Maks 10 atslēgas. Atslēgām jābūt alfanumeriskām vai pasvītrojumiem, 1-64 rakstzīmes. Vērtībām jābūt virknēm, maks 256 rakstzīmes katra. Kopējais metadatu izmērs nedrīkst pārsniegt 4 KB.
multiaddresses	string[]	Nē	Neobligātas swarm-connect norādes. Līdz 5 libp2p multiadresēm no mezgliem, kas glabā CID. Mūsu klasteris paralēli izpilda swarm connect katrai no tām pirms piespraušanas, tāpēc saturs uz privātiem / ne-DHT mezgliem ir sasniedzams, negaidot DHT atklāšanu. Labākā centiena pamatā — neveiksmīgs savienojums nesagrauj piespraušanu. Skatiet Piespraušana no privāta mezgla.

Pieprasījuma piemērs

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

Atbilde 202 Accepted

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

Lieliem DAG (>500 bloki vai >50 MB), atbilde ietver async: true karodziņu:

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

Piespraušana no privāta mezgla

Ja CID, kuru vēlaties piespraust, atrodas uz mezgla, kas nepiedalās publiskajā DHT — privāts staging mezgls, pašpārvaldīta mašīna VPN vai darbstacija aiz NAT — noklusējuma piespraušanas plūsma to neatradīs. Norādot vienu vai vairākas multiaddresses, jūs pasakāt mūsu klasterim, kur tieši meklēt.

Mēs paralēli izpildām ipfs swarm connect <multiaddr> katrai norādei pirms piespraušanas sākuma. Ja savienojums izdodas, piespraušanas DAG ieguve var sazināties tieši ar jūsu mezglu, nevis meklēt caur DHT. Ja tas neizdodas, piespraušana tomēr turpinās pret publisko tīklu (labākā centiena semantika).

Piemērs: piespraust no konkrēta mezgla

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

Atbilde ietver statusu katrai norādei

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

Atbalstītās multiadrešu formas

Tiek atbalstītas izplatītas formas: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr transporti; /tcp vai /udp protokoli; neobligāti /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct uzlabojumi. Multiadresei jābeidzas ar /p2p/<peerId>. Ierobežojums: līdz 5 norādēm vienai piespraušanai.

Sava mezgla multiadreses iegūšana

Uz mezgla, no kura vēlaties piespraust, izpildiet ipfs id un nokopējiet jebkuru no Addresses ierakstiem, kas beidzas ar /p2p/<PeerID>. Dodiet priekšroku publiski maršrutējamām adresēm (/ip4/YOUR_PUBLIC_IP/…) vai DNS balstītām adresēm (/dnsaddr/your.domain/…), lai mūsu klasteris varētu sasniegt mezglu no AWS.

Ļoti lielu direktoriju piespraušana

POST /pin ir paredzēts saturam, kas jau atrodas IPFS tīklā — klasteris ievelk DAG bloku pa blokam no mezgliem, kas direktorijām ar 1000+ failiem var aizņemt vairākas minūtes. Šajā ieguves periodā daži bērnfaili var vēl nebūt lokāli pieejami, un gateway pieprasījumi tiem var pārsniegt gaidīšanas laiku. Kad vecāka status mainās uz pinned, katrs bērnfails ir lokāli pieejams un sasniedzams caur jūsu gateway.

Ja jums faili ir lokāli (nevis tikai CID), lielām NFT kolekcijām vai datu kopām dodiet priekšroku CAR importam — tas augšupielādē visu DAG uz IPFS Ninja vienā atomiskā pieprasījumā, tāpēc nav ne ieguves perioda, ne daļējas piespraušanas stāvokļa. Izveidojiet CAR ar:

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

Pēc tam importējiet to caur POST /upload/new ar car: true.

TIP

Piespraušana ir asinhrona. Atbilde tiek atgriezta nekavējoties ar statusu pinning. Aptaujājiet statusa galapunktu, lai pārbaudītu, kad piespraušana ir pabeigta.

Pārbaudīt piespraušanas statusu

GET /pin/:cid

Parametrs	Tips	Obligāts	Apraksts
cid	string	Jā	CID, kuru pārbaudāt.

Atbilde 200 OK

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

Statusa vērtības

Statuss	Nozīme
pinning	Saturs tiek iegūts no IPFS tīkla. Aptaujājiet vēlreiz pēc dažām sekundēm.
pinned	Saturs ir piesprausts un pieejams caur jūsu kontu un gateway.
failed	Saturs netika atrasts IPFS tīklā. CID var būt nederīgs vai saturs vairs nav pieejams.

Kā piespraušana darbojas

1. Jūs iesniedzat CID caur POST /pin
2. Mūsu IPFS klasteris meklē tīklā mezglus, kuriem ir saturs
3. Klasteris lejupielādē un piespauž saturu lokāli
4. Pēc piespraušanas fails parādās jūsu failu sarakstā un ir pieejams caur gateway
5. Glabātuves izmantošana tiek reģistrēta, kad piespraušana ir pabeigta

WARNING

Piespraušanas laiks ir atkarīgs no faila izmēra un tīkla pieejamības. Mazi faili parasti tiek piesprausti sekundēs. Lieli faili vai reti piesprausts saturs var aizņemt minūtes.

Glabātuve

Piespraustais saturs tiek ieskaitīts jūsu plāna glabātuves limitā. Faila izmērs tiek reģistrēts, kad piespraušana ir pabeigta — jūs varat uzsākt piespraušanu pat ja jūsu glabātuve ir tuvu limitam, bet turpmākās augšupielādes tiks bloķētas, ja piespraušana izraisa limita pārsniegšanu.