CAR Import (DAG Import)

Tuo kokonaisia IPFS DAG -rakenteita yhdellä pyynnöllä käyttäen CAR (Content Addressable aRchive) -tiedostoja. CID-tunnisteesi säilyvät täsmälleen — uudelleenpilkontaa tai uudelleentiivistystä ei tapahdu.

Lataa CAR-tiedosto IPFS Ninjaan

CAR-tiedosto paketoi koko IPFS-hakemistopuun tai DAG-rakenteen yhdeksi siirrettäväksi arkistoksi. Jokainen lohko tallennetaan alkuperäisellä CID-tunnisteellaan, joten palvelu tuo kaiken sellaisenaan. Tämä tarkoittaa:

• CID-säilyvyys — laske CID-tunnisteet paikallisesti ja varmista, että palvelu palauttaa täsmälleen saman CID-tunnisteen
• Erätuonti — lataa satoja tiedostoja yhdellä pyynnöllä yhden kerrallaan lataamisen sijaan
• Palveluntarjoajan vaihto — vie DAG toiselta palveluntarjoajalta ja tuo IPFS Ninjaan identtisillä CID-tunnisteilla
• Mukautetut DAG-rakenteet — lataa mikä tahansa IPLD-tietorakenne suoraan

Lataus hallintapaneelin kautta

Kaksi vedä ja pudota -polkua sivulla /upload osuvat samaan tuontivirtaan — ei koodia tarvita:

• Pudota .car-tiedosto. Latausalue tunnistaa tiedostopäätteen automaattisesti, näyttää "CAR archive detected" -bannerin, ja lähetyspainikkeesta tulee "Import <filename> as CAR". Arkiston oma juuri-CID säilytetään.
• Pudota kansio. Hallintapaneeli pakkaa kansion UnixFS DAG:ksi selaimessasi (käyttäen ipfs-unixfs-importer-kirjastoa nykyaikaisella 1 MiB:n lohkottimella IPIP-0499 mukaisesti) ja lataa syntyneen CAR:n saman polun kautta. Juuri-CID on bafybei…-hakemisto, joka ratkeaa osoitteessa /ipfs/{cid}/{subpath}.

Molemmat käyttävät esiallekirjoitetun PUT:n virtaa kaikelle muutaman megatavun ylittävälle sisällölle — tiedostokoon yläraja on 5 Gt per CAR.

REST API

POST /upload/new

Sama päätepiste kuin tavallisissa latauksissa — lisää car: true osoittamaan CAR-tuontia.

Pyyntörunko

Parametri	Tyyppi	Pakollinen	Kuvaus
content	string	Kyllä	Base64-koodattu CAR-tiedosto
car	boolean	Kyllä	Aseta arvoon true CAR-tuonnin käyttämiseksi
description	string	Ei	Lyhyt kuvaus tuonnista
folderId	string	Ei	Kansion tunnus tuodun sisällön järjestämiseksi
metadata	object	Ei	Mukautetut avain-arvo-parit (samat säännöt kuin tavallisissa latauksissa)

Esimerkki: CAR-tiedoston tuonti curl-komennolla

Vaihe 1: Luo CAR-tiedosto paikallisesta hakemistosta ipfs-car-työkalulla:

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

Vaihe 2: Lataa CAR-tiedosto:

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

Esimerkki: CAR-tiedoston tuonti JavaScriptillä

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);

Esimerkki: CAR-tiedoston tuonti Pythonilla

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"])

Vastaus 200 OK

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

Miten tiedostojen laskenta toimii

Jokainen CAR:n sisällä oleva tiedosto lasketaan yksitellen suunnitelmasi tiedostorajaan. 12 tiedostoa sisältävä CAR käyttää 13 paikkaa (12 lasta + 1 juuren CAR-merkintä). Yhden tiedoston CAR lasketaan 1 paikkana.

• Tallennustila veloitetaan kerran juuren CAR-merkinnästä (koko CAR-tiedoston koko)
• Yksittäiset lapsitiedostot näkyvät tiedostolistassasi juuri-CID:n kanssa metatiedoissaan (carParentCid), jotta voit ryhmitellä ne
• Enintään 1000 tiedostoa per CAR-tuonti — suuremmat DAG:t on jaettava useiden tuontien kesken

Jos CAR:n tuonti ylittäisi suunnitelmasi tiedostorajan, pyyntö hylätään 402-virheellä ja sisällön kiinnitys poistetaan automaattisesti:

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

S3-yhteensopiva API

Käytä x-amz-meta-import: car -otsikkoa PutObject-pyynnössä tuodaksesi CAR-tiedoston S3 API:n kautta.

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" }   // ← käynnistää CAR-tuonnin
}));

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

MCP Server

ipfs_import_car-työkalu on saatavilla MCP Server -palvelimessa (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-tiedostojen luominen

Hakemistosta (suositeltu)

Käytä ipfs-car CLI-työkalua:

# 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

Käynnissä olevasta IPFS-solmusta

Vie mikä tahansa CID CAR-tiedostona Kubo CLI:n avulla:

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

Ohjelmallisesti JavaScriptillä

Käytä @ipld/car -kirjastoa:

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-eheyden varmistaminen

CAR-tuonnin keskeinen etu on CID-säilyvyys. Voit varmistaa, että juuri-CID täsmää ennen ja jälkeen latauksen:

# 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

Siirtyminen toiselta palveluntarjoajalta

Pinatasta

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

Filebasesta

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

Rajoitukset

Rajoitus	Arvo
CAR-tiedoston enimmäiskoko	100 MB
Yksittäinen juuri	Vähintään yksi juuri-CID vaaditaan
CAR-muoto	CARv1 (yleisesti tuettu)
Saatavuus	Kaikki suunnitelmat (Dharma, Bodhi, Nirvana)

Suunnitelmasi tallennustila- ja tiedostomäärärajoitukset ovat voimassa. Tuotu DAG lasketaan yhdeksi tiedostomerkinnäksi, ja CAR-tiedoston koko vähennetään tallennuskiintiöstäsi.

Vianmääritys

"invalid CAR file: too small"

Ladattu sisältö on alle 40 tavua, mikä on liian pieni kelvolliseksi CAR-tiedostoksi. Varmista, että lähetät täydellisen base64-koodatun CAR-sisällön.

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

Purettu CAR-tiedosto ylittää 100 MB. Jaa sisältösi useisiin pienempiin CAR-tiedostoihin carbites-paketin avulla tai lataa tiedostot yksitellen.

"dag/import did not return a root CID"

IPFS-solmu ei pystynyt käsittelemään CAR-tiedostoa. Varmista, että tiedosto on kelvollinen CARv1-arkisto:

ipfs-car roots my-archive.car

Jos tämä komento epäonnistuu, CAR-tiedosto on virheellinen. Luo se uudelleen komennolla ipfs-car pack tai ipfs dag export.

"not enough storage"

Suunnitelmasi tallennustilaraja on saavutettu. Poista käyttämättömät tiedostot tai päivitä suunnitelmasi osoitteessa ipfs.ninja/pricing.