CAR Import (DAG Import)

Importați DAG-uri IPFS întregi într-o singură cerere folosind fișiere CAR (Content Addressable aRchive). CID-urile dvs. sunt păstrate exact — fără re-chunking sau re-hashing.

Ce este un fișier CAR?

Un fișier CAR împachetează un arbore de directoare IPFS întreg sau un DAG într-un singur fișier portabil. Fiecare bloc este stocat cu CID-ul său original, astfel încât serviciul importă totul exact așa cum este. Aceasta înseamnă:

• Păstrarea CID — calculați CID-urile local, verificați că serviciul returnează exact același CID
• Upload în lot — încărcați sute de fișiere într-o singură cerere în loc de unul câte unul
• Migrare de la alt furnizor — exportați un DAG de la alt furnizor, importați în IPFS Ninja cu CID-uri identice
• DAG-uri personalizate — încărcați orice structură de date IPLD direct

REST API

POST /upload/new

Același endpoint ca pentru upload-urile obișnuite — adăugați car: true pentru a semnala un import CAR.

Corpul cererii

Parametru	Tip	Obligatoriu	Descriere
content	string	Da	Fișier CAR codificat în Base64
car	boolean	Da	Setați la true pentru a activa importul CAR
description	string	Nu	Scurtă descriere a importului
folderId	string	Nu	ID-ul dosarului pentru organizarea conținutului importat
metadata	object	Nu	Perechi cheie-valoare personalizate (aceleași reguli ca pentru upload-urile obișnuite)

Exemplu: Importarea unui fișier CAR cu curl

Pasul 1: Creați un fișier CAR dintr-un director local folosind ipfs-car:

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

Pasul 2: Încărcați fișierul CAR:

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

Exemplu: Importarea unui fișier CAR cu JavaScript

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

Exemplu: Importarea unui fișier CAR cu Python

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"])

Răspuns 200 OK

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

S3-Compatible API

Folosiți antetul x-amz-meta-import: car într-o cerere PutObject pentru a importa un fișier CAR prin API-ul S3.

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" }   // ← declanșează importul CAR
}));

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

MCP Server

Instrumentul ipfs_import_car este disponibil în MCP Server (v1.3.0+):

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

Crearea Fișierelor CAR

Dintr-un director (recomandat)

Folosiți instrumentul CLI ipfs-car:

# Install
npm install -g ipfs-car

# Pack a directory into a CAR file
ipfs-car pack ./my-directory -o my-archive.car

# Check the root CID before uploading
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

De la un nod IPFS în execuție

Exportați orice CID ca fișier CAR folosind CLI-ul Kubo:

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

Programatic cu JavaScript

Folosiți biblioteca @ipld/car:

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

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

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

// Collect output
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

Verificarea Integrității CID

Principalul beneficiu al importului CAR este păstrarea CID. Puteți verifica că CID-ul rădăcină este identic înainte și după upload:

# 1. Pack directory and note the root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Upload to IPFS Ninja
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"
# ✓ CIDs match — content imported exactly as built locally

Migrarea de la Alt Furnizor

De la Pinata

# Export from Pinata using IPFS gateway
ipfs dag export QmYourCID > export.car

# Import to IPFS Ninja
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}"

De la Filebase

# Filebase supports CAR export via their S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Import to IPFS Ninja
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}"

Limite

Limită	Valoare
Dimensiune maximă fișier CAR	100 MB
Rădăcină unică maximă	Trebuie să aibă cel puțin un CID rădăcină
Format CAR	CARv1 (suportat universal)
Disponibilitate	Toate planurile (Dharma, Bodhi, Nirvana)

Limitele de stocare și număr de fișiere ale planului dvs. se aplică. DAG-ul importat contează ca o singură intrare de fișier, iar dimensiunea fișierului CAR este dedusă din cota dvs. de stocare.

Depanare

"invalid CAR file: too small"

Conținutul încărcat are mai puțin de 40 de octeți, ceea ce este prea mic pentru a fi un fișier CAR valid. Asigurați-vă că trimiteți conținutul CAR complet codificat în Base64.

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

Fișierul CAR decodificat depășește 100 MB. Împărțiți conținutul în mai multe fișiere CAR mai mici folosind pachetul carbites, sau încărcați fișierele individual.

"dag/import did not return a root CID"

Nodul IPFS nu a putut procesa fișierul CAR. Verificați dacă fișierul este o arhivă CARv1 validă:

ipfs-car roots my-archive.car

Dacă această comandă eșuează, fișierul CAR este malformat. Regenerați-l cu ipfs-car pack sau ipfs dag export.

"not enough storage"

Limita de stocare a planului dvs. a fost atinsă. Ștergeți fișierele neutilizate sau faceți upgrade la planul dvs. pe ipfs.ninja/pricing.