Halaman ini diterjemahkan oleh Cloud Translation API.

Berlangganan acara menggunakan Google Workspace Events API

Halaman ini memberikan ringkasan Google Workspace Events API dan menjelaskan cara menggunakan API tersebut untuk berlangganan acara di seluruh Google Workspace.

Peristiwa Google Workspace mewakili perubahan pada resource Google Workspace, seperti saat resource dibuat, diperbarui, atau dihapus. Aplikasi Anda dapat berlangganan resource Google Workspace sehingga Anda menerima peristiwa yang relevan yang Anda minati.

Cara aplikasi Anda menerima peristiwa

Agar aplikasi dapat menerima peristiwa Google Workspace, Anda harus menggunakan Google Workspace Events API untuk membuat langganan ke resource Google Workspace.

Ilustrasi cara Google Workspace Events API mengirimkan peristiwa. — **Gambar 1.** Contoh cara Google Workspace Events API mengirimkan peristiwa ke aplikasi Chat.

Dalam contoh berikut, berikut cara Google Workspace Events API mengirimkan peristiwa ke aplikasi Google Chat melalui langganan:

Aplikasi Chat berlangganan ke ruang Chat.
Ruang Chat berubah. Misalnya, pesan baru diposting di ruang.
Chat mengirimkan peristiwa ke suatu topik di Google Cloud Pub/Sub, yang berfungsi sebagai endpoint notifikasi untuk langganan. Peristiwa ini berisi data tentang hal-hal yang berubah. Misalnya, untuk peristiwa tentang pesan baru, peristiwa tersebut berisi detail tentang resource Message yang dibuat.
Aplikasi Chat memproses pesan Pub/Sub Google Cloud yang berisi peristiwa tersebut, dan jika perlu, akan mengambil tindakan.

Terminologi penting

Berikut adalah daftar istilah umum yang digunakan di Google Workspace Events API:

Peristiwa Google Workspace

Perubahan pada resource Google Workspace. Peristiwa diformat menggunakan spesifikasi CloudEvents, dan dapat berupa peristiwa langganan atau peristiwa siklus proses:

Peristiwa langganan: Perubahan pada resource Google Workspace yang Anda pantau, seperti pesan baru di ruang Google Chat. Anda dapat menentukan jumlah detail yang ingin diterima tentang resource yang berubah. Untuk mengetahui detailnya, lihat Struktur acara Google Workspace.
Peristiwa siklus proses: Peristiwa tentang langganan Google Workspace Anda. Peristiwa siklus proses memberi tahu Anda tentang masalah dan status langganan sehingga Anda dapat menghindari peristiwa langganan yang terlewat. Secara default, langganan Anda selalu menerima peristiwa siklus proses. Untuk mengetahui detailnya, lihat Peristiwa siklus proses untuk langganan Google Workspace.

Langganan Google Workspace

Entitas bernama yang memantau resource dari aplikasi Google Workspace. Langganan diwakili oleh resource Subscription. Langganan ditentukan oleh informasi berikut:

Resource target: Resource Google Workspace yang ingin Anda pantau. Resource ini ditampilkan di kolom targetResource dari langganan Google Workspace. Setiap langganan hanya dapat memantau satu resource. Untuk melihat resource Google Workspace yang didukung Google Workspace Events API, lihat Acara Google Workspace yang didukung.
Jenis peristiwa: Jenis perubahan yang ingin Anda terima notifikasinya untuk resource target. Misalnya, jika Anda telah berlangganan ruang Google Chat, Anda dapat memilih apakah akan menerima peristiwa tentang ruang dan resource turunannya, seperti keanggotaan dan pesan.
Endpoint notifikasi: Endpoint tempat langganan Google Workspace menerima peristiwa. Google Workspace Events API mendukung topik Google Cloud Pub/Sub sebagai endpoint notifikasi. Untuk mempelajari lebih lanjut cara menggunakan Google Cloud Pub/Sub, lihat dokumentasi Google Cloud Pub/Sub.
Opsi payload: Data peristiwa yang ingin Anda terima tentang resource yang diubah.

Peristiwa Google Workspace yang didukung

Peristiwa yang dapat diterima aplikasi Anda bergantung pada resource target langganan Anda. Tabel berikut menampilkan peristiwa yang didukung untuk setiap kemungkinan resource target.

