CAR Import (DAG Import)

Uvozite celotne IPFS DAG-e v enem samem zahtevku z uporabo CAR (Content Addressable aRchive) datotek. Vasi CID-ji so ohranjeni natancno -- brez ponovnega razdeljevanja ali ponovnega zgoscevanja.

Kaj je CAR datoteka?

CAR datoteka zapakira celotno IPFS drevo imenikov ali DAG v en sam prenosljiv arhiv. Vsak blok je shranjen s svojim originalnim CID-jem, zato storitev uvozi vse kot je. To pomeni:

• Ohranitev CID -- izracunajte CID-je lokalno, preverite, da storitev vrne natancno enak CID
• Skupinski prenos -- nalozite na stotine datotek v enem zahtevku namesto ene za drugo
• Selitev ponudnika -- izvozite DAG od drugega ponudnika, uvozite v IPFS Ninja z identicnimi CID-ji
• Prilagojeni DAG-i -- nalozite katero koli IPLD podatkovno strukturo neposredno

REST API

POST /upload/new

Ista koncna tocka kot pri obicajnih nalaganje -- dodajte car: true za oznacitev CAR uvoza.

Telo zahtevka

Parameter	Tip	Obvezno	Opis
content	string	Da	Base64-kodirana CAR datoteka
car	boolean	Da	Nastavite na true za omogocanje CAR uvoza
description	string	Ne	Kratek opis uvoza
folderId	string	Ne	ID mape za organizacijo uvozene vsebine
metadata	object	Ne	Pari kljuc-vrednost po meri (enaka pravila kot pri obicajnih nalaganje)

Primer: Uvoz CAR datoteke s curl

Korak 1: Ustvarite CAR datoteko iz lokalnega imenika z uporabo ipfs-car:

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

Korak 2: Nalozite CAR datoteko:

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

Primer: Uvoz CAR datoteke z 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);

Primer: Uvoz CAR datoteke s 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"])

Odgovor 200 OK

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

S3-Compatible API

Uporabite glavo x-amz-meta-import: car pri zahtevku PutObject za uvoz CAR datoteke prek 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" }   // ← sprozzi CAR uvoz
}));

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

MCP Server

Orodje ipfs_import_car je na voljo v 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...

Ustvarjanje CAR datotek

Iz imenika (priporoceno)

Uporabite orodje CLI ipfs-car:

# Namestitev
npm install -g ipfs-car

# Zapakirajte imenik v CAR datoteko
ipfs-car pack ./my-directory -o my-archive.car

# Preverite korenski CID pred nalaganjem
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Iz delujocega IPFS vozlisca

Izvozite katerikoli CID kot CAR datoteko z uporabo Kubo CLI:

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

Programsko z JavaScript

Uporabite knjiznico @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);

Preverjanje celovitosti CID

Kljucna prednost CAR uvoza je ohranitev CID. Korenski CID lahko preverite pred in po nalaganju:

# 1. Zapakirajte imenik in si zabelezite korenski CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Nalozite na 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-ja se ujemata -- vsebina je uvozena natancno tako, kot je bila zgrajena lokalno

Selitev iz drugega ponudnika

Iz Pinata

# Izvoz iz Pinata prek IPFS prehoda
ipfs dag export QmYourCID > export.car

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

Iz Filebase

# Filebase podpira CAR izvoz prek svojega S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

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

Omejitve

Omejitev	Vrednost
Najvecja velikost CAR datoteke	100 MB
Najvec en koren	Mora imeti vsaj en korenski CID
CAR format	CARv1 (univerzalno podprt)
Razpolozljivost	Vsi narocninski nacrti (Dharma, Bodhi, Nirvana)

Omejitve prostora in stevila datotek iz vasega narocniskega nacrta veljajo. Uvozeni DAG steje kot en vnos datoteke, velikost CAR datoteke pa se odsteje od vase kvote prostora.

Odpravljanje tezav

"invalid CAR file: too small"

Nalozena vsebina je manjsa od 40 bajtov, kar je premajhno za veljavno CAR datoteko. Prepricajte se, da posiljate celotno base64-kodirano CAR vsebino.

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

Dekodirana CAR datoteka presega 100 MB. Razdelite svojo vsebino na vec manjsih CAR datotek z uporabo paketa carbites ali nalozite datoteke posamezno.

"dag/import did not return a root CID"

IPFS vozlisce ni moglo obdelati CAR datoteke. Preverite, da je datoteka veljaven CARv1 arhiv:

ipfs-car roots my-archive.car

Ce ta ukaz ne uspe, je CAR datoteka napacno oblikovana. Ponovno jo ustvarite z ipfs-car pack ali ipfs dag export.

"not enough storage"

Omejitev prostora vasega narocniskega nacrta je bila dosezena. Izbrisite neuporabljene datoteke ali nadgradite svoj nacrt na ipfs.ninja/pricing.