· Nacho Coll · Guides  · 8 dk okuma

IPFS CID açıklandı: nedir ve içerik adresleme nasıl çalışır

IPFS İçerik Tanımlayıcılarının (CIDs) net teknik açıklaması. İçerik adresleme nasıl çalışır, CID sürümleri ve ilk CID'nizi nasıl oluşturursunuz.

IPFS İçerik Tanımlayıcılarının (CIDs) net teknik açıklaması. İçerik adresleme nasıl çalışır, CID sürümleri ve ilk CID'nizi nasıl oluşturursunuz.

Eğer IPFS (InterPlanetary File System) ile çalıştıysanız, muhtemelen QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG veya bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi gibi dizelerle karşılaşmışsınızdır. Bunlar rastgele karakter dizileri değildir — bunlar IPFS’in içerik adresleme sisteminin omurgası olan İçerik Tanımlayıcılarıdır (CIDs).

CID’leri anlamak, ister dosya yüklüyor, ister merkeziyetsiz uygulamalar geliştiriyor, ister içerik dağıtım sistemleri uyguluyor olun, IPFS üzerine inşa eden herkes için çok önemlidir. Bu kılavuz, IPFS CID’leri hakkında bilmeniz gereken her şeyi, içerik adreslemenin nasıl çalıştığını ve projelerinizde bunları kullanmaya nasıl başlayacağınızı açıklayacak.

IPFS Ninja

IPFS CID nedir?

