การปักหมุด

ปักหมุดเนื้อหา IPFS ที่มีอยู่ในบัญชีของคุณ เมื่อคุณปักหมุด CID คลัสเตอร์ของเราจะดึงเนื้อหาจากเครือข่าย IPFS และเก็บไว้อย่างถาวร

ปักหมุดด้วย CID

POST /pin

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
cid	string	ใช่	ตัวระบุเนื้อหา IPFS รับได้ทุกรูปแบบ: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… และ codec อื่น ๆ)
description	string	ไม่	คำอธิบายสั้นๆ สำหรับอ้างอิง
metadata	object	ไม่	คู่คีย์-ค่าที่กำหนดเองแนบกับการปักหมุด สูงสุด 10 คีย์ คีย์ต้องเป็นตัวอักษรและตัวเลขหรือขีดล่าง 1-64 ตัวอักษร ค่าต้องเป็นสตริง สูงสุด 256 ตัวอักษร ขนาด metadata รวมต้องไม่เกิน 4 KB
multiaddresses	string[]	ไม่	คำใบ้ swarm-connect ที่เป็นตัวเลือก สูงสุด 5 multiaddress ของ libp2p ของ peer ที่มีเนื้อหา CID นั้นอยู่ คลัสเตอร์ของเราจะรัน swarm connect กับแต่ละรายการแบบขนาน ก่อน การปักหมุด เพื่อให้เนื้อหาบน peer ส่วนตัว/ไม่อยู่บน DHT เข้าถึงได้โดยไม่ต้องรอการค้นพบผ่าน DHT ทำงานแบบ best-effort — การเชื่อมต่อที่ล้มเหลวจะไม่ทำให้การปักหมุดล้มเหลว ดู การปักหมุดจากโหนดส่วนตัว

ตัวอย่างคำขอ

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

สำหรับ DAG ขนาดใหญ่ (>500 บล็อกหรือ >50 MB) การตอบกลับจะรวมแฟล็ก 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 — ขั้นตอนการปักหมุดเริ่มต้นจะหาไม่พบ การส่ง multiaddresses หนึ่งรายการขึ้นไปจะบอกคลัสเตอร์ของเราให้รู้ตำแหน่งที่ต้องมองหาอย่างชัดเจน

เราจะรัน ipfs swarm connect <multiaddr> สำหรับแต่ละคำใบ้แบบขนาน ก่อน ที่การปักหมุดจะรัน หากการเชื่อมต่อสำเร็จ การดึง DAG ของการปักหมุดจะสามารถคุยกับ peer ของคุณได้โดยตรงแทนที่จะค้นหาผ่าน DHT หากล้มเหลว การปักหมุดจะยังคงดำเนินต่อไปกับเครือข่ายสาธารณะ (แบบ 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 ที่รองรับ

รองรับรูปแบบทั่วไป: transport /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; โปรโตคอล /tcp หรือ /udp; อัปเกรดที่เป็นตัวเลือก /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct multiaddress ต้อง ลงท้ายด้วย /p2p/<peerId> ขีดจำกัด: สูงสุด 5 คำใบ้ต่อการปักหมุด

การหา multiaddress ของโหนดคุณ

บน peer ที่คุณต้องการปักหมุด รัน ipfs id และคัดลอกรายการ Addresses รายการใดก็ได้ที่ลงท้ายด้วย /p2p/<PeerID> ควรใช้แอดเดรสที่เข้าถึงได้จากสาธารณะ (/ip4/YOUR_PUBLIC_IP/…) หรือแบบ DNS (/dnsaddr/your.domain/…) เพื่อให้คลัสเตอร์ของเราเข้าถึง peer ได้จาก AWS

การปักหมุดไดเรกทอรีขนาดใหญ่มาก

POST /pin ใช้สำหรับเนื้อหาที่มีอยู่บนเครือข่าย IPFS แล้ว — คลัสเตอร์จะดึง DAG ทีละบล็อกจาก peer ซึ่งอาจใช้เวลาหลายนาทีสำหรับไดเรกทอรีที่มี 1,000 ไฟล์ขึ้นไป ในช่วงที่กำลังดึงข้อมูล ไฟล์ย่อยบางไฟล์อาจยังไม่พร้อมใช้งานในเครื่องและคำขอ gateway ไปยังไฟล์เหล่านั้นอาจหมดเวลา เมื่อ status ของโฟลเดอร์หลักเปลี่ยนเป็น pinned ไฟล์ย่อยทุกไฟล์จะพร้อมใช้งานในเครื่องและเข้าถึงได้ผ่าน gateway ของคุณ

หากคุณมีไฟล์อยู่ในเครื่อง (แทนที่จะมีแค่ CID) ให้ใช้ การนำเข้า CAR สำหรับคอลเลกชัน NFT หรือชุดข้อมูลขนาดใหญ่ — เพราะจะอัปโหลด DAG ทั้งหมดไปยัง IPFS Ninja ในคำขอเดียวแบบ atomic จึงไม่มีช่วงเวลาดึงข้อมูลและไม่มีสถานะปักหมุดบางส่วน สร้าง CAR ด้วย:

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

จากนั้นนำเข้าผ่าน POST /upload/new พร้อม car: true

TIP

การปักหมุดเป็นแบบอะซิงโครนัส การตอบกลับจะส่งคืนทันทีพร้อมสถานะ pinning สอบถาม endpoint สถานะเพื่อตรวจสอบเมื่อการปักหมุดเสร็จสิ้น

ตรวจสอบสถานะการปักหมุด

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 สอบถามอีกครั้งในไม่กี่วินาที
pinned	เนื้อหาถูกปักหมุดและพร้อมใช้งานผ่านบัญชีและ gateway ของคุณ
failed	ไม่พบเนื้อหาในเครือข่าย IPFS CID อาจไม่ถูกต้องหรือเนื้อหาไม่มีแล้ว

วิธีการทำงานของการปักหมุด

1. คุณส่ง CID ผ่าน POST /pin
2. คลัสเตอร์ IPFS ของเราค้นหาเครือข่ายสำหรับโหนดที่มีเนื้อหา
3. คลัสเตอร์ดาวน์โหลดและปักหมุดเนื้อหาในเครื่อง
4. เมื่อปักหมุดแล้ว ไฟล์จะปรากฏในรายการไฟล์ของคุณและเข้าถึงได้ผ่าน gateway
5. การใช้พื้นที่จัดเก็บจะถูกบันทึกเมื่อการปักหมุดเสร็จสิ้น

WARNING

เวลาปักหมุดขึ้นอยู่กับขนาดไฟล์และความพร้อมของเครือข่าย ไฟล์ขนาดเล็กมักปักหมุดได้ในไม่กี่วินาที ไฟล์ขนาดใหญ่หรือเนื้อหาที่ถูกปักหมุดน้อยอาจใช้เวลาหลายนาที

พื้นที่จัดเก็บ

เนื้อหาที่ปักหมุดจะนับรวมในขีดจำกัดพื้นที่จัดเก็บของแผนคุณ ขนาดไฟล์จะถูกบันทึกเมื่อการปักหมุดเสร็จสิ้น หากคุณใกล้ถึงขีดจำกัดพื้นที่จัดเก็บ คุณสามารถเพิ่มพื้นที่ว่างได้โดยลบไฟล์ที่ไม่ได้ใช้หรืออัปเกรดเพื่อเพิ่มความจุ