· Nacho Coll · Guides  · 7 min lukuaika

IPFS CID selitettynä: mikä se on ja miten sisältöosoitus toimii

Selkeä tekninen selitys IPFS-sisältötunnisteista (CIDs). Miten sisältöosoitus toimii, CID-versiot ja miten luot ensimmäisen CID:si.

Selkeä tekninen selitys IPFS-sisältötunnisteista (CIDs). Miten sisältöosoitus toimii, CID-versiot ja miten luot ensimmäisen CID:si.

Jos olet koskaan työskennellyt IPFS:n (InterPlanetary File System) kanssa, olet todennäköisesti törmännyt merkkijonoihin kuten QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG tai bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Nämä eivät ole satunnaista hölynpölyä — ne ovat sisältötunnisteita (CIDs), IPFS:n sisältöosoitusjärjestelmän selkäranka.

CIDien ymmärtäminen on ratkaisevan tärkeää kaikille, jotka rakentavat IPFS:n päälle, riippumatta siitä, lataatko tiedostoja, rakennat hajautettuja sovelluksia tai toteutat sisällönjakelujärjestelmiä. Tämä opas käy läpi kaiken, mitä sinun tarvitsee tietää IPFS-CIDeistä, miten sisältöosoitus toimii ja miten aloitat niiden käytön projekteissasi.

IPFS Ninja

Mikä on IPFS CID?