İçerik Tanımlayıcı (CID), IPFS üzerindeki bir içerik parçasını temsil eden benzersiz bir parmak izidir. Bir konuma işaret eden geleneksel web URL’lerinin aksine (https://example.com/file.pdf gibi), CID’ler nerede depolandığına bakılmaksızın içeriğin kendisine işaret eder.

Şöyle düşünün:

  • Konum bazlı adresleme: “Ana Cadde 123’e gidin ve kırmızı kitabı isteyin”
  • İçerik bazlı adresleme: “ISBN 978-0-123456-78-9’a sahip kitabı bulun” (hangi kütüphanenin elinde olduğu önemli değil)

CID’ler benzer şekilde çalışır — içeriği kriptografik karma değerine göre tanımlar, içeriği değişmez ve doğrulanabilir hale getirir. Dosyada tek bir bayt değişirse, CID tamamen değişir.

İçerik adresleme neden önemlidir

Geleneksel web mimarisi konum bazlı adreslemeye dayanır. https://example.com/image.jpg adresini ziyaret ettiğinizde, şunlara güvenirsiniz:

  1. Alan adı sahibinin içeriği değiştirmediği
  2. Sunucunun çevrimiçi ve erişilebilir olduğu
  3. İçeriğin tahrif edilmediği

CID’lerle içerik adresleme kullanılırken:

  1. Değişmezlik: CID, içeriğin değişmediğini garanti eder
  2. Merkeziyetsizlik: İçerik, onu barındıran herhangi bir IPFS düğümünden alınabilir
  3. Doğrulama: Doğru içeriği aldığınızı kriptografik olarak doğrulayabilirsiniz
  4. Verimlilik: Aynı içerik otomatik olarak tekilleştirilir

Bir CID’nin anatomisi

Bileşenlerini anlamak için tipik bir CID’yi parçalayalım:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ İçerik Karması (Base32 kodlu)
  └─ Multibase Öneki (kodlamayı belirtir)

Bir CID birkaç bilgi parçası içerir:

1. Multibase Öneki

İlk karakter, CID’nin nasıl kodlandığını gösterir:

  • Q = Base58 kodlama (CIDv0)
  • b = Base32 kodlama (CIDv1)
  • f = Base16/onaltılık (CIDv1)
  • z = Base58 (CIDv1)

2. CID Sürümü

  • CIDv0: Her zaman Qm ile başlar, SHA-256 kullanır, DAG-PB codec ile sınırlıdır
  • CIDv1: Daha esnek, birden fazla karma işlevini ve codec’i destekler

3. Multicodec

İçeriğin nasıl yapılandırıldığını belirtir (DAG-PB, DAG-CBOR, ham baytlar, vb.)

4. Multihash

İçeriğin gerçek kriptografik karma değeri, şunları içerir:

  • Karma işlevi tanımlayıcısı (genellikle SHA-256)
  • Karma uzunluğu
  • Karma özeti

CIDv0 vs CIDv1: Farkları anlamak

IPFS, her biri farklı özelliklere sahip iki ana CID sürümünden geçti:

CIDv0: Orijinal format

CIDv0 CID’leri her zaman Qm ile başlar ve şöyle görünür:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Özellikler:

  • Yalnızca Base58 kodlama
  • Yalnızca SHA-256 karma işlevi
  • Yalnızca DAG-PB (Protobuf) codec
  • 46 karakter uzunluğunda
  • Tüm IPFS uygulamalarıyla geriye dönük uyumlu

CIDv0 ne zaman kullanılır:

  • Eski IPFS düğümleriyle maksimum uyumluluk
  • Qm öneklerini bekleyen mevcut sistemlerle çalışma
  • Dosya depolama (en yaygın kullanım durumu)

CIDv1: Modern standart

CIDv1 CID’leri daha esnektir ve şöyle görünebilir:

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

Özellikler:

  • Birden fazla kodlama formatı (Base32, Base58, Base16)
  • Farklı karma işlevleri için destek (SHA-256, SHA-512, BLAKE2, vb.)
  • Birden fazla codec (Raw, DAG-CBOR, DAG-JSON, vb.)
  • Kendini tanımlayan format
  • Base32 kullanırken büyük/küçük harfe duyarsız

CIDv1 ne zaman kullanılır:

  • Yeni uygulamalar geliştirirken
  • Büyük/küçük harfe duyarsız tanımlayıcılara ihtiyaç duyduğunuzda
  • Yapılandırılmış verilerle çalışırken (JSON, CBOR)
  • Alternatif karma işlevleri kullanırken

Sürümler arasında dönüşüm

Aynı içerik referansını koruyarak CID’leri sürümler arasında dönüştürebilirsiniz:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

İçerik adresleme nasıl çalışır

IPFS’deki içerik adresleme, aynı içeriğin her zaman aynı CID’yi üretmesini sağlayan deterministik bir süreç izler:

1. İçerik hazırlığı

IPFS’e içerik eklediğinizde, önce parçalara ayrılır:

  • Küçük dosyalar: Tek bloklar olarak saklanır
  • Büyük dosyalar: Parçalara bölünür ve Merkle DAG (Yönlendirilmiş Asiklik Grafik) içinde organize edilir
  • Dizinler: Dosyalara bağlanan DAG yapıları olarak temsil edilir

2. Karma süreci

Her içerik parçası şunlardan geçer:

  1. Serileştirme: İçerik codec’ine göre biçimlendirilir
  2. Karma: Kriptografik karma işlevi serileştirilmiş veriyi işler
  3. Multihash oluşturma: Karma, algoritma ve uzunluk bilgisiyle sarılır
  4. CID birleştirme: Sürüm, codec ve multihash birleştirilir

3. Merkle DAG yapısı

IPFS içeriği bir Merkle DAG’da organize eder, burada:

  • Her düğümün bir CID’si vardır
  • Ebeveyn düğümler CID ile alt düğümlere referans verir
  • Herhangi bir düğümdeki değişiklikler ağaç boyunca yayılır
  • Tüm yapılar kriptografik olarak doğrulanabilir
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Pratik örnekler: CID’lerle çalışma

IPFS Ninja API kullanarak CID’lerle pratikte nasıl çalışılacağını keşfedelim:

İçerik yükleme ve CID alma

// 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

CID ile mevcut içeriği sabitleme

Zaten bir CID’niz varsa, kullanılabilirliği garanti etmek için onu sabitleyebilirsiniz:

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');

CID üzerinden içeriğe erişim

Bir CID’niz olduğunda, içeriğe çeşitli yöntemlerle erişebilirsiniz:

// 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;
};

