Καρφίτσωμα

Καρφιτσώστε υπάρχον περιεχόμενο IPFS στον λογαριασμό σας. Όταν καρφιτσώνετε ένα CID, το cluster μας ανακτά το περιεχόμενο από το δίκτυο IPFS και το κρατά μόνιμα διαθέσιμο.

Καρφίτσωμα με CID

POST /pin

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
cid	string	Ναι	Αναγνωριστικό περιεχομένου IPFS. Γίνεται δεκτή οποιαδήποτε μορφή: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy…, και άλλοι codecs).
description	string	Όχι	Σύντομη περιγραφή για δική σας αναφορά.
metadata	object	Όχι	Προσαρμοσμένα ζεύγη κλειδιού-τιμής που επισυνάπτονται στο pin. Μέγιστο 10 κλειδιά. Τα κλειδιά πρέπει να είναι αλφαριθμητικά ή underscore, 1-64 χαρακτήρων. Οι τιμές πρέπει να είναι strings, έως 256 χαρακτήρες η καθεμία. Το συνολικό μέγεθος των metadata δεν πρέπει να υπερβαίνει τα 4 KB.
multiaddresses	string[]	Όχι	Προαιρετικές υποδείξεις swarm-connect. Έως 5 multiaddresses libp2p peers που φιλοξενούν το CID. Το cluster μας εκτελεί swarm connect σε καθένα από αυτά παράλληλα πριν το pin, ώστε περιεχόμενο σε ιδιωτικούς / μη-DHT peers να είναι προσβάσιμο χωρίς αναμονή για ανακάλυψη μέσω DHT. Best-effort — μια αποτυχημένη σύνδεση δεν αποτυγχάνει το pin. Δείτε Καρφίτσωμα από ιδιωτικό κόμβο.

Παράδειγμα αιτήματος

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Απάντηση 202 Accepted

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "description": "NFT metadata",
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Για μεγάλα DAGs (>500 blocks ή >50 MB), η απάντηση περιλαμβάνει ένα flag async: true:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "async": true,
  "note": "Large DAG detected — pin running in background. Check status via GET /pin/bafybei…",
  "uris": { ... }
}

Καρφίτσωμα από ιδιωτικό κόμβο

Αν το CID που θέλετε να καρφιτσώσετε βρίσκεται σε έναν peer που δεν συμμετέχει στο δημόσιο DHT — έναν ιδιωτικό κόμβο staging, μια αυτοφιλοξενούμενη μηχανή σε VPN, ή έναν σταθμό εργασίας πίσω από NAT — η προεπιλεγμένη ροή pin δεν θα τον εντοπίσει. Περνώντας ένα ή περισσότερα multiaddresses λέτε στο cluster μας ακριβώς πού να ψάξει.

Εκτελούμε ipfs swarm connect <multiaddr> για κάθε υπόδειξη παράλληλα πριν τρέξει το pin. Αν η σύνδεση πετύχει, η ανάκτηση του DAG για το pin μπορεί να επικοινωνήσει απευθείας με τον peer σας αντί να ψάχνει μέσω του DHT. Αν αποτύχει, το pin συνεχίζει κανονικά έναντι του δημόσιου δικτύου (σημασιολογία best-effort).

Παράδειγμα: καρφίτσωμα από συγκεκριμένο peer

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

Η απάντηση περιλαμβάνει κατάσταση ανά υπόδειξη

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "swarmConnected": [
    { "multiaddr": "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooW…", "ok": true,  "strings": ["connect 12D3KooW… success"] },
    { "multiaddr": "/dns4/node.internal.example/tcp/443/…",   "ok": false, "error": "dial to peer: no route" }
  ],
  "uris": { … }
}

Αποδεκτές μορφές multiaddress

Υποστηρίζονται οι συνήθεις μορφές: μεταφορές /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr· πρωτόκολλα /tcp ή /udp· προαιρετικές αναβαθμίσεις /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Το multiaddress πρέπει να καταλήγει σε /p2p/<peerId>. Όριο: έως 5 υποδείξεις ανά pin.

Λήψη του multiaddress του κόμβου σας