Sisältötunniste (CID) on yksilöllinen sormenjälki, joka edustaa sisältöä IPFS:ssä. Toisin kuin perinteiset web-URL:t, jotka osoittavat sijaintiin (kuten https://example.com/file.pdf), CIDit osoittavat itse sisältöön, riippumatta siitä, missä se on tallennettu.

Ajattele asiaa näin:

  • Sijaintiperusteinen osoitus: “Mene osoitteeseen Pääkatu 123 ja pyydä punaista kirjaa”
  • Sisältöperusteinen osoitus: “Etsi kirja, jonka ISBN on 978-0-123456-78-9” (sillä ei ole väliä, missä kirjastossa se on)

CIDit toimivat samalla tavalla — ne tunnistavat sisällön sen kryptografisen tiivisteen perusteella, mikä tekee sisällöstä muuttumattoman ja todennettavan. Jos tiedostossa muuttuu yksikin tavu, CID muuttuu täysin.

Miksi sisältöosoitus on tärkeää

Perinteinen web-arkkitehtuuri perustuu sijaintiperusteiseen osoitukseen. Kun vierailet osoitteessa https://example.com/image.jpg, luotat siihen, että:

  1. Verkkotunnuksen omistaja ei ole muuttanut sisältöä
  2. Palvelin on online-tilassa ja saavutettavissa
  3. Sisältöä ei ole peukaloitu

Sisältöosoituksella CIDeillä:

  1. Muuttumattomuus: CID takaa, että sisältö ei ole muuttunut
  2. Hajautus: Sisältö voidaan hakea miltä tahansa IPFS-solmulta, jolla se on
  3. Todennus: Voit kryptografisesti todentaa, että sait oikean sisällön
  4. Tehokkuus: Identtinen sisältö poistetaan automaattisesti päällekkäisyyksien osalta

CID:n anatomia

Puretaan tyypillinen CID ymmärtääksemme sen osat:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Sisällön tiiviste (Base32-koodattu)
  └─ Multibase-etuliite (ilmaisee koodauksen)

CID sisältää useita tietoja:

1. Multibase-etuliite

Ensimmäinen merkki ilmaisee, miten CID on koodattu:

  • Q = Base58-koodaus (CIDv0)
  • b = Base32-koodaus (CIDv1)
  • f = Base16/heksadesimaali (CIDv1)
  • z = Base58 (CIDv1)

2. CID-versio

  • CIDv0: Alkaa aina Qm:llä, käyttää SHA-256:ta, rajoitettu DAG-PB-koodekkiin
  • CIDv1: Joustavampi, tukee useita tiivistefunktioita ja koodekkeja

3. Multicodec

Määrittää, miten sisältö on rakenteistettu (DAG-PB, DAG-CBOR, raakatavut jne.)

4. Multihash

Sisällön todellinen kryptografinen tiiviste, mukaan lukien:

  • Tiivistefunktion tunniste (yleensä SHA-256)
  • Tiivisteen pituus
  • Tiivisteen digest

CIDv0 vs CIDv1: Erojen ymmärtäminen

IPFS on kehittynyt kahden suuren CID-version kautta, kullakin on omat ominaisuutensa:

CIDv0: Alkuperäinen formaatti

CIDv0-CIDit alkavat aina Qm:llä ja näyttävät tältä:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Ominaisuudet:

  • Vain Base58-koodaus
  • Vain SHA-256-tiivistefunktio
  • Vain DAG-PB (Protobuf) -koodekki
  • 46 merkkiä pitkä
  • Taaksepäin yhteensopiva kaikkien IPFS-toteutusten kanssa

Milloin käyttää CIDv0:ta:

  • Maksimaalinen yhteensopivuus vanhempien IPFS-solmujen kanssa
  • Työskentely olemassa olevien järjestelmien kanssa, jotka odottavat Qm-etuliitettä
  • Tiedostojen tallennus (yleisin käyttötapaus)

CIDv1: Moderni standardi

CIDv1-CIDit ovat joustavampia ja voivat näyttää tältä:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi  # Base32
zb2rhj7crUKTQYRGCRATFaQ6YFLTde2YzdqbbhAASkL9uRDXn      # Base58
f01551220d1e2c35...                                      # Base16

Ominaisuudet:

  • Useita koodausmuotoja (Base32, Base58, Base16)
  • Tuki eri tiivistefunktioille (SHA-256, SHA-512, BLAKE2 jne.)
  • Useita koodekkeja (Raw, DAG-CBOR, DAG-JSON jne.)
  • Itsekuvaava formaatti
  • Ei kirjainkoosta riippuva Base32:ta käytettäessä

Milloin käyttää CIDv1:tä:

  • Uusien sovellusten rakentaminen
  • Tarvitset kirjainkoosta riippumattomia tunnisteita
  • Työskentely rakenteellisen datan kanssa (JSON, CBOR)
  • Vaihtoehtoisten tiivistefunktioiden käyttö

Versioiden välinen muunto

Voit muuntaa CIDejä versioiden välillä säilyttäen saman sisältöviittauksen:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

// Convert to CIDv1 Base32
const cidv1 = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi";

// Both reference the same content!

Miten sisältöosoitus toimii

IPFS:n sisältöosoitus noudattaa deterministista prosessia, joka varmistaa, että sama sisältö tuottaa aina saman CID:n:

1. Sisällön valmistelu

Kun lisäät sisältöä IPFS:ään, se hajotetaan ensin:

  • Pienet tiedostot: Tallennetaan yksittäisinä lohkoina
  • Suuret tiedostot: Jaetaan paloihin ja järjestetään Merkle DAG:iin (suunnattu syklittömän graafi)
  • Hakemistot: Esitetään DAG-rakenteina, jotka linkittyvät tiedostoihin

2. Tiivistämisprosessi

Jokainen sisältöpalanen käy läpi:

  1. Sarjallistus: Sisältö muotoillaan koodekkinsa mukaan
  2. Tiivistäminen: Kryptografinen tiivistefunktio käsittelee sarjallisen datan
  3. Multihash-luonti: Tiiviste käännetään algoritmi- ja pituustiedoilla
  4. CID-kokoaminen: Versio, koodekki ja multihash yhdistetään

3. Merkle DAG -rakenne

IPFS järjestää sisällön Merkle DAG:iin, jossa:

  • Jokaisella solmulla on CID
  • Vanhempi-solmut viittaavat lapsi-solmuihin CID:n kautta
  • Muutokset missä tahansa solmussa leviävät puuhun ylöspäin
  • Koko rakenteet voidaan kryptografisesti todentaa
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Käytännön esimerkit: CIDien kanssa työskentely

Tutkitaan, miten CIDien kanssa työskennellään käytännössä IPFS Ninja API:lla:

Sisällön lataaminen ja CID:n saaminen

// Upload a file and get its CID
const uploadFile = async (content, filename) => {
  const response = await fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa(content), // Base64 encode binary content
      description: `Upload of ${filename}`
    })
  });
  
  const result = await response.json();
  console.log('CID:', result.cid);
  console.log('IPFS URL:', result.uris.ipfs);
  console.log('HTTP URL:', result.uris.url);
  
  return result.cid;
};

