CAR Import (DAG Import)

Importējiet veselus IPFS DAG vienā pieprasījumā, izmantojot CAR (Content Addressable aRchive) failus. Jūsu CID tiek saglabāti precīzi — bez atkārtotas sadalīšanas vai atkārtotas hešošanas.

Kas ir CAR fails?

CAR fails iepako visu IPFS direktoriju koku vai DAG vienā pārnēsājamā arhīvā. Katrs bloks tiek saglabāts ar sākotnējo CID, tāpēc serviss importē visu tieši tā, kā tas ir. Tas nozīmē:

• CID saglabāšana — aprēķiniet CID lokāli, pārbaudiet, vai serviss atgriež tieši to pašu CID
• Pakešu augšupielāde — augšupielādējiet simtiem failu vienā pieprasījumā, nevis pa vienam
• Pakalpojumu sniedzēja migrācija — eksportējiet DAG no cita pakalpojumu sniedzēja, importējiet uz IPFS Ninja ar identiskiem CID
• Pielāgoti DAG — augšupielādējiet jebkuru IPLD datu struktūru tieši

Augšupielāde caur informācijas paneli

Divi vilkt-un-nomest ceļi /upload izmanto šo pašu importa plūsmu — kods nav vajadzīgs:

• Nometiet .car failu. Augšupielādes zona automātiski atklāj paplašinājumu, parāda "CAR archive detected" baneri, un iesniegšanas poga kļūst par "Import <filename> as CAR". Tiek saglabāts arhīva paša saknes CID.
• Nometiet mapi. Informācijas panelis iepako mapi UnixFS DAG jūsu pārlūkā (izmantojot ipfs-unixfs-importer ar moderno 1 MiB gabalu veidotāju saskaņā ar IPIP-0499) un augšupielādē rezultējošo CAR caur šo pašu ceļu. Saknes CID ir bafybei… direktorija, kas atrisinās /ipfs/{cid}/{subpath}.

Abi izmanto presigned-PUT plūsmu jebkam virs dažiem MB — faila izmēra ierobežojums ir 5 GB katram CAR.

REST API

POST /upload/new

Tas pats endpoint kā parastām augšupielādēm — pievienojiet car: true, lai signalizētu CAR importu.

Pieprasījuma pamatteksts

Parametrs	Tips	Obligāts	Apraksts
content	string	Jā	Base64 kodēts CAR fails
car	boolean	Jā	Iestatiet uz true, lai iespējotu CAR importu
description	string	Nē	Īss importa apraksts
folderId	string	Nē	Mapes ID, lai sakārtotu importēto saturu
metadata	object	Nē	Pielāgoti atslēgas-vērtības pāri (tie paši noteikumi kā parastām augšupielādēm)

Piemērs: CAR faila importēšana ar curl

1. solis: Izveidojiet CAR failu no lokālas direktorijas, izmantojot ipfs-car:

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

2. solis: Augšupielādējiet CAR failu:

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

Piemērs: CAR faila importēšana ar 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);

Piemērs: CAR faila importēšana ar 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"])

Atbilde 200 OK

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

Kā darbojas failu skaitīšana

Katrs CAR iekšējais fails tiek skaitīts atsevišķi pret jūsu plāna faila limitu. CAR, kas satur 12 failus, izmanto 13 vietas (12 bērnfaili + 1 saknes CAR ieraksts). Viena faila CAR skaitās kā 1 vieta.

• Glabātuve tiek iekasēta vienreiz par saknes CAR ierakstu (pilnais CAR faila izmērs)
• Individuāli bērnfaili parādās jūsu failu sarakstā ar saknes CID to metadatos (carParentCid), lai varētu tos grupēt
• Maksimums 1000 faili katram CAR importam — lielāki DAG jāsadala vairākos importos

Ja CAR importēšana pārsniegtu jūsu plāna faila skaita limitu, pieprasījums tiek noraidīts ar 402 kļūdu un saturs tiek automātiski atspraudēts:

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

S3 saderīgais API

Izmantojiet x-amz-meta-import: car galveni PutObject pieprasījumā, lai importētu CAR failu caur 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" }   // ← aktivizē CAR importu
}));

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

MCP Server

Rīks ipfs_import_car ir pieejams 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 failu izveide

No direktorijas (ieteicams)

Izmantojiet ipfs-car CLI rīku:

# 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

No darbojoša IPFS mezgla

Eksportējiet jebkuru CID kā CAR failu, izmantojot Kubo CLI:

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

Programmatiski ar JavaScript

Izmantojiet @ipld/car bibliotēku:

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

CID integritātes pārbaude

Galvenais CAR importa ieguvums ir CID saglabāšana. Jūs varat pārbaudīt, vai saknes CID sakrīt pirms un pēc augšupielādes:

# 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ācija no cita pakalpojumu sniedzēja

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

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

Ierobežojumi

Ierobežojums	Vērtība
Maksimālais CAR faila lielums	100 MB
Maksimālā viena sakne	Jābūt vismaz vienam saknes CID
CAR formāts	CARv1 (universāli atbalstīts)
Pieejamība	Visi plāni (Dharma, Bodhi, Nirvana)

Jūsu plāna krātuves un failu skaita ierobežojumi ir spēkā. Importētais DAG tiek skaitīts kā viens faila ieraksts, un CAR faila lielums tiek atskaitīts no jūsu krātuves kvotas.

Problēmu novēršana

"invalid CAR file: too small"

Augšupielādētais saturs ir mazāks par 40 baitiem, kas ir pārāk mazs, lai būtu derīgs CAR fails. Pārliecinieties, ka sūtāt pilnu base64 kodētu CAR saturu.

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

Atkodētais CAR fails pārsniedz 100 MB. Sadaliet saturu vairākos mazākos CAR failos, izmantojot carbites pakotni, vai augšupielādējiet failus atsevišķi.

"dag/import did not return a root CID"

IPFS mezgls nevarēja apstrādāt CAR failu. Pārbaudiet, vai fails ir derīgs CARv1 arhīvs:

ipfs-car roots my-archive.car

Ja šī komanda neizdodas, CAR fails ir bojāts. Ģenerējiet to no jauna ar ipfs-car pack vai ipfs dag export.

"not enough storage"

Jūsu plāna krātuves ierobežojums ir sasniegts. Dzēsiet neizmantotos failus vai jauniniet savu plānu vietnē ipfs.ninja/pricing.