CAR Import (DAG Import)

Import keseluruhan DAG IPFS dalam satu permintaan menggunakan fail CAR (Content Addressable aRchive). CID anda dikekalkan dengan tepat — tiada penghirisan semula atau penghasilan semula hash.

Apakah itu fail CAR?

Fail CAR membungkus keseluruhan pokok direktori IPFS atau DAG ke dalam satu arkib mudah alih. Setiap blok disimpan dengan CID asalnya, jadi perkhidmatan ini mengimport semuanya seperti sedia ada. Ini bermakna:

• Pengekalan CID — kira CID secara setempat, sahkan perkhidmatan mengembalikan CID yang sama tepat
• Muat naik kelompok — muat naik ratusan fail dalam satu permintaan dan bukannya satu persatu
• Migrasi penyedia — eksport DAG daripada penyedia lain, import ke IPFS Ninja dengan CID yang sama
• DAG tersuai — muat naik sebarang struktur data IPLD secara terus

Muat Naik melalui Papan Pemuka

Dua laluan drag-and-drop pada /upload menggunakan aliran import yang sama ini — tiada kod diperlukan:

• Lepaskan fail .car. Zon muat naik mengesan sambungan secara automatik, memaparkan banner "CAR archive detected", dan butang hantar bertukar menjadi "Import <filename> as CAR". CID akar arkib itu sendiri dikekalkan.
• Lepaskan folder. Papan pemuka membungkus folder tersebut menjadi DAG UnixFS dalam pelayar anda (menggunakan ipfs-unixfs-importer dengan chunker moden 1 MiB mengikut IPIP-0499) dan memuat naik CAR yang terhasil melalui laluan yang sama. CID akar adalah direktori bafybei… yang boleh diselesaikan pada /ipfs/{cid}/{subpath}.

Kedua-duanya menggunakan aliran presigned-PUT untuk apa-apa yang melebihi beberapa MB — had saiz fail ialah 5 GB setiap CAR.

REST API

POST /upload/new

Endpoint yang sama seperti muat naik biasa — tambah car: true untuk menandakan import CAR.

Badan permintaan

Parameter	Jenis	Diperlukan	Penerangan
content	string	Ya	Fail CAR yang dikodkan Base64
car	boolean	Ya	Tetapkan kepada true untuk mengaktifkan import CAR
description	string	Tidak	Penerangan ringkas import
folderId	string	Tidak	ID folder untuk menyusun kandungan yang diimport
metadata	object	Tidak	Pasangan kunci-nilai tersuai (peraturan sama seperti muat naik biasa)

Contoh: Import fail CAR dengan curl

Langkah 1: Cipta fail CAR daripada direktori setempat menggunakan ipfs-car:

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

Langkah 2: Muat naik fail 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\"
  }"

Contoh: Import fail CAR dengan 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);

Contoh: Import fail CAR dengan 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"])

Respons 200 OK

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

Bagaimana pengiraan fail berfungsi

Setiap fail di dalam CAR dikira secara individu terhadap had fail pelan anda. CAR yang mengandungi 12 fail menggunakan 13 slot (12 fail anak + 1 entri CAR akar). CAR fail tunggal dikira sebagai 1 slot.

• Storan dikenakan sekali sahaja pada entri CAR akar (saiz penuh fail CAR)
• Fail anak individu muncul dalam senarai fail anda dengan CID akar dalam metadata mereka (carParentCid) supaya anda boleh mengumpulkannya
• Maksimum 1000 fail setiap import CAR — DAG yang lebih besar mesti dipecahkan kepada berbilang import

Jika mengimport CAR akan melebihi had bilangan fail pelan anda, permintaan ditolak dengan ralat 402 dan kandungan dinyahsemat secara automatik:

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

API Serasi S3

Gunakan header x-amz-meta-import: car pada permintaan PutObject untuk mengimport fail CAR melalui 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" }   // ← mencetuskan import CAR
}));

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

MCP Server

Alat ipfs_import_car tersedia dalam 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...

Mencipta Fail CAR

Daripada direktori (disyorkan)

Gunakan alat CLI ipfs-car:

# 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

Daripada nod IPFS yang sedang berjalan

Eksport sebarang CID sebagai fail CAR menggunakan Kubo CLI:

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

Secara pengaturcaraan dengan JavaScript

Gunakan pustaka @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);

Mengesahkan Integriti CID

Manfaat utama import CAR ialah pengekalan CID. Anda boleh mengesahkan CID akar sepadan sebelum dan selepas muat naik:

# 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 sepadan — kandungan diimport tepat seperti yang dibina secara setempat

Migrasi daripada Penyedia Lain

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

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

Had

Had	Nilai
Saiz maksimum fail CAR	100 MB
Akar tunggal maksimum	Mesti mempunyai sekurang-kurangnya satu CID akar
Format CAR	CARv1 (disokong secara universal)
Ketersediaan	Semua pelan (Dharma, Bodhi, Nirvana)

Had storan dan bilangan fail daripada pelan anda terpakai. DAG yang diimport dikira sebagai satu entri fail, dan saiz fail CAR ditolak daripada kuota storan anda.

Penyelesaian Masalah

"invalid CAR file: too small"

Kandungan yang dimuat naik kurang daripada 40 bait, yang terlalu kecil untuk menjadi fail CAR yang sah. Pastikan anda menghantar kandungan CAR penuh yang dikodkan base64.

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

Fail CAR yang dinyahkod melebihi 100 MB. Bahagikan kandungan anda kepada beberapa fail CAR yang lebih kecil menggunakan pakej carbites, atau muat naik fail secara individu.

"dag/import did not return a root CID"

Nod IPFS tidak dapat memproses fail CAR. Sahkan fail tersebut adalah arkib CARv1 yang sah:

ipfs-car roots my-archive.car

Jika arahan ini gagal, fail CAR rosak. Jana semula dengan ipfs-car pack atau ipfs dag export.

"not enough storage"

Had storan pelan anda telah dicapai. Padam fail yang tidak digunakan atau naik taraf pelan anda di ipfs.ninja/pricing.