Geliştiriciler için CID en iyi uygulamaları

1. CID’leri her zaman doğrulayın

Bir CID’yi uygulamanızda kullanmadan önce formatını doğrulayın:

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. Her iki CID sürümünü de işleyin

Uygulamanız hem CIDv0 hem de CIDv1 ile çalışmalıdır:

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. CID eşlemelerini önbelleğe alın

Sık sık CID oluşturuyorsanız, önbelleğe almayı düşünün:

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. Anlamlı açıklamalar kullanın

İçerik yüklerken, açıklayıcı metadata ekleyin:

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'
      }
    })
  });
};

Yaygın CID kullanım durumları

1. Statik web sitesi dağıtımı

Tüm web sitelerini IPFS’e dağıtın ve CID ile referans verin:

// 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;
};

Web sitesi dağıtımı hakkında daha fazla bilgi için, IPFS’e dosya nasıl yüklenir kılavuzumuza göz atın.

2. NFT metadata depolama

NFT metadata’yı CID’ler kullanarak değişmez şekilde saklayın:

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. İçerik dağıtımı

Dağıtık içerik teslimatı için CID’leri kullanın:

// 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 };
};

CID’lerle IPFS sabitlemeyi anlamak

CID’ler varsayılan olarak geçicidir — kullanılabilir kalmaları için “sabitlenmeleri” gerekir. Bu önemli kavram hakkında daha fazla bilgi için, IPFS sabitlemenin ne olduğu hakkındaki kapsamlı kılavuzumuza bakın.

Bir IPFS sabitleme hizmeti seçerken, IPFS Ninja vs Pinata karşılaştırmamızı okumayı düşünün veya bugün mevcut olan en iyi IPFS sabitleme hizmetlerinin özetimizi keşfedin.

30 saniyede ilk CID’nizi oluşturun

İlk CID’nizi oluşturmaya hazır mısınız? IPFS Ninja API kullanarak hızlı bir örnek:

# 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();

Bu şöyle bir şey döndürecek:

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

Daha ayrıntılı API örnekleri için, IPFS yükleme API eğitici belgemize bakın.

Sonuç

CID’ler, IPFS’in içerik adresleme sisteminin temelidir ve değişmez, doğrulanabilir ve merkeziyetsiz içerik tanımlaması sağlar. Nasıl çalıştıklarını anlamak — CIDv0 vs CIDv1’in teknik detaylarından pratik uygulama desenlerine kadar — sağlam merkeziyetsiz uygulamalar geliştirmek için çok önemlidir.

Temel çıkarımlar:

  • CID’ler içeriği benzersiz olarak tanımlar, konumları değil
  • CIDv0 maksimum uyumluluk sağlar, CIDv1 esneklik sunar
  • İçerik adresleme doğrulama ve tekilleştirmeyi sağlar
  • Doğru CID işleme, üretim uygulamaları için çok önemlidir

İster NFT metadata saklıyor, ister merkeziyetsiz web siteleri dağıtıyor, ister içerik dağıtım sistemleri geliştiriyor olun, CID’ler gerçek anlamda merkeziyetsiz uygulamalar için ihtiyacınız olan güvenilir temeli sağlar.

Sabitlemeye başlamaya hazır mısınız? Ücretsiz hesap oluşturun — 50 dosya, 1 GB depolama, 2 GB bant genişliği/ay. Kredi kartı gerekmez.

Share:
Blog'a Dön

İlgili Yazılar

Tüm Yazıları Gör »
IPFS Pinleme Nedir? 2026'da Bilmeniz Gereken Her Şey

IPFS Pinleme Nedir? 2026'da Bilmeniz Gereken Her Şey

IPFS pinlemenin ne olduğunu, dosyaların pinleme olmadan neden kaybolduğunu, uzak pinleme servislerinin nasıl çalıştığını ve ilk dosyanızı nasıl pinleyeceğinizi öğrenin. Örneklerle eksiksiz kılavuz.