CAR Import (DAG Import)

CAR (Content Addressable aRchive) 파일을 사용하여 단일 요청으로 전체 IPFS DAG를 가져옵니다. CID가 정확하게 보존됩니다 — 재청크 또는 재해싱이 없습니다.

CAR 파일이란?

CAR 파일은 전체 IPFS 디렉토리 트리 또는 DAG를 단일 포터블 아카이브로 패키징합니다. 각 블록은 원래 CID와 함께 저장되므로 서비스가 모든 것을 그대로 가져옵니다. 이는 다음을 의미합니다:

CID 보존 — CID를 로컬에서 계산하고 서비스가 정확히 동일한 CID를 반환하는지 확인
일괄 업로드 — 하나씩이 아닌 한 번의 요청으로 수백 개의 파일을 업로드
프로바이더 마이그레이션 — 다른 프로바이더에서 DAG를 내보내고 동일한 CID로 IPFS Ninja에 가져오기
커스텀 DAG — 모든 IPLD 데이터 구조를 직접 업로드

REST API

POST /upload/new

일반 업로드와 동일한 endpoint입니다 — CAR 가져오기를 나타내려면 car: true를 추가하세요.

요청 본문

매개변수	유형	필수	설명
`content`	string	예	Base64로 인코딩된 CAR 파일
`car`	boolean	예	CAR 가져오기를 활성화하려면 `true`로 설정
`description`	string	아니오	가져오기에 대한 간단한 설명
`folderId`	string	아니오	가져온 콘텐츠를 정리할 폴더 ID
`metadata`	object	아니오	사용자 정의 키-값 쌍 (일반 업로드와 동일한 규칙)

예제: curl로 CAR 파일 가져오기

1단계: ipfs-car를 사용하여 로컬 디렉토리에서 CAR 파일을 생성합니다:

bash

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

2단계: CAR 파일을 업로드합니다:

bash

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

예제: JavaScript로 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);

예제: Python으로 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`

json

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

S3-Compatible API

S3 API를 통해 CAR 파일을 가져오려면 PutObject 요청에 x-amz-meta-import: car 헤더를 사용합니다.

javascript

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 파일 생성

디렉토리에서 (권장)

ipfs-car CLI 도구를 사용합니다:

bash

# 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 노드에서

Kubo CLI를 사용하여 모든 CID를 CAR 파일로 내보냅니다:

bash

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

JavaScript로 프로그래밍 방식으로

@ipld/car 라이브러리를 사용합니다:

javascript

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 보존입니다. 업로드 전후로 루트 CID가 일치하는지 확인할 수 있습니다:

bash

# 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가 일치 — 콘텐츠가 로컬에서 구축한 것과 정확히 동일하게 가져왔습니다

다른 프로바이더에서 마이그레이션

Pinata에서

bash

# 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에서

bash

# 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
최대 단일 루트	최소 하나의 루트 CID가 필요
CAR 형식	CARv1 (보편적으로 지원)
이용 가능 플랜	모든 플랜 (Dharma, Bodhi, Nirvana)

플랜의 스토리지 및 파일 수 제한이 적용됩니다. 가져온 DAG는 하나의 파일 항목으로 계산되며, CAR 파일 크기는 스토리지 할당량에서 차감됩니다.

문제 해결

"invalid CAR file: too small"

업로드된 콘텐츠가 40바이트 미만으로, 유효한 CAR 파일이 되기에 너무 작습니다. 전체 Base64 인코딩된 CAR 콘텐츠를 전송하고 있는지 확인하세요.

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

디코딩된 CAR 파일이 100 MB를 초과합니다. carbites 패키지를 사용하여 콘텐츠를 여러 개의 작은 CAR 파일로 분할하거나, 파일을 개별적으로 업로드하세요.

"dag/import did not return a root CID"

IPFS 노드가 CAR 파일을 처리할 수 없습니다. 파일이 유효한 CARv1 아카이브인지 확인하세요:

bash

ipfs-car roots my-archive.car

이 명령이 실패하면 CAR 파일이 손상된 것입니다. ipfs-car pack 또는 ipfs dag export로 다시 생성하세요.

"not enough storage"

플랜의 스토리지 한도에 도달했습니다. 사용하지 않는 파일을 삭제하거나 ipfs.ninja/pricing에서 플랜을 업그레이드하세요.

CAR Import (DAG Import) ​

CAR 파일이란? ​

REST API ​

요청 본문 ​

예제: curl로 CAR 파일 가져오기 ​

예제: JavaScript로 CAR 파일 가져오기 ​

예제: Python으로 CAR 파일 가져오기 ​

응답 200 OK ​

S3-Compatible API ​

MCP Server ​

CAR 파일 생성 ​

디렉토리에서 (권장) ​

실행 중인 IPFS 노드에서 ​

JavaScript로 프로그래밍 방식으로 ​

CID 무결성 확인 ​

다른 프로바이더에서 마이그레이션 ​

Pinata에서 ​

Filebase에서 ​

제한 사항 ​

문제 해결 ​

"invalid CAR file: too small" ​

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

"dag/import did not return a root CID" ​

"not enough storage" ​

CAR Import (DAG Import)

CAR 파일이란?

REST API

요청 본문

예제: curl로 CAR 파일 가져오기

예제: JavaScript로 CAR 파일 가져오기

예제: Python으로 CAR 파일 가져오기

응답 `200 OK`

S3-Compatible API

MCP Server

CAR 파일 생성

디렉토리에서 (권장)

실행 중인 IPFS 노드에서

JavaScript로 프로그래밍 방식으로

CID 무결성 확인

다른 프로바이더에서 마이그레이션

Pinata에서

Filebase에서

제한 사항

문제 해결

"invalid CAR file: too small"

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

"dag/import did not return a root CID"

"not enough storage"