CAR Import (DAG Import)

Импортирайте цели IPFS DAG структури с една заявка, използвайки CAR (Content Addressable aRchive) файлове. Вашите CID се запазват точно — без повторно разделяне или повторно хеширане.

Какво е CAR файл?

CAR файлът пакетира цяло IPFS дърво от директории или DAG в един преносим архив. Всеки блок се съхранява с оригиналния си CID, така че услугата импортира всичко без промени. Това означава:

• Запазване на CID — изчислете CID локално, проверете дали услугата връща абсолютно същия CID
• Групово качване — качете стотици файлове с една заявка вместо един по един
• Миграция на доставчик — експортирайте DAG от друг доставчик, импортирайте в IPFS Ninja със същите CID
• Потребителски DAG — качете всяка IPLD структура от данни директно

REST API

POST /upload/new

Същият endpoint като обикновените качвания — добавете car: true, за да укажете CAR импорт.

Тяло на заявката

Параметър	Тип	Задължителен	Описание
content	string	Да	Base64-кодиран CAR файл
car	boolean	Да	Задайте true, за да активирате CAR импорт
description	string	Не	Кратко описание на импорта
folderId	string	Не	ID на папка за организиране на импортираното съдържание
metadata	object	Не	Потребителски двойки ключ-стойност (същите правила като обикновените качвания)

Пример: Импортиране на CAR файл с curl

Стъпка 1: Създайте CAR файл от локална директория с помощта на ipfs-car:

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

Стъпка 2: Качете 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\"
  }"

Пример: Импортиране на CAR файл с 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);

Пример: Импортиране на CAR файл с 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"])

Отговор 200 OK

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

S3-съвместим API

Използвайте хедъра x-amz-meta-import: car при PutObject заявка, за да импортирате CAR файл чрез 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" }   // ← задейства CAR импорт
}));

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

MCP Server

Инструментът ipfs_import_car е наличен в 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...

Създаване на CAR файлове

От директория (препоръчително)

Използвайте CLI инструмента ipfs-car:

# Инсталиране
npm install -g ipfs-car

# Пакетиране на директория в CAR файл
ipfs-car pack ./my-directory -o my-archive.car

# Проверка на основния CID преди качване
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

От работещ IPFS възел

Експортирайте всеки CID като CAR файл с помощта на Kubo CLI:

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

Програмно с JavaScript

Използвайте библиотеката @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";

// Създаване на блокове
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

// Записване на CAR
const { writer, out } = CarWriter.create([cid1]);
writer.put({ cid: cid1, bytes: block1 });
writer.close();

// Събиране на резултата
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

Проверка на целостта на CID

Основното предимство на CAR импорта е запазването на CID. Можете да проверите дали основният CID съвпада преди и след качването:

# 1. Пакетирайте директорията и запишете основния CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Качете в 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 съвпадат — съдържанието е импортирано точно както е създадено локално

Мигриране от друг доставчик

От Pinata

# Експортиране от Pinata чрез IPFS gateway
ipfs dag export QmYourCID > export.car

# Импортиране в 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}"

От Filebase

# Filebase поддържа CAR експорт чрез техния S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Импортиране в 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}"

Ограничения

Ограничение	Стойност
Максимален размер на CAR файл	100 MB
Минимум основни CID	Поне един основен CID
CAR формат	CARv1 (универсално поддържан)
Наличност	Всички планове (Dharma, Bodhi, Nirvana)

Ограниченията за съхранение и брой файлове от вашия план се прилагат. Импортираният DAG се брои като един файлов запис, а размерът на CAR файла се приспада от квотата ви за съхранение.

Отстраняване на проблеми

"invalid CAR file: too small"

Каченото съдържание е по-малко от 40 байта, което е твърде малко за валиден CAR файл. Уверете се, че изпращате пълното base64-кодирано CAR съдържание.

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

Декодираният CAR файл надвишава 100 MB. Разделете съдържанието си на няколко по-малки CAR файла с помощта на пакета carbites или качете файловете поотделно.

"dag/import did not return a root CID"

IPFS възелът не можа да обработи CAR файла. Проверете дали файлът е валиден CARv1 архив:

ipfs-car roots my-archive.car

Ако тази команда не успее, CAR файлът е повреден. Генерирайте го отново с ipfs-car pack или ipfs dag export.

"not enough storage"

Лимитът за съхранение на вашия план е достигнат. Изтрийте неизползвани файлове или надградете плана си на ipfs.ninja/pricing.