ข้อมูลเมตา

metadata คือชุดคู่คีย์-ค่าของคุณเองบนออบเจ็กต์ เช่น ID ของรายการใน CRM ของคุณ ทีมที่รับผิดชอบ หรือรอบการซิงก์ที่เขียนออบเจ็กต์นั้น Sursa เก็บข้อมูลนี้ ส่งคืนพร้อมออบเจ็กต์และในอีเวนต์ และให้คุณกรองรายการการ์ด คอลเลกชัน และโฟลเดอร์ด้วยข้อมูลนี้ได้ โดยไม่ตีความข้อมูลนี้แต่อย่างใด

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "metadata": {"crm_id": "A-1042", "team": "support"}
}

ออบเจ็กต์ที่มี metadata ได้แก่ การ์ด คอลเลกชัน และโฟลเดอร์ เอกสารของ แหล่งข้อมูลแบบกำหนดเอง ก็มี metadata เช่นกัน และค่านี้จะกลายเป็น metadata ของการ์ดของเอกสารนั้น

ขีดจำกัด

คำขอที่เกินขีดจำกัดจะได้การตอบกลับ 400 พร้อมรหัส api.metadata_invalid โดย error.details.key ระบุคีย์ และ error.details.reason บอกว่าผิดพลาดอย่างไร: too_many_keys key_invalid value_too_long too_large หรือ value_invalid (ค่าไม่ใช่สตริง)

ค่าเป็นสตริง ให้เก็บตัวเลขและวันที่เป็นสตริงด้วย เช่น "2026-10-24"

การตั้งค่าข้อมูลเมตา

เมื่อสร้างหรือแทนที่ออบเจ็กต์ (POST และ PUT) ระบบจะตั้งค่า metadata ทั้งชุด:

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy",
    "body": "Refunds are processed within 14 days.",
    "metadata": {"crm_id": "A-1042", "team": "support"}
  }'

ในคำขอ multipart/form-data เช่น การอัปโหลดไฟล์ ให้ส่ง metadata เป็นฟิลด์ของฟอร์มที่มีค่าเป็นออบเจ็กต์ JSON: metadata={"crm_id":"A-1042"}

การอัปเดตข้อมูลเมตา

PATCH รวมคีย์ที่คุณส่งเข้ากับคีย์ที่มีอยู่ คีย์ที่มีค่า "" หรือ null จะถูกนำออก ส่วนคีย์ที่คุณไม่ได้ส่งจะคงเดิม:

curl -X PATCH https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": "billing", "legacy_flag": null}}'

{"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "metadata": {"crm_id": "A-1042", "team": "billing"}}

"metadata": {} ไม่เปลี่ยนแปลงอะไร หากต้องการนำคู่ทั้งหมดออก ให้ส่งแต่ละคีย์พร้อมค่า null

การกรองด้วยข้อมูลเมตา

รายการต่อไปนี้รับ metadata[<key>]=<value>:

• การ์ด: GET /v1/cards และ GET /v1/cards/count
• คอลเลกชัน: GET /v1/collections
• โฟลเดอร์: GET /v1/folders และ GET /v1/collections/{name}/folders

ตัวกรองนี้จับคู่ค่าแบบตรงทุกตัวอักษร คุณรวมเงื่อนไขได้ไม่เกิน 3 ข้อ และออบเจ็กต์ต้องตรงกับทุกเงื่อนไข:

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "metadata[team]=support" \
  --data-urlencode "metadata[crm_id]=A-1042"

เมื่อใช้ตัวกรอง ต้นไม้โฟลเดอร์จะมาเป็นรายการแบบแบน folders ของแต่ละคอลเลกชันมีโฟลเดอร์ที่ตรงเงื่อนไขพร้อม children ที่ว่างเปล่า และ parent_id บอกตำแหน่งของแต่ละโฟลเดอร์ ในกรณีนี้ GET /v1/folders จะไม่รวมคอลเลกชันที่ไม่มีโฟลเดอร์ที่ตรงเงื่อนไข เงื่อนไขที่มากกว่า 3 ข้อหรือคีย์ที่ไม่ถูกต้องจะได้การตอบกลับ 400 พร้อมรหัส api.metadata_invalid

สิ่งที่ข้อมูลเมตาไม่ใช่

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