CAR import (DAG import)

Importáljon teljes IPFS DAG-okat egyetlen kéréssel CAR (Content Addressable aRchive) fájlok segítségével. A CID-jei pontosan megőrzésre kerülnek — nincs újradarabolás vagy újrahash-elés.

Mi az a CAR fájl?

Egy CAR fájl egy teljes IPFS könyvtárfát vagy DAG-ot csomagol egyetlen hordozható archívumba. Minden blokk az eredeti CID-jével kerül tárolásra, így a szolgáltatás mindent úgy importál, ahogy van. Ez azt jelenti:

• CID megőrzés — számítsa ki a CID-eket lokálisan, ellenőrizze, hogy a szolgáltatás pontosan ugyanazt a CID-et adja vissza
• Kötegelt feltöltés — töltsön fel több száz fájlt egyetlen kérésben, ahelyett hogy egyenként tenné
• Szolgáltatóváltás — exportáljon egy DAG-ot egy másik szolgáltatótól, importálja az IPFS Ninja-ra azonos CID-ekkel
• Egyéni DAG-ok — töltsön fel bármilyen IPLD adatstruktúrát közvetlenül

Feltöltés az irányítópulton keresztül

Két húzd-és-ejtsd útvonal a /upload oldalon ugyanezt az import folyamatot éri el — kód nélkül:

• Ejtsen egy .car fájlt. A feltöltési zóna automatikusan felismeri a kiterjesztést, megjelenít egy „CAR archívum észlelve" bannert, és a beküldés gomb „<fájlnév> importálása CAR-ként" lesz. Az archívum saját gyökér CID-je megőrzésre kerül.
• Ejtsen egy mappát. Az irányítópult a mappát a böngészőjében UnixFS DAG-gá csomagolja (az ipfs-unixfs-importer segítségével, az IPIP-0499 szerinti modern 1 MiB darabolóval), és az eredményül kapott CAR-t ugyanazon az útvonalon tölti fel. A gyökér CID egy bafybei… könyvtár, amely a /ipfs/{cid}/{subpath} címen oldódik fel.

Mindkettő az előre aláírt PUT folyamatot használja néhány MB felett — a fájlméret korlát 5 GB CAR-onként.

REST API

POST /upload/new

Ugyanaz a végpont, mint a szokásos feltöltéseknél — adja hozzá a car: true-t a CAR import jelzéséhez.

Kérés törzse

Paraméter	Típus	Kötelező	Leírás
content	string	Igen	Base64-kódolt CAR fájl
car	boolean	Igen	Állítsa true-ra a CAR import engedélyezéséhez
description	string	Nem	Az import rövid leírása
folderId	string	Nem	Mappa ID az importált tartalom rendszerezéséhez
metadata	object	Nem	Egyéni kulcs-érték párok (ugyanazok a szabályok, mint a szokásos feltöltéseknél)

Példa: CAR fájl importálása curl-lel

1. lépés: Hozzon létre egy CAR fájlt egy helyi könyvtárból az ipfs-car segítségével:

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

2. lépés: Töltse fel a CAR fájlt:

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

Példa: CAR fájl importálása JavaScripttel

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

Példa: CAR fájl importálása Pythonnal

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

Response 200 OK

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

Hogyan működik a fájlszámlálás

A CAR-on belüli minden fájl egyénileg számít bele a csomagja fájlkorlátjába. Egy 12 fájlt tartalmazó CAR 13 helyet foglal (12 gyermek + 1 gyökér CAR bejegyzés). Egy egyfájlos CAR 1 helyet foglal.

• A tárhely egyszer kerül felszámításra a gyökér CAR bejegyzésen (a teljes CAR fájl mérete)
• Az egyes gyermekfájlok megjelennek a fájllistájában, a gyökér CID-del a metaadataikban (carParentCid), így csoportosíthatja őket
• Legfeljebb 1000 fájl CAR importonként — nagyobb DAG-okat több importra kell osztani

Ha a CAR importálása meghaladná a csomagja fájlszám-korlátját, a kérés 402 hibával kerül elutasításra, és a tartalom automatikusan feloldásra kerül:

{
  "error": "file limit exceeded: this CAR contains 523 files, you have 800/1000. Upgrade your plan."
}

S3-kompatibilis API

Használja az x-amz-meta-import: car fejlécet egy PutObject kérésen egy CAR fájl importálásához az S3 API-n keresztül.

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" }   // ← triggers CAR import
}));

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

MCP szerver

Az ipfs_import_car eszköz elérhető az MCP szerverben (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...

CAR fájlok létrehozása

Egy könyvtárból (ajánlott)

Használja az ipfs-car parancssori eszközt:

# 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

Egy futó IPFS csomópontból

Exportáljon bármilyen CID-et CAR fájlként a Kubo CLI segítségével:

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

Programozottan JavaScripttel

Használja az @ipld/car könyvtárat:

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

A CID integritásának ellenőrzése

A CAR import legfontosabb előnye a CID megőrzés. Ellenőrizheti, hogy a gyökér CID megegyezik a feltöltés előtt és után:

# 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

Migrálás egy másik szolgáltatótól

A Pinatáról

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

A Filebase-ről

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

Korlátok

Korlát	Érték
Max CAR fájlméret	100 MB
Max egy gyökér	Legalább egy gyökér CID szükséges
CAR formátum	CARv1 (univerzálisan támogatott)
Elérhetőség	Minden csomagon (Dharma, Bodhi, Nirvana)

A csomagja tárhely- és fájlszám-korlátai érvényesek. Az importált DAG egy fájlbejegyzésként számít, és a CAR fájl mérete levonásra kerül a tárhelykeretéből.

Hibaelhárítás

„invalid CAR file: too small"

A feltöltött tartalom kevesebb mint 40 byte, ami túl kicsi ahhoz, hogy érvényes CAR fájl legyen. Győződjön meg róla, hogy a teljes base64-kódolt CAR tartalmat küldi.

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

A dekódolt CAR fájl meghaladja a 100 MB-ot. Ossza a tartalmát több kisebb CAR fájlra a carbites csomag segítségével, vagy töltse fel a fájlokat egyenként.

„dag/import did not return a root CID"

Az IPFS csomópont nem tudta feldolgozni a CAR fájlt. Ellenőrizze, hogy a fájl érvényes CARv1 archívum:

ipfs-car roots my-archive.car

Ha ez a parancs sikertelen, a CAR fájl hibás. Generálja újra az ipfs-car pack vagy az ipfs dag export paranccsal.

„not enough storage"

Elérte a csomagja tárhelykorlátját. Töröljön nem használt fájlokat, vagy frissítse a csomagját az ipfs.ninja/pricing oldalon.