CAR Import (DAG Import)

Εισαγάγετε ολόκληρα IPFS DAGs σε ένα μόνο αίτημα χρησιμοποιώντας αρχεία CAR (Content Addressable aRchive). Τα CIDs σας διατηρούνται ακριβώς — χωρίς εκ νέου τεμαχισμό ή εκ νέου κατακερματισμό.

Τι είναι ένα αρχείο CAR;

Ένα αρχείο CAR συσκευάζει ένα ολόκληρο δέντρο καταλόγων IPFS ή DAG σε ένα ενιαίο φορητό αρχείο. Κάθε block αποθηκεύεται με το αρχικό του CID, οπότε η υπηρεσία εισάγει τα πάντα ως έχουν. Αυτό σημαίνει:

• Διατήρηση CID — υπολογίστε τα CIDs τοπικά, επαληθεύστε ότι η υπηρεσία επιστρέφει ακριβώς το ίδιο CID
• Μαζική μεταφόρτωση — ανεβάστε εκατοντάδες αρχεία σε ένα αίτημα αντί για ένα-ένα
• Μετεγκατάσταση παρόχου — εξάγετε ένα DAG από άλλον πάροχο, εισαγάγετε στο IPFS Ninja με πανομοιότυπα CIDs
• Προσαρμοσμένα DAGs — ανεβάστε οποιαδήποτε δομή δεδομένων 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-συμβατό API

Χρησιμοποιήστε την κεφαλίδα 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";

// Δημιουργία blocks
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

// Εγγραφή CAR
const { writer, out } = CarWriter.create([cid1]);
writer.put({ cid: cid1, bytes: block1 });
writer.close();

// Συλλογή εξόδου
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"
# ✓ Τα CIDs ταιριάζουν — το περιεχόμενο εισήχθη ακριβώς όπως κατασκευάστηκε τοπικά

Μετεγκατάσταση από άλλον πάροχο

Από 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	Πρέπει να υπάρχει τουλάχιστον ένα root CID
Μορφή CAR	CARv1 (καθολικά υποστηριζόμενη)
Διαθεσιμότητα	Όλα τα πλάνα (Dharma, Bodhi, Nirvana)

Ισχύουν τα όρια αποθήκευσης και αριθμού αρχείων του πλάνου σας. Το εισαγόμενο DAG μετράει ως μία καταχώρηση αρχείου, και το μέγεθος του αρχείου CAR αφαιρείται από το αποθηκευτικό σας όριο.

Αντιμετώπιση προβλημάτων

"invalid CAR file: too small"

Το μεταφορτωμένο περιεχόμενο είναι λιγότερο από 40 bytes, που είναι πολύ μικρό για ένα έγκυρο αρχείο 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.