// Example usage
uploadFile('Hello, IPFS!', 'greeting.txt');
// Returns: bafkreifjxz6zwqh27k5xnr5qfbx4w6n5vuwwwdcngguwjewzj2e3xxfgvi

Olemassa olevan sisällön kiinnittäminen CID:llä

Jos sinulla on jo CID, voit kiinnittää sen varmistaaksesi saatavuuden:

const pinByCID = async (cid) => {
  const response = await fetch('https://api.ipfs.ninja/pin', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      cid: cid,
      description: 'Pinned via API'
    })
  });
  
  const result = await response.json();
  console.log('Pinned CID:', result.cid);
  
  return result;
};

// Pin the "Hello World" of IPFS
pinByCID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u');

Sisältöön pääsy CID:n kautta

Kun sinulla on CID, voit päästä käsiksi sisältöön useilla tavoilla:

// Direct IPFS gateway access
const ipfsUrl = `https://ipfs.ninja/ipfs/${cid}`;

// Custom gateway (if configured)
const customGatewayUrl = `https://my-app.gw.ipfs.ninja/ipfs/${cid}`;

// Fetch content programmatically
const fetchContent = async (cid) => {
  const response = await fetch(`https://ipfs.ninja/ipfs/${cid}`);
  const content = await response.text();
  return content;
};

CID-parhaat käytännöt kehittäjille

1. Validoi CIDit aina

Ennen CID:n käyttöä sovelluksessasi, validoi sen muoto:

const isValidCID = (cid) => {
  // Basic validation patterns
  const cidv0Pattern = /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/;
  const cidv1Pattern = /^[bf][a-z2-7]{58}$/;
  
  return cidv0Pattern.test(cid) || cidv1Pattern.test(cid);
};

2. Käsittele molempia CID-versioita

Sovelluksesi tulisi toimia sekä CIDv0:n että CIDv1:n kanssa:

const normalizeCID = (cid) => {
  if (cid.startsWith('Qm')) {
    // CIDv0 - can convert to CIDv1 if needed
    return cid;
  } else if (cid.startsWith('b') || cid.startsWith('f') || cid.startsWith('z')) {
    // CIDv1
    return cid;
  } else {
    throw new Error('Invalid CID format');
  }
};

3. Välimuistita CID-mäppäykset

Jos generoit CIDejä usein, harkitse välimuistitusta:

const cidCache = new Map();

const getCachedCID = (content) => {
  const contentHash = btoa(content);
  
  if (cidCache.has(contentHash)) {
    return cidCache.get(contentHash);
  }
  
  // Upload and cache result
  return uploadFile(content).then(cid => {
    cidCache.set(contentHash, cid);
    return cid;
  });
};

4. Käytä merkityksellisiä kuvauksia

Kun lataat sisältöä, sisällytä kuvaava metadata:

const uploadWithMetadata = async (content, metadata) => {
  return fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa(content),
      description: metadata.name || 'Uploaded file',
      metadata: {
        filename: metadata.filename,
        contentType: metadata.contentType,
        uploadedAt: new Date().toISOString(),
        version: metadata.version || '1.0'
      }
    })
  });
};

Yleisiä CID-käyttötapauksia

1. Staattinen verkkosivuston käyttöönotto

Ota kokonaiset verkkosivustot käyttöön IPFS:ssä ja viittaa niihin CID:llä:

// Upload website directory structure
const deployWebsite = async (files) => {
  const uploads = await Promise.all(
    files.map(file => uploadFile(file.content, file.path))
  );
  
  // Root CID references entire site
  const rootCID = uploads.find(u => u.path === 'index.html').cid;
  console.log(`Website deployed: https://ipfs.ninja/ipfs/${rootCID}`);
  
  return rootCID;
};

Lue lisää verkkosivuston käyttöönotosta oppaastamme miten ladata tiedostoja IPFS:ään.

2. NFT-metadatan tallennus

Tallenna NFT-metadata muuttumattomasti CIDeillä:

