ข้ามไปยังเนื้อหา
Sursa Developers

เริ่มต้นอย่างรวดเร็ว

คู่มือนี้พาคุณจากศูนย์ไปจนมีระบบที่เชื่อมต่อซึ่งใช้งานได้ภายใน 5 นาที คุณจะสร้างคีย์ API ตรวจสอบคีย์ เพิ่มเอกสารลงในฐานความรู้ ค้นหาเอกสารนั้น และถามคำถามเกี่ยวกับเอกสารนั้น ทุกขั้นตอนคือคำขอ HTTP หนึ่งคำขอ เลือกภาษาครั้งเดียวในตัวอย่างใดก็ได้ แล้วทุกตัวอย่างในหน้านี้จะเปลี่ยนตาม

ตัวอย่างที่มีตัวเลือกภาษาใช้ที่อยู่ API ของพอร์ทัลนี้ คือ https://api.sursa.com ในคลาวด์ของ Sursa หรือที่อยู่ API ของระบบที่ติดตั้งเอง ในตัวอย่างที่แสดง https://api.example.com ให้ใส่ที่อยู่ API ของคุณแทน หากไม่แน่ใจว่าคุณใช้ที่อยู่ใด ดู ที่อยู่ API เฉพาะและสภาพแวดล้อม

1. สร้างคีย์ API

ผู้ดูแลระบบขององค์กรสร้างคีย์ใน Sursa ได้ที่ Administration → API keys (การดูแลระบบ → คีย์ API) ตั้งชื่อคีย์ให้บอกว่าใช้ที่ใด (เช่น “CRM sync”) เลือกบทบาท และเลือกขอบเขตสิทธิ์หากต้องการจำกัดให้แคบลงอีก คีย์ทำได้เท่าที่ผู้ใช้ที่มีบทบาทนั้นทำได้ และไม่เกินกว่าที่ขอบเขตสิทธิ์อนุญาต สำหรับคู่มือนี้ บทบาท editor ก็เพียงพอ

คีย์แสดงเพียงครั้งเดียว ให้เก็บไว้ในที่เก็บข้อมูลลับของระบบของคุณ และส่งให้โค้ดผ่านตัวแปรสภาพแวดล้อม:

export SURSA_API_KEY="kb_…"

ทุกคำขอส่งคีย์ในเฮดเดอร์ Authorization เป็นโทเค็น Bearer คีย์ API และขอบเขตสิทธิ์ อธิบายเรื่องบทบาท ขอบเขตสิทธิ์ การหมดอายุ และการหมุนเวียน

2. ตั้งค่าไคลเอ็นต์

ไม่จำเป็นต้องใช้ไลบรารี API เป็นเพียง HTTPS และ JSON ธรรมดา ตัวอย่างในคู่มือนี้ใช้ฟังก์ชันช่วยขนาดเล็กในแต่ละภาษา คัดลอกฟังก์ชันของภาษาที่คุณใช้ไปได้เลย คู่มือถัดไปก็ใช้ฟังก์ชันช่วยเดียวกันนี้ ไลบรารีไคลเอ็นต์อย่างเป็นทางการมีรายการอยู่ที่ SDK

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. ตรวจสอบคีย์

GET /v1/me อธิบายผู้เรียก ได้แก่ องค์กร คีย์ บทบาทและขอบเขตสิทธิ์ของคีย์ และขีดจำกัดอัตราการเรียกที่ใช้กับคีย์นั้น เอนด์พอยต์นี้ใช้ได้กับทุกคีย์ที่ใช้งานได้ จึงเป็นคำขอแรกที่ดีที่สุดของทุกระบบที่เชื่อมต่อ

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

401 ที่มีรหัส auth.not_authenticated หมายความว่าไม่มีคีย์ คีย์ถูกเพิกถอน หรือพิมพ์คีย์ผิด ส่วน api_keys.expired หมายความว่าคีย์หมดอายุแล้ว

4. ค้นหาคอลเลกชัน

การ์ดอยู่ในคอลเลกชัน GET /v1/collections แสดงรายการคอลเลกชันที่คีย์ของคุณมองเห็น:

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

จด id และ name ของคอลเลกชันที่คุณต้องการใช้ไว้ ตัวอย่างด้านล่างใช้คอลเลกชัน 3 ซึ่งชื่อ support

5. เพิ่มเอกสาร

PUT /v1/cards-by-external-id/{external_id} สร้างการ์ดภายใต้ ID ของคุณเอง หรือแทนที่การ์ดหากมีอยู่แล้ว การรันคำขอนี้สองครั้งปลอดภัย ในครั้งที่สองเนื้อหาไม่ได้เปลี่ยน และคำตอบจะเป็น skipped พร้อมเหตุผล unchanged ให้ใช้ ID ของรายการในระบบของคุณเป็น external_id

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 '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

คำขอจะตอบกลับเมื่อการ์ดพร้อมให้ค้นพบแล้ว: 201 พร้อม "status": "ready" สำหรับการ์ดใหม่ และ 200 สำหรับการ์ดที่ถูกแทนที่ HTML และข้อความธรรมดาใช้งานแบบเดียวกันด้วย "content_type": "html" หรือ "text" ไฟล์ (PDF Word Excel และรูปแบบอื่น) ส่งผ่านเอนด์พอยต์เดียวกันในรูป multipart/form-data คู่มือ นำเข้าเอกสาร อธิบายเรื่องไฟล์ โฟลเดอร์ ข้อมูลเมตา และการนำเข้าเอกสารจำนวนมาก

POST /v1/search ค้นหาข้อความที่ตัดมาจากการ์ดซึ่งตรงกับคำค้น โดยเรียงรายการที่ตรงที่สุดไว้ก่อน:

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collection รับชื่อของคอลเลกชัน หากไม่ระบุ การค้นหาจะครอบคลุมคอลเลกชันที่ชื่อ default

7. ถามคำถาม

POST /v1/ask ตอบคำถามที่ถามด้วยภาษาธรรมดาและส่งคืนแหล่งที่มาของคำตอบ ผู้ช่วยค้นหาความรู้ที่เกี่ยวข้องและตอบจากการ์ดที่คีย์มีสิทธิ์อ่านเท่านั้น

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

เมื่อไม่พบสิ่งที่เกี่ยวข้อง การตอบกลับยังคงเป็น 200 พร้อม "empty": "no_hits" และคำอธิบายสั้นใน answer โค้ดของคุณเป็นผู้ตัดสินว่าจะแสดงอะไรให้ผู้ใช้เห็นในกรณีนี้

ขั้นตอนถัดไป