CAR Import (DAG Import)

นำเข้า IPFS DAG ทั้งหมดในคำขอเดียวโดยใช้ไฟล์ CAR (Content Addressable aRchive) CID ของคุณจะถูกรักษาไว้ตรงตามเดิม -- ไม่มีการแบ่งชิ้นใหม่หรือแฮชใหม่

ไฟล์ CAR คืออะไร?

ไฟล์ CAR จะรวมแผนผังไดเรกทอรี IPFS หรือ DAG ทั้งหมดไว้ในไฟล์เก็บถาวรแบบพกพาไฟล์เดียว แต่ละบล็อกจะถูกจัดเก็บพร้อมกับ CID ดั้งเดิม ดังนั้นบริการจะนำเข้าทุกอย่างตามสภาพเดิม ซึ่งหมายความว่า:

• การรักษา CID -- คำนวณ CID ในเครื่อง ตรวจสอบว่าบริการส่งคืน CID เดียวกันทุกประการ
• อัปโหลดแบบกลุ่ม -- อัปโหลดไฟล์หลายร้อยไฟล์ในคำขอเดียวแทนที่จะทีละไฟล์
• การย้ายผู้ให้บริการ -- ส่งออก DAG จากผู้ให้บริการรายอื่น นำเข้าสู่ IPFS Ninja ด้วย CID ที่เหมือนกัน
• DAG แบบกำหนดเอง -- อัปโหลดโครงสร้างข้อมูล IPLD ใดก็ได้โดยตรง

REST API

POST /upload/new

endpoint เดียวกันกับการอัปโหลดปกติ -- เพิ่ม car: true เพื่อระบุว่าเป็นการนำเข้า CAR

เนื้อหาคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
content	string	ใช่	ไฟล์ CAR ที่เข้ารหัส Base64
car	boolean	ใช่	ตั้งค่าเป็น true เพื่อเปิดใช้งานการนำเข้า CAR
description	string	ไม่	คำอธิบายสั้น ๆ ของการนำเข้า
folderId	string	ไม่	ID โฟลเดอร์สำหรับจัดระเบียบเนื้อหาที่นำเข้า
metadata	object	ไม่	คู่คีย์-ค่าแบบกำหนดเอง (กฎเดียวกันกับการอัปโหลดปกติ)

ตัวอย่าง: นำเข้าไฟล์ CAR ด้วย curl

ขั้นตอนที่ 1: สร้างไฟล์ CAR จากไดเรกทอรีในเครื่องโดยใช้ ipfs-car:

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

ขั้นตอนที่ 2: อัปโหลดไฟล์ 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\"
  }"

ตัวอย่าง: นำเข้าไฟล์ CAR ด้วย 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);

ตัวอย่าง: นำเข้าไฟล์ CAR ด้วย 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"])

การตอบกลับ 200 OK

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

S3-Compatible API

ใช้ header x-amz-meta-import: car ในคำขอ PutObject เพื่อนำเข้าไฟล์ CAR ผ่าน 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" }   // ← เรียกใช้การนำเข้า CAR
}));

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

MCP Server

เครื่องมือ ipfs_import_car พร้อมใช้งานใน 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

จากไดเรกทอรี (แนะนำ)

ใช้เครื่องมือ CLI ipfs-car:

# ติดตั้ง
npm install -g ipfs-car

# แพ็คไดเรกทอรีเป็นไฟล์ CAR
ipfs-car pack ./my-directory -o my-archive.car

# ตรวจสอบ root CID ก่อนอัปโหลด
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

จากโหนด IPFS ที่กำลังทำงาน

ส่งออก CID ใดก็ได้เป็นไฟล์ CAR โดยใช้ Kubo CLI:

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

สร้างด้วยโปรแกรม JavaScript

ใช้ไลบรารี @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);

การตรวจสอบความสมบูรณ์ของ CID

ประโยชน์หลักของการนำเข้า CAR คือการรักษา CID คุณสามารถตรวจสอบว่า root CID ตรงกันก่อนและหลังการอัปโหลด:

# 1. แพ็คไดเรกทอรีและจดบันทึก root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. อัปโหลดไปยัง 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 ตรงกัน -- เนื้อหาถูกนำเข้าตรงตามที่สร้างไว้ในเครื่อง

การย้ายจากผู้ให้บริการรายอื่น

จาก Pinata

# ส่งออกจาก Pinata ผ่าน IPFS gateway
ipfs dag export QmYourCID > export.car

# นำเข้าสู่ 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}"

จาก Filebase

# Filebase รองรับการส่งออก CAR ผ่าน S3 API ของพวกเขา
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# นำเข้าสู่ 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}"

ข้อจำกัด

ข้อจำกัด	ค่า
ขนาดไฟล์ CAR สูงสุด	100 MB
รูทเดี่ยวสูงสุด	ต้องมีอย่างน้อยหนึ่ง root CID
รูปแบบ CAR	CARv1 (รองรับทั่วไป)
ความพร้อมใช้งาน	ทุกแผน (Dharma, Bodhi, Nirvana)

ข้อจำกัดด้านพื้นที่จัดเก็บและจำนวนไฟล์จากแผนของคุณมีผลบังคับใช้ DAG ที่นำเข้าจะนับเป็นหนึ่งรายการไฟล์ และขนาดไฟล์ CAR จะถูกหักจากโควตาพื้นที่จัดเก็บของคุณ

การแก้ไขปัญหา

"invalid CAR file: too small"

เนื้อหาที่อัปโหลดมีขนาดน้อยกว่า 40 ไบต์ ซึ่งเล็กเกินไปสำหรับไฟล์ CAR ที่ถูกต้อง ตรวจสอบให้แน่ใจว่าคุณส่งเนื้อหา CAR ที่เข้ารหัส base64 ทั้งหมด

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

ไฟล์ CAR ที่ถอดรหัสแล้วมีขนาดเกิน 100 MB แบ่งเนื้อหาของคุณเป็นไฟล์ CAR ขนาดเล็กหลายไฟล์โดยใช้แพ็กเกจ carbites หรืออัปโหลดไฟล์ทีละไฟล์

"dag/import did not return a root CID"

โหนด IPFS ไม่สามารถประมวลผลไฟล์ CAR ได้ ตรวจสอบว่าไฟล์เป็นไฟล์เก็บถาวร CARv1 ที่ถูกต้อง:

ipfs-car roots my-archive.car

หากคำสั่งนี้ล้มเหลว แสดงว่าไฟล์ CAR มีรูปแบบไม่ถูกต้อง สร้างใหม่ด้วย ipfs-car pack หรือ ipfs dag export

"not enough storage"

ถึงขีดจำกัดพื้นที่จัดเก็บของแผนของคุณแล้ว ลบไฟล์ที่ไม่ได้ใช้หรืออัปเกรดแผนของคุณที่ ipfs.ninja/pricing