ID ของออบเจ็กต์

ทุกออบเจ็กต์ของ API มี id ให้เก็บค่านี้ไว้ในระบบของคุณเมื่อต้องกลับมาใช้ออบเจ็กต์นั้นอีก ชื่อและหัวเรื่องเปลี่ยนได้ แต่ ID ไม่เปลี่ยนเลย

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

ออบเจ็กต์ประเภทใหม่ที่คุณน่าจะอ้างถึงจากระบบของคุณเองจะได้ ID แบบสตริงที่มีคำนำหน้าสั้นระบุประเภท ตามด้วยอักขระฐานสิบหก 32 ตัว

การอ้างอิงระหว่างออบเจ็กต์

ออบเจ็กต์อ้างถึงกันด้วย ID ในฟิลด์ชื่อ <object>_id เช่น collection_id owner_id และ folder_id หากต้องการออบเจ็กต์ที่เกี่ยวข้องในการตอบกลับเดียวกัน ให้ใช้ expand[]

พารามิเตอร์พาธที่รับ ID ก็ตั้งชื่อแบบเดียวกัน: {card_id} {webhook_id} และ {upload_id}

คอลเลกชันตาม ID

คอลเลกชันมีทั้ง id และ name ที่ไม่ซ้ำกัน เช่น support พาธที่มีมาก่อนที่จะแนะนำให้ใช้ ID จะรับชื่อของคอลเลกชัน:

GET /v1/collections/support/stats

พาธเดียวกันนี้รับ ID ได้ด้วย โดยเขียนเป็น id:<number>:

curl https://api.sursa.com/v1/collections/id:3/stats \
  -H "Authorization: Bearer $SURSA_API_KEY"

ในโค้ดใหม่ให้ใช้รูปแบบ id: ผู้ดูแลระบบเปลี่ยนชื่อคอลเลกชันได้ แต่ ID ยังคงเดิม ส่วนของพาธที่มีแต่ตัวเลข เช่น /v1/collections/3 ยังคงหมายถึงคอลเลกชันที่ ชื่อ 3 ชื่อคอลเลกชันมี : ไม่ได้ ทั้งสองรูปแบบจึงไม่มีทางสับสนกัน

ในเนื้อหาคำขอและพารามิเตอร์คิวรี collection_id ใช้ควบคู่กับ collection แบบเดิม (ชื่อ) หากส่งทั้งคู่ ระบบจะใช้ collection_id ส่วน collection_id ที่ไม่มีอยู่ในองค์กร หรือที่คีย์ไม่มีสิทธิ์มองเห็น จะได้การตอบกลับ 404 พร้อมรหัส collections.not_found

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "collection_id=3"

ID ของคุณเอง

การ์ดเก็บ ID ของรายการต้นทางในระบบของคุณไว้ใน external_id ได้ ยาวไม่เกิน 512 อักขระ และไม่ซ้ำกันในการ์ดขององค์กร เมื่อมีค่านี้ คุณก็ไม่ต้องเก็บ ID ของการ์ดใน Sursa เลย:

เข้ารหัส URL ของ external_id เมื่อเป็นส่วนหนึ่งของพาธ: crm/A-1042 จะกลายเป็น crm%2FA-1042

เอกสารของ แหล่งข้อมูลแบบกำหนดเอง มี external_id ของตัวเองภายในแหล่งข้อมูลนั้น ทั้งสองแบบจึงไม่ชนกัน การ์ดของแหล่งข้อมูลแบบกำหนดเองเปลี่ยนแปลงได้ด้วยการส่งเอกสารไปยังแหล่งข้อมูลนั้นอีกครั้ง ไม่ใช่ด้วย PUT /v1/cards-by-external-id/… ซึ่งในกรณีนี้จะตอบกลับ 409 พร้อมรหัส cards.managed_by_source