Kiinnitys

Kiinnitä olemassa olevaa IPFS-sisältöä tilillesi. Kun kiinnität CID:n, klusterimme hakee sisällön IPFS-verkosta ja pitää sen pysyvästi saatavilla.

Kiinnitä CID:llä

POST /pin

Parametri	Tyyppi	Pakollinen	Kuvaus
cid	string	Kyllä	IPFS-sisältötunniste. Kaikki muodot hyväksytään: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… ja muut koodekit).
description	string	Ei	Lyhyt kuvaus viitteeksesi.
metadata	object	Ei	Mukautetut avain-arvo-parit kiinnitykseen liitettäväksi. Enintään 10 avainta. Avainten on oltava aakkosnumeerisia tai alaviivoja, 1-64 merkkiä. Arvojen on oltava merkkijonoja, enintään 256 merkkiä kukin. Metatietojen kokonaiskoko ei saa ylittää 4 KB.
multiaddresses	string[]	Ei	Valinnaisia swarm-connect-vihjeitä. Enintään 5 libp2p-multiosoitetta vertaisille, joilla CID on isännöitynä. Klusterimme suorittaa swarm connect -komennon jokaiselle rinnakkain ennen kiinnitystä, joten yksityisillä / ei-DHT-vertaisilla oleva sisältö on tavoitettavissa ilman DHT-löydön odottamista. Parhaan yrityksen periaatteella — epäonnistunut yhdistäminen ei kaada kiinnitystä. Katso Kiinnitys yksityisestä solmusta.

Esimerkkipyyntö

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

Vastaus 202 Accepted

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

Suurille DAG-rakenteille (>500 lohkoa tai >50 MB) vastaus sisältää async: true -lipun:

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

Kiinnitys yksityisestä solmusta

Jos kiinnitettävä CID sijaitsee vertaisella, joka ei osallistu julkiseen DHT:hen — yksityinen valmistelusolmu, VPN:n takana oleva itseisännöity kone tai NAT:n takana oleva työasema — oletuskiinnitysvirta ei löydä sitä. Yhden tai useamman multiaddresses-parametrin antaminen kertoo klusterillemme tarkalleen, mistä etsiä.

Suoritamme ipfs swarm connect <multiaddr> -komennon jokaiselle vihjeelle rinnakkain ennen kiinnityksen suorittamista. Jos yhdistäminen onnistuu, kiinnityksen DAG-haku voi puhua suoraan vertaisellesi DHT:n läpikäymisen sijaan. Jos se epäonnistuu, kiinnitys jatkuu silti julkista verkkoa vasten (parhaan yrityksen periaate).

Esimerkki: kiinnitä tietystä vertaisesta

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

Vastaus sisältää kunkin vihjeen tilan

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

Hyväksytyt multiosoitemuodot

Yleiset muodot tuetaan: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr-kuljetukset; /tcp- tai /udp-protokollat; valinnaiset /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct-päivitykset. Multiosoitteen on päätyttävä /p2p/<peerId>. Yläraja: enintään 5 vihjettä per kiinnitys.

Solmusi multiosoitteen hankkiminen

Suorita vertaisella, josta haluat kiinnittää, komento ipfs id ja kopioi mikä tahansa Addresses-merkintä, joka päättyy /p2p/<PeerID>. Suosi julkisesti reititettäviä osoitteita (/ip4/YOUR_PUBLIC_IP/…) tai DNS-pohjaisia (/dnsaddr/your.domain/…), jotta klusterimme voi tavoittaa vertaisen AWS:stä.

Erittäin suurten hakemistojen kiinnittäminen

POST /pin on tarkoitettu sisällölle, joka on jo IPFS-verkossa — klusteri hakee DAG:n lohko kerrallaan vertaisilta, mikä voi kestää useita minuutteja hakemistoille, joissa on yli 1 000 tiedostoa. Tämän hakuikkunan aikana jotkin lapsitiedostot eivät ehkä vielä ole paikallisesti saatavilla, ja gateway-pyynnöt niihin voivat aikakatketa. Kun pääkohteen status vaihtuu tilaan pinned, jokainen lapsi on paikallisesti saatavilla ja käytettävissä gatewaysi kautta.

Jos tiedostot ovat paikallisesi (pelkän CID:n sijaan), suosi CAR-tuontia suurille NFT-kokoelmille tai datajoukoille — se lataa koko DAG:n IPFS Ninjaan yhdellä atomisella pyynnöllä, joten hakuikkunaa tai osittaisen kiinnityksen tilaa ei synny. Luo CAR komennolla:

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

Tuo se sitten POST /upload/new -pyynnöllä käyttäen car: true.

TIP

Kiinnitys on asynkroninen. Vastaus palautetaan välittömästi tilalla pinning. Kysy tilapäätepistettä tarkistaaksesi milloin kiinnitys on valmis.

Tarkista kiinnityksen tila

GET /pin/:cid

Parametri	Tyyppi	Pakollinen	Kuvaus
cid	string	Kyllä	Tarkistettava CID.

Vastaus 200 OK

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

Tila-arvot

Tila	Merkitys
pinning	Sisältöä haetaan IPFS-verkosta. Kysy uudelleen muutaman sekunnin kuluttua.
pinned	Sisältö on kiinnitetty ja saatavilla tilisi ja gatewayn kautta.
failed	Sisältöä ei löytynyt IPFS-verkosta. CID voi olla virheellinen tai sisältö ei ole enää saatavilla.

Miten kiinnitys toimii

1. Lähetät CID:n POST /pin -pyynnöllä
2. IPFS-klusterimme etsii verkosta solmuja, joilla on sisältö
3. Klusteri lataa ja kiinnittää sisällön paikallisesti
4. Kiinnityksen jälkeen tiedosto näkyy tiedostolistallasi ja on saatavilla gatewayn kautta
5. Tallennustilan käyttö kirjataan kiinnityksen valmistuttua

WARNING

Kiinnitysaika riippuu tiedostokoosta ja verkon saatavuudesta. Pienet tiedostot kiinnittyvät tyypillisesti sekunneissa. Suuret tiedostot tai harvoin kiinnitetty sisältö voi viedä minuutteja.

Tallennus

Kiinnitetty sisältö lasketaan suunnitelmasi tallennusrajaan. Tiedostokoko kirjataan kiinnityksen valmistuttua. Jos lähestyt tallennusrajaasi, voit vapauttaa tilaa poistamalla käyttämättömiä tiedostoja tai päivittää suunnitelmaasi saadaksesi lisää kapasiteettia.