Resource target	Peristiwa yang didukung
Ruang Google Chat	Pesan Langganan Reaksi Spasi
Pengguna Google Chat	Langganan
Ruang rapat Google Meet	Konferensi Sesi peserta Rekaman Transkrip
Pengguna Google Meet	Konferensi Sesi peserta Rekaman Transkrip

Untuk mempelajari lebih lanjut, lihat panduan berikut:

Struktur peristiwa Google Workspace

Peristiwa Google Workspace mengikuti spesifikasi CloudEvents, yaitu cara standar industri untuk mendeskripsikan data peristiwa. Peristiwa Google Workspace berisi hal berikut:

Atribut CloudEvent.
Data tentang resource Google Workspace yang berubah sebagai akibat dari peristiwa

Bagian berikut menjelaskan struktur atribut dan data untuk peristiwa Google Workspace.

Atribut CloudEvent

Peristiwa Google Workspace berisi atribut CloudEvents wajib berikut:

Atribut	Deskripsi	Contoh
`datacontenttype`	Jenis data yang telah diteruskan dalam peristiwa.	`application/json`
`id`	ID untuk CloudEvent.	`spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO`
`source`	Sumber peristiwa. Untuk peristiwa Google Workspace, ini adalah nama resource lengkap langganan.	`//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg`
`specversion`	Versi spesifikasi CloudEvents yang digunakan untuk peristiwa ini.	`1.0`
`subject`	Resource Google Workspace tempat peristiwa terjadi.	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	Stempel waktu saat peristiwa terjadi, dalam format RFC 3339.	`2023-09-07T21:37:36.260127Z`
`type`	Jenis peristiwa Google Workspace.	`google.workspace.chat.message.v1.created`

Data peristiwa

Data peristiwa adalah payload yang mewakili perubahan pada resource target langganan Anda, termasuk resource turunan dari resource target. Dalam langganan, Anda dapat menentukan apakah Anda ingin payload menyertakan data tentang resource yang diubah, atau hanya nama resource yang diubah.

Misalnya, jika memiliki langganan ke ruang Chat, Anda dapat menerima peristiwa tentang pesan baru di ruang tersebut. Untuk peristiwa tentang pesan baru, data peristiwa berisi payload dengan resource Chat spaces.message yang dibuat.

Saat membuat langganan, Anda dapat menentukan jumlah data resource yang disertakan dalam peristiwa yang diterima aplikasi Anda:

Sertakan data resource: Berisi beberapa atau semua kolom resource yang diubah. Jika Anda memilih untuk menyertakan data resource, durasi langganan Anda dibatasi hingga 4 jam, atau 24 jam jika Anda menggunakan delegasi seluruh domain.
Kecualikan data resource: Hanya berisi nama resource yang diubah. Durasi langganan Anda adalah maksimal 7 hari. Untuk mendapatkan detail tentang peristiwa, Anda dapat membuat kueri resource menggunakan nama resource.

Opsi untuk data peristiwa ini ditampilkan di kolom payloadOptions langganan Anda.

Peristiwa sebagai pesan Google Cloud Pub/Sub

Langganan Google Workspace Events API menggunakan topik Google Cloud Pub/Sub sebagai endpoint notifikasi yang menerima peristiwa Google Workspace. Peristiwa dienkode sebagai pesan Google Cloud Pub/Sub. Aplikasi Anda dapat memproses pesan Google Cloud Pub/Sub untuk mengambil tindakan atau merespons peristiwa.

Contoh berikut menunjukkan pesan Google Cloud Pub/Sub yang berisi peristiwa tentang pesan yang diperbarui di ruang Chat:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

Perhatikan kolom berikut:

attributes: Atribut untuk CloudEvent, yang mencakup jenis peristiwa. Dalam hal ini, peristiwanya adalah tentang pesan yang diperbarui di ruang.
data: Data peristiwa dengan detail tentang resource spaces.message yang diperbarui, yang diformat sebagai string berenkode Base64.
messageId: ID untuk pesan Google Cloud Pub/Sub.

Untuk mempelajari lebih lanjut cara CloudEvents ditentukan dalam pesan Google Cloud Pub/Sub, lihat Penautan Protokol Google Cloud Pub/Sub untuk CloudEvents.

Berlangganan peristiwa Google Chat
Berlangganan acara Google Meet
Peristiwa siklus proses untuk langganan Google Workspace
Memilih cakupan Google Workspace Events API
Membuat langganan Google Workspace