CAR Import (DAG Import)

Mag-import ng buong IPFS DAG sa isang kahilingan gamit ang mga CAR (Content Addressable aRchive) na file. Ang iyong mga CID ay nananatiling eksakto -- walang muling paghahati o muling pag-hash.

Ano ang CAR file?

Ang CAR file ay nagpapackage ng buong IPFS directory tree o DAG sa isang portable na archive. Bawat block ay naka-store kasama ang orihinal nitong CID, kaya ini-import ng serbisyo ang lahat nang walang pagbabago. Ibig sabihin nito:

• Pagpapanatili ng CID -- kalkulahin ang mga CID nang lokal, i-verify na ibinabalik ng serbisyo ang eksaktong parehong CID
• Batch na pag-upload -- mag-upload ng daan-daang file sa isang kahilingan sa halip na isa-isa
• Paglipat ng provider -- i-export ang DAG mula sa ibang provider, i-import sa IPFS Ninja na may magkakaparehong CID
• Custom na mga DAG -- direktang mag-upload ng anumang IPLD na data structure

REST API

POST /upload/new

Parehong endpoint sa mga regular na upload -- magdagdag ng car: true para ipahiwatig ang CAR import.

Request body

Parameter	Uri	Kinakailangan	Paglalarawan
content	string	Oo	Base64-encoded na CAR file
car	boolean	Oo	Itakda sa true para paganahin ang CAR import
description	string	Hindi	Maikling paglalarawan ng import
folderId	string	Hindi	Folder ID para ayusin ang na-import na nilalaman
metadata	object	Hindi	Custom na key-value pairs (parehong mga patakaran sa regular na mga upload)

Halimbawa: Mag-import ng CAR file gamit ang curl

Hakbang 1: Gumawa ng CAR file mula sa lokal na direktoryo gamit ang ipfs-car:

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

Hakbang 2: I-upload ang CAR file:

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

Halimbawa: Mag-import ng CAR file gamit ang 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);

Halimbawa: Mag-import ng CAR file gamit ang 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"])

Tugon 200 OK

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

S3-Compatible API

Gamitin ang x-amz-meta-import: car header sa isang PutObject na kahilingan para mag-import ng CAR file sa pamamagitan ng 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" }   // ← nagti-trigger ng CAR import
}));

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

MCP Server

Ang tool na ipfs_import_car ay available sa 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...

Paggawa ng mga CAR File

Mula sa isang direktoryo (inirerekomenda)

Gamitin ang CLI tool na ipfs-car:

# I-install
npm install -g ipfs-car

# I-pack ang direktoryo sa isang CAR file
ipfs-car pack ./my-directory -o my-archive.car

# Suriin ang root CID bago mag-upload
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Mula sa isang tumatakbong IPFS node

I-export ang anumang CID bilang CAR file gamit ang Kubo CLI:

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

Sa pamamagitan ng programa gamit ang JavaScript

Gamitin ang library na @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);

Pag-verify ng Integridad ng CID

Ang pangunahing benepisyo ng CAR import ay ang pagpapanatili ng CID. Maaari mong i-verify na magkatugma ang root CID bago at pagkatapos ng pag-upload:

# 1. I-pack ang direktoryo at itala ang root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. I-upload sa 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"
# ✓ Magkatugma ang mga CID -- ang nilalaman ay na-import nang eksakto gaya ng pagkakagawa nito nang lokal

Paglipat Mula sa Ibang Provider

Mula sa Pinata

# I-export mula sa Pinata gamit ang IPFS gateway
ipfs dag export QmYourCID > export.car

# I-import sa 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}"

Mula sa Filebase

# Sinusuportahan ng Filebase ang CAR export sa pamamagitan ng kanilang S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# I-import sa 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}"

Mga Limitasyon

Limitasyon	Halaga
Maximum na laki ng CAR file	100 MB
Maximum na isang root	Dapat may kahit isang root CID
Format ng CAR	CARv1 (universally supported)
Availability	Lahat ng plano (Dharma, Bodhi, Nirvana)

Nalalapat ang mga limitasyon sa storage at bilang ng file mula sa iyong plano. Ang na-import na DAG ay binibilang bilang isang file entry, at ang laki ng CAR file ay ibinabawas mula sa iyong storage quota.

Pag-troubleshoot

"invalid CAR file: too small"

Ang na-upload na nilalaman ay mas mababa sa 40 bytes, na masyadong maliit para sa isang valid na CAR file. Siguraduhing ipinapadala mo ang buong base64-encoded na CAR na nilalaman.

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

Ang na-decode na CAR file ay lumampas sa 100 MB. Hatiin ang iyong nilalaman sa maraming mas maliliit na CAR file gamit ang package na carbites, o mag-upload ng mga file nang isa-isa.

"dag/import did not return a root CID"

Hindi naproseso ng IPFS node ang CAR file. I-verify na ang file ay isang valid na CARv1 archive:

ipfs-car roots my-archive.car

Kung nabigo ang command na ito, ang CAR file ay may mali ang format. Muling gawin ito gamit ang ipfs-car pack o ipfs dag export.

"not enough storage"

Naabot na ang limitasyon ng storage ng iyong plano. Magtanggal ng mga hindi ginagamit na file o mag-upgrade ng iyong plano sa ipfs.ninja/pricing.