Antarmuka endpoint add-on Google Workspace


Ringkasan layanan

Saat pengguna memicu interaksi di aplikasi host yang didukung (Gmail, Google Kalender, Google Drive, Google Chat, Google Dokumen, Google Spreadsheet, Google Slide, atau Workspace Studio), host akan mengirimkan payload peristiwa POST HTTP ke URL callback add-on yang Anda konfigurasi (/*).

Endpoint add-on Anda harus menerima payload permintaan EventObject dan menampilkan salah satu dari lima jenis respons JSON yang valid yang didokumentasikan dalam Respons: HandleEventResponse.


Kontrak endpoint webhook

Metode Jalur endpoint Isi permintaan Isi respons
POST /* (atau jalur callback yang dikonfigurasi) EventObject Salah satu dari 5 jenis respons

Permintaan: EventObject

EventObject berisi metadata tingkat teratas, kolom peristiwa umum, dan detail kontekstual aplikasi host:

Konteks umum dan otorisasi

  • commonEventObject: Lokalitas pengguna, enum aplikasi host (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), platform pengguna, zona waktu, nilai input formulir widget (formInputs), dan parameter kustom. Lihat CommonEventObject.
  • authorizationEventObject: Token akses OAuth pengguna, token ID pengguna, dan cakupan yang diizinkan sistem. Lihat AuthorizationEventObject.

Objek peristiwa aplikasi host

Bergantung pada aplikasi yang memanggil callback, salah satu objek host berikut akan ada:

  • Gmail: ID pesan, ID rangkaian pesan, token akses sementara, dan daftar penerima pesan (toRecipients, ccRecipients, bccRecipients). Lihat GmailEventObject.
  • Kalender: ID acara, ID acara rutin, ID kalender, informasi penyelenggara, tamu, data konferensi, dan titik entri. Lihat CalendarEventObject.
  • Drive: File atau folder yang dipilih (selectedItems) dan metadata item kursor saat ini (activeCursorItem). Lihat DriveEventObject.
  • Chat: Jenis peristiwa (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), metadata ruang, detail pengguna, dan data payload. Lihat ChatEventObject.
  • Workspace Studio: Pemanggilan tindakan, peristiwa siklus proses pemicu, konfigurasi elemen, pengambilan resource, dan peta data variabel. Lihat WorkflowEventObject.
  • Dokumen: ID dokumen, judul, tanda izin cakupan file, dan pola URL yang cocok. Lihat DocsEventObject.
  • Spreadsheet: ID spreadsheet, judul, tanda izin cakupan file, dan pola URL yang cocok. Lihat SheetsEventObject.
  • Slide: ID presentasi, judul, tanda izin cakupan file, dan pola URL yang cocok. Lihat SlidesEventObject.

Respons: HandleEventResponse

Respons HTTP yang ditampilkan oleh endpoint webhook Anda adalah objek JSON root tanpa tag yang harus berupa instance salah satu dari lima jenis respons berikut:

  1. RenderActions: Merender kartu baru, menavigasi tumpukan kartu, atau menjalankan tindakan UI (misalnya, {"action": {"navigations": [...]}} atau {"renderActions": ...}).
  2. SubmitFormResponse: Merespons tindakan pengiriman formulir pengguna dengan petunjuk render kartu dan indikator update status opsional (misalnya, {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse: Memberikan saran teks dinamis untuk kolom pelengkapan otomatis widget (misalnya, {"autoComplete": {"items": [...]}}).
  4. DataActions: Melakukan mutasi dokumen atau tindakan ruang Chat yang dipicu oleh callback (misalnya, {"hostAppDataAction": {...}}).
  5. AuthorizationError: Meminta pengguna untuk mengizinkan kredensial pihak ketiga eksternal atau meminta cakupan Google OAuth tambahan (misalnya, {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).

Spesifikasi OpenAPI 3.0 dan Skema JSON mandiri

Untuk membuat stub server, library klien SDK, atau skema validasi payload secara otomatis untuk endpoint callback Anda, lihat file spesifikasi berikut:

  • Spesifikasi OpenAPI 3.0.3: addon_callback_openapi.json
  • Definisi Skema JSON: endpoint_interface.schema.json
    • Fragmen skema permintaan: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • Fragmen skema respons: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse