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
• 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

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,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

API Serasi S3

Gunakan pengepala 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:

# Pasang
npm install -g ipfs-car

# Bungkus direktori ke dalam fail CAR
ipfs-car pack ./my-directory -o my-archive.car

# Semak CID akar sebelum muat naik
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);

Pengesahan Integriti CID

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

# 1. Bungkus direktori dan catat CID akar
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Muat naik ke 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

# Eksport daripada Pinata menggunakan IPFS gateway
ipfs dag export QmYourCID > export.car

# Import ke 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 menyokong eksport CAR melalui S3 API mereka
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Import ke 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.