CAR importas (DAG importas)

Importuokite visas IPFS DAG struktūras vienos užklausos metu naudodami CAR (Content Addressable aRchive) failus. Jūsų CID išsaugomi tiksliai — be pakartotinio skaidymo ar maišos perskaičiavimo.

Kas yra CAR failas?

CAR failas supakuoja visą IPFS katalogo medį ar DAG į vieną nešiojamą archyvą. Kiekvienas blokas saugomas su savo originaliu CID, todėl paslauga importuoja viską tokį, koks jis yra. Tai reiškia:

• CID išsaugojimas — apskaičiuokite CID lokaliai, patikrinkite, ar paslauga grąžina tiksliai tą patį CID
• Masinis įkėlimas — įkelkite šimtus failų viena užklausa vietoj po vieną
• Tiekėjo migracija — eksportuokite DAG iš kito tiekėjo, importuokite į IPFS Ninja su identiškais CID
• Pasirinktinės DAG struktūros — tiesiogiai įkelkite bet kokią IPLD duomenų struktūrą

Įkėlimas per prietaisų skydelį

Du vilkimo ir numetimo (drag-and-drop) keliai /upload puslapyje veda į tą patį importo procesą — jokio kodo nereikia:

• Numeskite .car failą. Įkėlimo zona automatiškai aptinka plėtinį, parodo juostelę „CAR archyvas aptiktas“, o pateikimo mygtukas tampa „Importuoti <filename> kaip CAR“. Archyvo šaknies CID išsaugomas.
• Numeskite aplanką. Prietaisų skydelis supakuoja aplanką į UnixFS DAG jūsų naršyklėje (naudodamas ipfs-unixfs-importer su moderniu 1 MiB skaidikliu pagal IPIP-0499) ir įkelia gautą CAR per tą patį kelią. Šaknies CID yra bafybei… katalogas, kuris išsprendžiamas per /ipfs/{cid}/{subpath}.

Abu naudoja pasirašyto PUT (presigned-PUT) srautą viskam, kas didesnis nei kelis MB — failo dydžio riba yra 5 GB vienam CAR.

REST API

POST /upload/new

Tas pats galinis taškas kaip ir įprastiems įkėlimams — pridėkite car: true, kad nurodytumėte CAR importą.

Užklausos turinys

Parametras	Tipas	Privalomas	Aprašymas
content	string	Taip	Base64 koduotas CAR failas
car	boolean	Taip	Nustatykite į true, kad įgalintumėte CAR importą
description	string	Ne	Trumpas importo aprašymas
folderId	string	Ne	Aplanko ID importuotam turiniui organizuoti
metadata	object	Ne	Pritaikytos rakto-reikšmės poros (tos pačios taisyklės kaip įprastiems įkėlimams)

Pavyzdys: importuoti CAR failą su curl

1 žingsnis: Sukurkite CAR failą iš vietinio katalogo naudodami ipfs-car:

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

2 žingsnis: Įkelkite CAR failą:

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

Pavyzdys: importuoti CAR failą su 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);

Pavyzdys: importuoti CAR failą su 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"])

Atsakymas 200 OK

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

Kaip veikia failų skaičiavimas

Kiekvienas CAR viduje esantis failas skaičiuojamas individualiai jūsų plano failų limitui. CAR su 12 failų užima 13 vietų (12 vaikinių + 1 šaknies CAR įrašas). Vieno failo CAR skaičiuojamas kaip 1 vieta.

• Saugykla apmokestinama vieną kartą už šaknies CAR įrašą (viso CAR failo dydis)
• Atskiri vaikiniai failai rodomi jūsų failų sąraše su šaknies CID savo metaduomenyse (carParentCid), kad galėtumėte juos grupuoti
• Maksimalus 1000 failų vienam CAR importui — didesnės DAG struktūros turi būti padalintos į kelis importus

Jei importuojant CAR būtų viršytas jūsų plano failų skaičius, užklausa atmetama su 402 klaida, o turinys automatiškai atsegamas:

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

S3 suderinama API

Naudokite x-amz-meta-import: car antraštę PutObject užklausoje, kad importuotumėte CAR failą per 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" }   // ← triggers CAR import
}));

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

MCP Server

Įrankis ipfs_import_car yra prieinamas 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 failų kūrimas

Iš katalogo (rekomenduojama)

Naudokite ipfs-car CLI įrankį:

# 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

Iš veikiančio IPFS mazgo

Eksportuokite bet kurį CID kaip CAR failą naudodami Kubo CLI:

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

Programiškai su JavaScript

Naudokite @ipld/car biblioteką:

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 vientisumo tikrinimas

Pagrindinė CAR importo nauda yra CID išsaugojimas. Galite patikrinti, ar šaknies CID sutampa prieš ir po įkėlimo:

# 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"
# ✓ CID sutampa — turinys importuotas tiksliai taip, kaip buvo sukurtas lokaliai

Migracija iš kito tiekėjo

Iš 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}"

Iš 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}"

Ribos

Riba	Reikšmė
Maksimalus CAR failo dydis	100 MB
Maksimalus vienas šaknis	Turi turėti bent vieną šaknies CID
CAR formatas	CARv1 (universaliai palaikomas)
Prieinamumas	Visi planai (Dharma, Bodhi, Nirvana)

Taikomi jūsų plano saugyklos ir failų skaičiaus limitai. Importuota DAG skaičiuojama kaip vienas failo įrašas, o CAR failo dydis atimamas iš jūsų saugyklos kvotos.

Trikčių šalinimas

"invalid CAR file: too small"

Įkeltas turinys yra mažesnis nei 40 baitų, o tai per mažai, kad būtų galiojantis CAR failas. Įsitikinkite, kad siunčiate visą base64 koduotą CAR turinį.

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

Iškoduotas CAR failas viršija 100 MB. Padalinkite turinį į kelis mažesnius CAR failus naudodami carbites paketą arba įkelkite failus atskirai.

"dag/import did not return a root CID"

IPFS mazgas negalėjo apdoroti CAR failo. Patikrinkite, ar failas yra galiojantis CARv1 archyvas:

ipfs-car roots my-archive.car

Jei ši komanda nepavyksta, CAR failas yra netinkamai suformuotas. Sugeneruokite jį iš naujo su ipfs-car pack arba ipfs dag export.

"not enough storage"

Pasiektas jūsų plano saugyklos limitas. Ištrinkite nenaudojamus failus arba atnaujinkite savo planą adresu ipfs.ninja/pricing.