อินเทอร์เฟซปลายทางของส่วนเสริม Google Workspace


ภาพรวมบริการ

เมื่อผู้ใช้เรียกให้เกิดการโต้ตอบในแอปพลิเคชันโฮสต์ที่รองรับ (Gmail, Google ปฏิทิน, Google ไดรฟ์, Google Chat, Google เอกสาร, Google ชีต, Google สไลด์ หรือ Workspace Studio) โฮสต์จะส่งเพย์โหลดเหตุการณ์ HTTP POST ไปยัง URL Callback ของส่วนเสริมที่กำหนดค่าไว้ (/*)

ปลายทางของส่วนเสริมต้องได้รับเพย์โหลดคำขอ EventObject และแสดงผลประเภทการตอบกลับ JSON ที่ถูกต้อง 1 ใน 5 ประเภทที่ระบุไว้ในการตอบกลับ: HandleEventResponse


สัญญาปลายทางของเว็บฮุค

วิธีการ เส้นทางปลายทาง เนื้อความของคำขอ เนื้อหาการตอบกลับ
POST /* (หรือเส้นทางการเรียกกลับที่กำหนดค่าไว้) EventObject ประเภทการตอบกลับ 1 ใน 5 ประเภท

คำขอ: EventObject

EventObject มีข้อมูลเมตาระดับบนสุด ช่องเหตุการณ์ทั่วไป และรายละเอียดตามบริบทของแอปพลิเคชันแบบโฮสต์ ดังนี้

บริบททั่วไปและการให้สิทธิ์

  • commonEventObject: ภาษาของผู้ใช้, enum ของแอปพลิเคชันแบบโฮสต์ (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), แพลตฟอร์มของผู้ใช้, เขตเวลา, ค่าอินพุตของแบบฟอร์มวิดเจ็ต (formInputs) และพารามิเตอร์ที่กำหนดเอง ดูCommonEventObject
  • authorizationEventObject: โทเค็นเพื่อการเข้าถึง OAuth ของผู้ใช้ โทเค็นรหัสผู้ใช้ และขอบเขตที่ได้รับสิทธิ์จากระบบ ดูAuthorizationEventObject

ออบเจ็กต์เหตุการณ์ของแอปพลิเคชันแบบโฮสต์

ออบเจ็กต์โฮสต์อย่างใดอย่างหนึ่งต่อไปนี้จะแสดงขึ้น โดยขึ้นอยู่กับแอปพลิเคชันที่เรียกใช้ Callback

  • Gmail: รหัสข้อความ, รหัสชุดข้อความ, โทเค็นเพื่อการเข้าถึงชั่วคราว และรายชื่อผู้รับข้อความ (toRecipients, ccRecipients, bccRecipients) โปรดดูหัวข้อGmailEventObject
  • ปฏิทิน: รหัสกิจกรรม, รหัสกิจกรรมที่เกิดซ้ำ, รหัสปฏิทิน, ข้อมูลผู้จัด, ผู้เข้าร่วม, ข้อมูลการประชุม และจุดเข้าใช้งาน ดูCalendarEventObject
  • ไดรฟ์: ไฟล์หรือโฟลเดอร์ที่เลือก (selectedItems) และข้อมูลเมตาของรายการเคอร์เซอร์ปัจจุบัน (activeCursorItem) ดู DriveEventObject
  • Chat: ประเภทเหตุการณ์ (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), ข้อมูลเมตาของพื้นที่ทำงาน, รายละเอียดผู้ใช้ และข้อมูลเพย์โหลด ดูChatEventObject
  • Workspace Studio: การเรียกใช้การดำเนินการ, เหตุการณ์ในวงจรของทริกเกอร์, การกำหนดค่าองค์ประกอบ, การดึงข้อมูลทรัพยากร และการแมปข้อมูลตัวแปร ดูWorkflowEventObject
  • เอกสาร: รหัสเอกสาร, ชื่อ, แฟล็กสิทธิ์ระดับไฟล์ และรูปแบบ URL ที่ตรงกัน ดูDocsEventObject
  • ชีต: รหัสสเปรดชีต, ชื่อ, แฟล็กสิทธิ์ระดับไฟล์ และรูปแบบ URL ที่ตรงกัน ดูSheetsEventObject
  • สไลด์: รหัสงานนำเสนอ, ชื่อ, แฟล็กสิทธิ์ระดับไฟล์ และรูปแบบ URL ที่ตรงกัน ดูSlidesEventObject

คำตอบ: HandleEventResponse

การตอบกลับ HTTP ที่ปลายทางเว็บฮุคแสดงผลคือออบเจ็กต์ JSON รูทที่ไม่มีแท็ก ซึ่งต้องเป็นอินสแตนซ์ของประเภทการตอบกลับ 5 ประเภทต่อไปนี้

  1. RenderActions: แสดงผลการ์ดใหม่ ไปยังกองการ์ด หรือดำเนินการ UI (เช่น {"action": {"navigations": [...]}} หรือ {"renderActions": ...})
  2. SubmitFormResponse: ตอบสนองต่อการดำเนินการส่งแบบฟอร์มของผู้ใช้ด้วยวิธีการแสดงผลการ์ดและตัวบ่งชี้การอัปเดตสถานะที่ไม่บังคับ (เช่น {"renderActions": {...}, "stateChanged": true})
  3. GetAutocompletionResponse: แสดงคำแนะนำข้อความแบบไดนามิกสำหรับช่องเติมข้อความอัตโนมัติของวิดเจ็ต (เช่น {"autoComplete": {"items": [...]}})
  4. DataActions: ทำการเปลี่ยนแปลงเอกสารหรือการดำเนินการในพื้นที่ใน Chat ที่ทริกเกอร์โดย Callback (เช่น {"hostAppDataAction": {...}})
  5. AuthorizationError: แจ้งให้ผู้ใช้ให้สิทธิ์ข้อมูลเข้าสู่ระบบของบุคคลที่สามภายนอกหรือขอขอบเขต OAuth เพิ่มเติมของ Google (เช่น {"basicAuthorizationPrompt": {"authorizationUrl": "..."}})

ข้อกำหนด OpenAPI 3.0 แบบสแตนด์อโลนและสคีมา JSON

หากต้องการสร้างสตับเซิร์ฟเวอร์ ไลบรารีของไคลเอ็นต์ SDK หรือสคีมาการตรวจสอบเพย์โหลดสำหรับปลายทาง Callback โดยอัตโนมัติ โปรดดูไฟล์ข้อกำหนดต่อไปนี้

  • ข้อกำหนด OpenAPI 3.0.3: addon_callback_openapi.json
  • คำจำกัดความของสคีมา JSON: endpoint_interface.schema.json
    • Request schema fragment: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • ส่วนย่อยของสคีมาการตอบกลับ: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse