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

POST/v1/sources

สร้างแหล่งข้อมูล

create_source

เมื่อใช้คีย์ API ขององค์กร (ตั้งแต่ 1.62.0) จะใช้ได้เฉพาะแหล่งข้อมูลแบบกำหนดเอง (kind: custom): คีย์ต้องมีบทบาท admin และขอบเขตสิทธิ์ admin ชนิดอื่นจะส่งคืน 400 sources.kind_not_allowed_for_key คอนเนกเตอร์ที่ลงชื่อเข้าใช้กับผู้ให้บริการต้องตั้งค่าในเบราว์เซอร์ ฟิลด์ของคอนเนกเตอร์ไม่แสดงในข้อกำหนดสาธารณะ แหล่งข้อมูลแบบกำหนดเองรับ name คอลเลกชัน (collection_id หรือ collection) โหมดสิทธิ์ permissions_mode โฟลเดอร์ของคอลเลกชันสำหรับการ์ด (folder_id และ folder_mode) และโฟลเดอร์เอกสารที่เลือก (roots) ส่งเอกสารด้วยการดำเนินการ /v1/push/sources/{source_id}/*

การยืนยันตัวตน

ส่งคีย์ API ในเฮดเดอร์ Authorization: Authorization: Bearer <คีย์>

พารามิเตอร์เฮดเดอร์

  • X-View-Asstring

    สำหรับคีย์ API ที่มีบทบาท admin เท่านั้น ทำคำขอในนามโปรไฟล์ข้อมูล <profile>[:viewer|verifier|editor] เช่น employee:viewer คีย์การติดตั้งใช้เฮดเดอร์นี้ไม่ได้ (403)

  • Idempotency-Keystring

    คีย์ป้องกันการทำซ้ำ (idempotency key) สำหรับลองคำขอเขียนข้อมูลใหม่อย่างปลอดภัย: อักขระ ASCII ที่พิมพ์ได้ 1 ถึง 255 ตัว แนะนำให้ใช้ UUID v4 หนึ่งค่าต่อการดำเนินการเชิงตรรกะหนึ่งรายการ การลองใหม่ด้วยคีย์เดิมภายใน 24 ชั่วโมงจะไม่ทำการดำเนินการซ้ำ แต่ส่งคืนการตอบกลับที่บันทึกไว้ (สถานะ เฮดเดอร์ และเนื้อหา) พร้อมเฮดเดอร์ Idempotency-Replayed: true คีย์เดิมที่ใช้กับเมธอด พาธ Content-Type หรือเนื้อหาที่ต่างออกไปจะส่งคืน 409 api.idempotency_mismatch ส่วนระหว่างที่คำขอแรกยังทำงานอยู่จะส่งคืน 409 api.idempotency_in_progress พร้อม Retry-After: 1 หลังการตอบกลับ 5xx หรือ 429 Sursa จะปล่อยคีย์ และการลองใหม่จะทำการดำเนินการอีกครั้ง คีย์มีขอบเขตตามองค์กรและผู้เรียก (คีย์ API ผู้ใช้ หรือคีย์แหล่งข้อมูล)

    length ≥ 1, length ≤ 255

พารามิเตอร์คุกกี้

  • kb_view_asstring

    คุกกี้ของโหมด “View as” สำหรับเซสชัน POST /auth/view-as ตั้งค่าคุกกี้นี้ และ DELETE /auth/view-as ล้างค่า

เนื้อหาคำขอ

application/json

ออบเจ็กต์: SourceCreate

  • kindstring

    ประเภทของแหล่งข้อมูล (ดู SourceKind) เมื่อใช้คีย์ API ขององค์กร ใช้ได้เฉพาะ custom

    ค่าเริ่มต้น: "gdrive"

  • namestringจำเป็น

    length ≥ 1, length ≤ 120

  • collectionstring

    ชื่อคอลเลกชันของแหล่งข้อมูล ส่ง collection_id แทนได้ (ตั้งแต่เวอร์ชัน 1.62.0)

    length ≥ 1, length ≤ 64

  • collection_idinteger

    คอลเลกชันของแหล่งข้อมูลตาม ID (ตั้งแต่เวอร์ชัน 1.62.0) ถ้าส่งมาทั้งสองฟิลด์ ระบบใช้ collection_id

  • permissions_modestring

    โหมดสิทธิ์ของการ์ดจากแหล่งข้อมูล (ตั้งแต่เวอร์ชัน 1.62.0 เหมือนใน update_source_settings): own ใช้สิทธิ์ของคอลเลกชัน ส่วน mirror นำสิทธิ์มาจากเอกสาร (permissions) การเลือก mirror ต้องมีสิทธิ์จัดการสิทธิ์ของคอลเลกชัน

    ค่าที่ใช้ได้: ownmirror

  • default_owner_idinteger | null
  • verify_interval_daysinteger

    ค่าเริ่มต้น: 90≥ 1, ≤ 3650

  • tagsarray of string

    ค่าเริ่มต้น: []

  • default_categorystring | null
  • rootsarray of string | null

    โฟลเดอร์ที่เลือกของแหล่งข้อมูล: เฉพาะรายการที่อยู่ในโฟลเดอร์เหล่านี้จะกลายเป็นการ์ด สำหรับแหล่งข้อมูลแบบกำหนดเอง คือพาธโฟลเดอร์ของเอกสาร (Guides/Billing) สำหรับคอนเนกเตอร์ คือโหนดในโครงสร้างต้นไม้ของผู้ให้บริการ

  • folder_idstring | null

    โฟลเดอร์ในคอลเลกชันของแหล่งข้อมูลที่ใช้วางการ์ด (null หมายถึงระดับบนสุดของคอลเลกชัน)

  • folder_modestring

    flat ใส่ทุกอย่างในโฟลเดอร์ที่เลือก ส่วน mirror สร้างโฟลเดอร์ตามพาธของรายการในแหล่งข้อมูล ลึกไม่เกินขีดจำกัดการซ้อนโฟลเดอร์ (3 ระดับ รายการที่ลึกกว่านั้นจะอยู่ในโฟลเดอร์ที่ใกล้ที่สุด)

    ค่าที่ใช้ได้: flatmirror

    ค่าเริ่มต้น: "flat"

การตอบกลับ

200การตอบกลับเมื่อสำเร็จ

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

  • Idempotency-Replayed

    true หมายถึงการตอบกลับนี้เป็นการส่งคืนซ้ำจากการตอบกลับที่บันทึกไว้สำหรับ Idempotency-Key นี้: ไม่มีการทำการดำเนินการซ้ำ

application/json

ออบเจ็กต์: DataSource

อย่างใดอย่างหนึ่ง

400คำขอไม่ถูกต้อง: ค่าพารามิเตอร์หรือสถานะของออบเจ็กต์ไม่อนุญาตให้ดำเนินการ (`detail` เป็นข้อความ)

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: Error

401ไม่ได้ส่งข้อมูลรับรอง (ไม่มีทั้งคุกกี้เซสชันและคีย์ API) หรือไม่พบคีย์

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: Error

403ไม่อนุญาตให้ดำเนินการ: บทบาทไม่เพียงพอ ไม่มีสิทธิ์เข้าถึงคอลเลกชันหรือการ์ด คำขอทำงานในโหมด “View as” หรือองค์กรถูกระงับหรือถูกลบ (`detail` เป็นออบเจ็กต์ที่มี `code: org_suspended | org_deleted`)

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: Error

404ออบเจ็กต์ไม่มีอยู่หรือคุณเข้าถึงไม่ได้ API ไม่ยืนยันว่าออบเจ็กต์ที่จำกัดสิทธิ์มีอยู่จริง

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: Error

422ข้อผิดพลาดในการตรวจความถูกต้องของข้อมูล: เนื้อหาหรือพารามิเตอร์ไม่ตรงกับสคีมา (`detail` เป็นรายการข้อผิดพลาดในการตรวจความถูกต้อง) หรือค่าพารามิเตอร์อยู่นอกช่วงที่กำหนด (`detail` เป็นข้อความ)

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: Error

429คำขอมากเกินไป (`api.rate_limited`) โควตาขององค์กรสำหรับนาที วัน หรือเดือนหมดแล้ว (`api.quota_exceeded` โดย `error.details` มี `quota` `limit` และ `reset_at`) องค์กรใช้ถึงขีดจำกัดแล้ว หรือบริการคำตอบไม่ว่าง (`answers.engine_busy`) รอตามเวลาในเฮดเดอร์ `Retry-After`

เฮดเดอร์การตอบกลับ

  • Retry-After

    จำนวนวินาทีที่ต้องรอก่อนลองส่งคำขอใหม่

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: Error

รหัสข้อผิดพลาด

รหัสที่เอนด์พอยต์นี้อาจส่งคืนใน error.code นอกเหนือจากรหัสทั่วไปของทุกคำขอ

การลองใหม่อย่างปลอดภัย

ส่งเฮดเดอร์ Idempotency-Key (เช่น UUID) ไปกับทุกคำขอ POST และ PATCH เมื่อลองใหม่ด้วยคีย์เดียวกันภายใน 24 ชั่วโมง Sursa จะส่งคืนการตอบกลับที่บันทึกไว้แทนการดำเนินการคำขอซ้ำ

ขีดจำกัดอัตราการเรียก

การตอบกลับมีเฮดเดอร์ RateLimit และ RateLimit-Policy รวมถึงเฮดเดอร์แบบเดิม X-RateLimit-Limit X-RateLimit-Remaining และ X-RateLimit-Reset การตอบกลับ 429 มี Retry-After เป็นวินาที ให้รอตามนั้นแล้วลองใหม่

← sources · เอกสารอ้างอิง API