CAR Import (DAG Import)

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

อัปโหลดไฟล์ CAR ไปยัง IPFS Ninja

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

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

อัปโหลดผ่านแดชบอร์ด

การลากและวางสองเส้นทางบน /upload เข้าสู่โฟลว์การนำเข้าเดียวกันนี้ — ไม่ต้องเขียนโค้ด:

• วางไฟล์ .car โซนอัปโหลดจะตรวจจับนามสกุลอัตโนมัติ แสดงแบนเนอร์ "CAR archive detected" และปุ่มส่งจะกลายเป็น "Import <filename> as CAR" root CID ของไฟล์เก็บถาวรเองจะถูกรักษาไว้
• วางโฟลเดอร์ แดชบอร์ดจะแพ็กโฟลเดอร์เป็น UnixFS DAG ในเบราว์เซอร์ของคุณ (ใช้ ipfs-unixfs-importer พร้อม chunker 1 MiB รุ่นใหม่ตาม IPIP-0499) และอัปโหลด CAR ที่ได้ผ่านเส้นทางเดียวกัน root CID เป็นไดเรกทอรี bafybei… ที่แก้ไขได้ที่ /ipfs/{cid}/{subpath}

ทั้งสองใช้โฟลว์ presigned-PUT สำหรับไฟล์ที่ใหญ่กว่า 2-3 MB — ขีดจำกัดขนาดไฟล์คือ 5 GB ต่อ CAR

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

วิธีนับไฟล์ทำงานอย่างไร

แต่ละไฟล์ภายใน CAR จะนับเป็นรายการแยกกันต่อขีดจำกัดไฟล์ของแผนคุณ CAR ที่มี 12 ไฟล์จะใช้ 13 สล็อต (ไฟล์ย่อย 12 ไฟล์ + รายการ root CAR 1 รายการ) CAR ไฟล์เดียวจะนับเป็น 1 สล็อต

• พื้นที่จัดเก็บจะถูกเรียกเก็บ ครั้งเดียว บนรายการ root CAR (ขนาดไฟล์ CAR ทั้งหมด)
• ไฟล์ย่อยแต่ละไฟล์จะปรากฏในรายการไฟล์ของคุณพร้อม root CID ใน metadata (carParentCid) เพื่อให้คุณจัดกลุ่มได้
• สูงสุด 1000 ไฟล์ ต่อการนำเข้า CAR — DAG ที่ใหญ่กว่าต้องแบ่งเป็นหลายการนำเข้า

หากการนำเข้า CAR จะเกินจำนวนไฟล์ของแผนคุณ คำขอจะถูกปฏิเสธด้วยข้อผิดพลาด 402 และเนื้อหาจะถูกถอนปักหมุดโดยอัตโนมัติ:

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

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:

# 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

จากโหนด 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. 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"
# ✓ CIDs match — content imported exactly as built locally

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

จาก 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}"

จาก 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}"

ข้อจำกัด

ข้อจำกัด	ค่า
ขนาดไฟล์ 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