Στον peer από τον οποίο θέλετε να καρφιτσώσετε, εκτελέστε ipfs id και αντιγράψτε οποιαδήποτε από τις καταχωρίσεις Addresses που καταλήγει σε /p2p/<PeerID>. Προτιμήστε δημόσια δρομολογήσιμες διευθύνσεις (/ip4/YOUR_PUBLIC_IP/…) ή διευθύνσεις βασισμένες σε DNS (/dnsaddr/your.domain/…) ώστε το cluster μας να μπορεί να προσεγγίσει τον peer από το AWS.

Καρφίτσωμα πολύ μεγάλων καταλόγων

Το POST /pin προορίζεται για περιεχόμενο που ήδη βρίσκεται στο δίκτυο IPFS — το cluster ανακτά το DAG block-by-block από peers, κάτι που μπορεί να διαρκέσει αρκετά λεπτά για καταλόγους με 1.000+ αρχεία. Κατά τη διάρκεια αυτού του παραθύρου ανάκτησης, ορισμένα θυγατρικά αρχεία ενδέχεται να μην είναι ακόμη διαθέσιμα τοπικά και τα αιτήματα gateway προς αυτά μπορεί να λήξουν (timeout). Μόλις η status του γονικού στοιχείου γίνει pinned, κάθε θυγατρικό στοιχείο είναι διαθέσιμο τοπικά και προσβάσιμο μέσω του gateway σας.

Αν έχετε τα αρχεία τοπικά (αντί για απλώς ένα CID), προτιμήστε το εισαγωγή CAR για μεγάλες συλλογές NFT ή σύνολα δεδομένων — ανεβάζει ολόκληρο το DAG στο IPFS Ninja σε ένα ατομικό αίτημα, οπότε δεν υπάρχει παράθυρο ανάκτησης ούτε κατάσταση μερικού pin. Δημιουργήστε ένα CAR με:

npx ipfs-car pack ./my-collection -o collection.car

Στη συνέχεια εισάγετέ το μέσω POST /upload/new με car: true.

TIP

Το καρφίτσωμα είναι ασύγχρονο. Η απάντηση επιστρέφει αμέσως με κατάσταση pinning. Κάντε poll στο endpoint κατάστασης για να δείτε πότε ολοκληρώνεται το καρφίτσωμα.

Έλεγχος Κατάστασης Pin

GET /pin/:cid

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
cid	string	Ναι	Το CID που ελέγχετε.

Απάντηση 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Τιμές κατάστασης

Κατάσταση	Σημασία
pinning	Το περιεχόμενο ανακτάται από το δίκτυο IPFS. Κάντε poll ξανά σε λίγα δευτερόλεπτα.
pinned	Το περιεχόμενο είναι καρφιτσωμένο και διαθέσιμο μέσω του λογαριασμού και του gateway σας.
failed	Το περιεχόμενο δεν βρέθηκε στο δίκτυο IPFS. Το CID μπορεί να μην είναι έγκυρο ή το περιεχόμενο να μην είναι πλέον διαθέσιμο.

Πώς λειτουργεί το καρφίτσωμα

1. Υποβάλλετε ένα CID μέσω POST /pin
2. Το cluster IPFS μας αναζητά στο δίκτυο κόμβους που διαθέτουν το περιεχόμενο
3. Το cluster κατεβάζει και καρφιτσώνει το περιεχόμενο τοπικά
4. Μόλις καρφιτσωθεί, το αρχείο εμφανίζεται στη λίστα αρχείων σας και είναι προσβάσιμο μέσω του gateway
5. Η χρήση αποθηκευτικού χώρου καταγράφεται όταν ολοκληρωθεί το καρφίτσωμα

WARNING

Ο χρόνος καρφιτσώματος εξαρτάται από το μέγεθος του αρχείου και τη διαθεσιμότητα του δικτύου. Τα μικρά αρχεία συνήθως καρφιτσώνονται σε δευτερόλεπτα. Μεγάλα αρχεία ή σπάνια καρφιτσωμένο περιεχόμενο μπορεί να χρειαστούν λεπτά.

Αποθηκευτικός χώρος

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