const nftMetadata = {
  name: "My Awesome NFT",
  description: "A unique digital collectible",
  image: "ipfs://bafkreibc5sgo2plmjkq2tzmhrn54bk3crhnqekiy7u66fqvqm37pu2e5gw",
  attributes: [
    { trait_type: "Color", value: "Blue" },
    { trait_type: "Rarity", value: "Epic" }
  ]
};

const metadataCID = await uploadFile(
  JSON.stringify(nftMetadata, null, 2), 
  'metadata.json'
);

// Use in smart contract
console.log(`Token URI: ipfs://${metadataCID}`);

3. Sisällönjakelu

Käytä CIDejä hajautettuun sisällönjakeluun:

// Upload once, access everywhere
const distributeContent = async (content) => {
  const cid = await uploadFile(content, 'content.txt');
  
  // Content available via multiple gateways
  const gateways = [
    `https://ipfs.ninja/ipfs/${cid}`,
    `https://ipfs.io/ipfs/${cid}`,
    `https://cloudflare-ipfs.com/ipfs/${cid}`
  ];
  
  return { cid, gateways };
};

IPFS-pinningin ymmärtäminen CIDeillä

CIDit ovat oletuksena väliaikaisia — ne on “kiinnitettävä” pysyäkseen saatavilla. Lue lisää tästä tärkeästä käsitteestä kattavasta oppaastamme mikä on IPFS-pinning.

Kun valitset IPFS-pinning-palvelua, harkitse lukemista vertailustamme IPFS Ninja vs Pinata tai tutustu tämän hetken parhaiden IPFS-pinning-palveluiden koosteeseemme.

Luo ensimmäinen CID 30 sekunnissa

Valmis generoimaan ensimmäisen CID:si? Tässä nopea esimerkki IPFS Ninja API:lla:

# Using curl (replace with your actual API key)
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "SGVsbG8sIElQRlMgV29ybGQh",
    "description": "My first IPFS upload"
  }'
// Using JavaScript
const createFirstCID = async () => {
  const response = await fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa('Hello, IPFS World!'), // Base64: "SGVsbG8sIElQRlMgV29ybGQh"
      description: 'My first IPFS upload'
    })
  });
  
  const result = await response.json();
  console.log('🎉 Your first CID:', result.cid);
  console.log('🌐 Access it at:', result.uris.url);
  
  return result;
};

createFirstCID();

Tämä palauttaa jotain seuraavanlaista:

{
  "cid": "bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw",
  "sizeMB": 0.000017,
  "uris": {
    "ipfs": "ipfs://bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw",
    "url": "https://ipfs.ninja/ipfs/bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw"
  }
}

Lisätietoja yksityiskohtaisemmista API-esimerkeistä, katso IPFS-lataus-API-oppaastamme.

Yhteenveto

CIDit ovat IPFS:n sisältöosoitusjärjestelmän perusta, joka tarjoaa muuttumattoman, todennettavan ja hajautetun sisällön tunnistamisen. Niiden toiminnan ymmärtäminen — CIDv0:n vs CIDv1:n teknisistä yksityiskohdista käytännön toteutusmalleihin — on välttämätöntä vankkojen hajautettujen sovellusten rakentamiseen.

Keskeiset huomiot:

  • CIDit tunnistavat sisällön yksilöllisesti, eivät sijainteja
  • CIDv0 tarjoaa maksimaalisen yhteensopivuuden, CIDv1 tarjoaa joustavuutta
  • Sisältöosoitus mahdollistaa todennuksen ja duplikaattien poiston
  • Asianmukainen CID-käsittely on ratkaisevan tärkeää tuotantosovelluksissa

Olipa kyseessä NFT-metadatan tallennus, hajautettujen verkkosivustojen käyttöönotto tai sisällönjakelujärjestelmien rakentaminen, CIDit tarjoavat luotettavan perustan, jota tarvitset aidosti hajautettuihin sovelluksiin.

Valmis aloittamaan pinningin? Luo ilmainen tili — 50 tiedostoa, 1 GB tallennustilaa, 2 GB kaistanleveys/kuukausi. Ei luottokorttia vaaditaan.

Share:
Takaisin Blogiin

Aiheeseen liittyvät artikkelit

Näytä kaikki artikkelit »