CAR Import (DAG Import)

CAR (Content Addressable aRchive) dosyalarını kullanarak tek bir istekle tam IPFS DAG'lerini içe aktarın. CID'leriniz tam olarak korunur — yeniden parçalama veya yeniden hashleme yapılmaz.

CAR dosyası nedir?

Bir CAR dosyası, tam bir IPFS dizin ağacını veya DAG'yi tek bir taşınabilir arşivde paketler. Her blok orijinal CID'si ile saklanır, böylece hizmet her şeyi olduğu gibi içe aktarır. Bu şu anlama gelir:

• CID koruması — CID'leri yerel olarak hesaplayın, hizmetin tam olarak aynı CID'yi döndürdüğünü doğrulayın
• Toplu yükleme — tek tek yerine yüzlerce dosyayı tek bir istekle yükleyin
• Sağlayıcı göçü — başka bir sağlayıcıdan bir DAG dışa aktarın, aynı CID'lerle IPFS Ninja'ya içe aktarın
• Özel DAG'ler — herhangi bir IPLD veri yapısını doğrudan yükleyin

REST API

POST /upload/new

Normal yüklemelerle aynı endpoint — CAR içe aktarımını belirtmek için car: true ekleyin.

İstek gövdesi

Parametre	Tür	Zorunlu	Açıklama
content	string	Evet	Base64 kodlanmış CAR dosyası
car	boolean	Evet	CAR içe aktarımını etkinleştirmek için true olarak ayarlayın
description	string	Hayır	İçe aktarımın kısa açıklaması
folderId	string	Hayır	İçe aktarılan içeriği düzenlemek için klasör ID'si
metadata	object	Hayır	Özel anahtar-değer çiftleri (normal yüklemelerle aynı kurallar)

Örnek: curl ile bir CAR dosyasını içe aktarma

Adım 1: ipfs-car kullanarak yerel bir dizinden CAR dosyası oluşturun:

npx ipfs-car pack ./my-directory -o my-archive.car

Adım 2: CAR dosyasını yükleyin:

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\": \"$(base64 -w0 my-archive.car)\",
    \"car\": true,
    \"description\": \"My directory import\"
  }"

Örnek: JavaScript ile bir CAR dosyasını içe aktarma

import fs from "fs";

const carBuffer = fs.readFileSync("my-archive.car");
const base64Content = carBuffer.toString("base64");

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: base64Content,
    car: true,
    description: "My directory import"
  })
});

const result = await response.json();
console.log("Root CID:", result.cid);
console.log("Gateway:", result.uris.url);

Örnek: Python ile bir CAR dosyasını içe aktarma

import requests
import base64

with open("my-archive.car", "rb") as f:
    car_content = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.ipfs.ninja/upload/new",
    headers={
        "X-Api-Key": "bws_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "content": car_content,
        "car": True,
        "description": "My directory import"
    }
)

result = response.json()
print("Root CID:", result["cid"])
print("Gateway:", result["uris"]["url"])

Yanıt 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 4.2,
  "car": true,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

S3 Uyumlu API

CAR dosyasını S3 API üzerinden içe aktarmak için PutObject isteğinde x-amz-meta-import: car başlığını kullanın.

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import fs from "fs";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: {
    accessKeyId: "bws_628bba35",
    secretAccessKey: "bws_628bba35e9e0079d9ff9c392b1b55a7b"
  },
  region: "us-east-1",
  forcePathStyle: true
});

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-archive.car",
  Body: fs.readFileSync("my-archive.car"),
  ContentType: "application/vnd.ipld.car",
  Metadata: { import: "car" }   // ← CAR içe aktarımını tetikler
}));

console.log("Root CID:", result.ETag);

MCP Server

ipfs_import_car aracı MCP Server (v1.3.0+) içinde mevcuttur:

You: Import my-archive.car to IPFS
Claude: [calls ipfs_import_car with base64 content]
     → Root CID: bafybeig... — https://ipfs.ninja/ipfs/bafybeig...

CAR Dosyaları Oluşturma

Bir dizinden (önerilen)

ipfs-car CLI aracını kullanın:

# Kurulum
npm install -g ipfs-car

# Bir dizini CAR dosyasına paketleme
ipfs-car pack ./my-directory -o my-archive.car

# Yüklemeden önce kök CID'yi kontrol etme
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Çalışan bir IPFS düğümünden

Kubo CLI kullanarak herhangi bir CID'yi CAR dosyası olarak dışa aktarın:

ipfs dag export QmXyz... > my-archive.car

JavaScript ile programatik olarak

@ipld/car kütüphanesini kullanın:

import { CarWriter } from "@ipld/car";
import { CID } from "multiformats/cid";
import * as raw from "multiformats/codecs/raw";
import { sha256 } from "multiformats/hashes/sha2";

// Bloklar oluşturma
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

// CAR yazma
const { writer, out } = CarWriter.create([cid1]);
writer.put({ cid: cid1, bytes: block1 });
writer.close();

// Çıktıyı toplama
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

CID Bütünlüğünü Doğrulama

CAR içe aktarımının temel faydası CID korumasıdır. Kök CID'nin yükleme öncesi ve sonrasında eşleştiğini doğrulayabilirsiniz:

# 1. Dizini paketleyin ve kök CID'yi not edin
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. IPFS Ninja'ya yükleyin
curl -s -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 collection.car)\", \"car\": true}" \
  | jq .cid
# "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
# ✓ CID'ler eşleşiyor — içerik yerel olarak oluşturulduğu şekliyle içe aktarıldı

Başka Bir Sağlayıcıdan Göç

Pinata'dan

# IPFS ağ geçidini kullanarak Pinata'dan dışa aktarma
ipfs dag export QmYourCID > export.car

# IPFS Ninja'ya içe aktarma
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Filebase'den

# Filebase, S3 API üzerinden CAR dışa aktarımını destekler
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# IPFS Ninja'ya içe aktarma
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Limitler

Limit	Değer
Maksimum CAR dosya boyutu	100 MB
Maksimum tek kök	En az bir kök CID bulunmalıdır
CAR formatı	CARv1 (evrensel olarak desteklenir)
Erişilebilirlik	Tüm planlar (Dharma, Bodhi, Nirvana)

Planınızdaki depolama ve dosya sayısı limitleri geçerlidir. İçe aktarılan DAG tek bir dosya girişi olarak sayılır ve CAR dosya boyutu depolama kotanızdan düşülür.

Sorun Giderme

"invalid CAR file: too small"

Yüklenen içerik 40 bayttan küçüktür, bu geçerli bir CAR dosyası için çok küçüktür. Tam base64 kodlanmış CAR içeriğini gönderdiğinizden emin olun.

"File too large. Maximum upload size is 100 MB."

Çözümlenen CAR dosyası 100 MB'ı aşıyor. carbites paketini kullanarak içeriğinizi birden fazla küçük CAR dosyasına bölün veya dosyaları tek tek yükleyin.

"dag/import did not return a root CID"

IPFS düğümü CAR dosyasını işleyemedi. Dosyanın geçerli bir CARv1 arşivi olduğunu doğrulayın:

ipfs-car roots my-archive.car

Bu komut başarısız olursa, CAR dosyası hatalıdır. ipfs-car pack veya ipfs dag export ile yeniden oluşturun.

"not enough storage"

Planınızın depolama limiti dolmuştur. Kullanılmayan dosyaları silin veya ipfs.ninja/pricing adresinden planınızı yükseltin.