CAR Import (DAG Import)

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

Ανεβάστε ένα αρχείο CAR στο IPFS Ninja

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

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

Μεταφόρτωση μέσω Dashboard

Δύο διαδρομές drag-and-drop στο /upload οδηγούν στην ίδια ροή εισαγωγής — χωρίς να απαιτείται κώδικας:

• Ρίξτε ένα αρχείο .car. Η ζώνη μεταφόρτωσης εντοπίζει αυτόματα την επέκταση, εμφανίζει ένα banner "CAR archive detected" και το κουμπί υποβολής γίνεται "Import <filename> as CAR". Το ίδιο το root CID του αρχείου διατηρείται.
• Ρίξτε έναν φάκελο. Το dashboard συσκευάζει τον φάκελο σε ένα UnixFS DAG μέσα στον browser σας (χρησιμοποιώντας το ipfs-unixfs-importer με τον σύγχρονο chunker του 1 MiB σύμφωνα με το IPIP-0499) και μεταφορτώνει το προκύπτον CAR μέσω της ίδιας διαδρομής. Το root CID είναι ένας κατάλογος bafybei… που επιλύεται στο /ipfs/{cid}/{subpath}.

Και οι δύο χρησιμοποιούν τη ροή presigned-PUT για οτιδήποτε ξεπερνά μερικά 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 παιδιά + 1 καταχώρηση root CAR). Ένα CAR με ένα μόνο αρχείο μετράει ως 1 θέση.

• Ο αποθηκευτικός χώρος χρεώνεται μία φορά στην καταχώρηση root CAR (το πλήρες μέγεθος του αρχείου CAR)
• Τα επιμέρους αρχεία-παιδιά εμφανίζονται στη λίστα αρχείων σας με το root CID στα metadata τους (carParentCid) ώστε να μπορείτε να τα ομαδοποιήσετε
• Μέγιστο 1000 αρχεία ανά εισαγωγή CAR — μεγαλύτερα DAGs πρέπει να χωριστούν σε πολλαπλές εισαγωγές

Εάν η εισαγωγή του CAR θα ξεπερνούσε το όριο αρχείων του πλάνου σας, το αίτημα απορρίπτεται με σφάλμα 402 και το περιεχόμενο ξε-καρφιτσώνεται αυτόματα:

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

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" }   // ← triggers CAR import
}));

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	Πρέπει να υπάρχει τουλάχιστον ένα 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.