CAR Import (DAG Import)

Importuj całe DAG-i IPFS w jednym żądaniu za pomocą plików CAR (Content Addressable aRchive). Twoje CID-y są zachowywane dokładnie — bez ponownego dzielenia na fragmenty ani ponownego hashowania.

Czym jest plik CAR?

Plik CAR pakuje całe drzewo katalogów IPFS lub DAG w jedno przenośne archiwum. Każdy blok jest przechowywany z oryginalnym CID, więc usługa importuje wszystko bez zmian. Oznacza to:

• Zachowanie CID — oblicz CID-y lokalnie, zweryfikuj, że usługa zwraca dokładnie ten sam CID
• Przesyłanie zbiorcze — prześlij setki plików w jednym żądaniu zamiast pojedynczo
• Migracja dostawcy — wyeksportuj DAG od innego dostawcy, zaimportuj do IPFS Ninja z identycznymi CID-ami
• Niestandardowe DAG-i — prześlij dowolną strukturę danych IPLD bezpośrednio

REST API

POST /upload/new

Ten sam endpoint co w przypadku zwykłych przesyłań — dodaj car: true, aby wskazać import CAR.

Treść żądania

Parametr	Typ	Wymagany	Opis
content	string	Tak	Plik CAR zakodowany w Base64
car	boolean	Tak	Ustaw na true, aby włączyć import CAR
description	string	Nie	Krótki opis importu
folderId	string	Nie	ID folderu do organizacji zaimportowanej zawartości
metadata	object	Nie	Niestandardowe pary klucz-wartość (te same zasady co w zwykłych przesyłaniach)

Przykład: Import pliku CAR za pomocą curl

Krok 1: Utwórz plik CAR z lokalnego katalogu za pomocą ipfs-car:

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

Krok 2: Prześlij plik 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\"
  }"

Przykład: Import pliku CAR za pomocą 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);

Przykład: Import pliku CAR za pomocą 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"])

Odpowiedź 200 OK

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

API zgodne z S3

Użyj nagłówka x-amz-meta-import: car w żądaniu PutObject, aby zaimportować plik CAR przez S3 API.

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

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

MCP Server

Narzędzie ipfs_import_car jest dostępne w 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...

Tworzenie plików CAR

Z katalogu (zalecane)

Użyj narzędzia CLI ipfs-car:

# Zainstaluj
npm install -g ipfs-car

# Zapakuj katalog do pliku CAR
ipfs-car pack ./my-directory -o my-archive.car

# Sprawdź główny CID przed przesłaniem
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Z działającego węzła IPFS

Wyeksportuj dowolny CID jako plik CAR za pomocą Kubo CLI:

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

Programowo za pomocą JavaScript

Użyj biblioteki @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);

Weryfikacja integralności CID

Główną zaletą importu CAR jest zachowanie CID. Możesz zweryfikować, czy główny CID jest zgodny przed i po przesłaniu:

# 1. Zapakuj katalog i zanotuj główny CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Prześlij do 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"
# ✓ CID-y są zgodne — zawartość zaimportowana dokładnie tak, jak zbudowana lokalnie

Migracja od innego dostawcy

Z Pinata

# Eksport z Pinata za pomocą IPFS gateway
ipfs dag export QmYourCID > export.car

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

Z Filebase

# Filebase obsługuje eksport CAR przez ich S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

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

Limity

Limit	Wartość
Maksymalny rozmiar pliku CAR	100 MB
Maksymalnie jeden root	Musi mieć co najmniej jeden główny CID
Format CAR	CARv1 (uniwersalnie obsługiwany)
Dostępność	Wszystkie plany (Dharma, Bodhi, Nirvana)

Obowiązują limity przechowywania i liczby plików z Twojego planu. Zaimportowany DAG jest liczony jako jeden wpis pliku, a rozmiar pliku CAR jest odejmowany od Twojego limitu przechowywania.

Rozwiązywanie problemów

"invalid CAR file: too small"

Przesłana zawartość ma mniej niż 40 bajtów, co jest zbyt mało, aby być prawidłowym plikiem CAR. Upewnij się, że wysyłasz pełną zawartość CAR zakodowaną w base64.

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

Zdekodowany plik CAR przekracza 100 MB. Podziel zawartość na kilka mniejszych plików CAR za pomocą pakietu carbites lub prześlij pliki pojedynczo.

"dag/import did not return a root CID"

Węzeł IPFS nie mógł przetworzyć pliku CAR. Sprawdź, czy plik jest prawidłowym archiwum CARv1:

ipfs-car roots my-archive.car

Jeśli to polecenie się nie powiedzie, plik CAR jest uszkodzony. Wygeneruj go ponownie za pomocą ipfs-car pack lub ipfs dag export.

"not enough storage"

Limit przechowywania Twojego planu został osiągnięty. Usuń nieużywane pliki lub ulepsz swój plan na ipfs.ninja/pricing.