Halaman ini menyediakan ringkasan Google Workspace Events API dan menjelaskan cara menggunakan API tersebut untuk berlangganan peristiwa 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 agar Anda menerima peristiwa relevan yang Anda minati.
Cara aplikasi Anda menerima peristiwa
Agar aplikasi Anda dapat menerima peristiwa Google Workspace, gunakan Google Workspace Events API untuk membuat langganan ke resource Google Workspace.
Dalam contoh berikut, berikut cara Google Workspace Events API mengirimkan peristiwa ke aplikasi Google Chat melalui langganan:
- Aplikasi Chat berlangganan ruang Chat.
- Ruang Chat akan berubah. Misalnya, pesan baru diposting dalam ruang.
- Chat mengirimkan peristiwa ke suatu topik di
Google Cloud Pub/Sub, yang berfungsi sebagai endpoint notifikasi untuk langganan. Peristiwa tersebut
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 Google Cloud Pub/Sub yang berisi peristiwa, dan jika perlu, akan mengambil tindakan.
Terminologi penting
Berikut adalah daftar istilah umum yang digunakan dalam Google Workspace Events API:
- Peristiwa Google Workspace
Perubahan pada fasilitas 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 seberapa banyak detail yang ingin Anda terima tentang resource yang berubah. Untuk mengetahui detailnya, lihat Struktur peristiwa Google Workspace.
- Peristiwa siklus proses
- Acara tentang langganan Google Workspace Anda. Peristiwa siklus proses memberi tahu Anda tentang masalah dan status langganan sehingga Anda dapat menghindari peristiwa langganan yang hilang. 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 direpresentasikan oleh resource
Subscription
. Langganan ditentukan oleh informasi berikut:- Resource target
- Resource Google Workspace yang ingin Anda pantau.
Resource ini diwakili di kolom
targetResource
pada langganan Google Workspace. Setiap langganan hanya dapat memantau satu resource. Untuk melihat resource Google Workspace mana yang didukung Google Workspace Events API, lihat Peristiwa Google Workspace yang didukung. - Jenis acara
- Jenis perubahan yang ingin Anda ketahui untuk resource target. Misalnya, jika Anda telah berlangganan ruang Google Chat, Anda dapat memilih apakah akan menerima peristiwa terkait ruang tersebut 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 penggunaan Google Cloud Pub/Sub lebih lanjut, 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 resource target yang memungkinkan.
Resource target | Format | Acara yang didukung | Batasan (jika ada) | |
---|---|---|---|---|
Google Chat | ||||
Ruang Google Chat |
Untuk berlangganan ruang tertentu:
Untuk berlangganan ke semua ruang tempat pengguna menjadi anggota:
|
Untuk mengetahui detailnya, lihat Berlangganan acara Google Chat. |
Pengguna Google Chat yang memberi otorisasi langganan harus menjadi anggota ruang melalui Google Workspace atau Akun Google-nya. | |
Pengguna Google Chat | //cloudidentity.googleapis.com/users/USER_ID |
Untuk mengetahui detailnya, lihat Berlangganan acara Google Chat. |
Langganan hanya menerima peristiwa tentang pengguna yang mengizinkan langganan. Pengguna tidak dapat mengizinkan langganan atas nama pengguna lain. |
|
Google Meet | ||||
Ruang rapat Google Meet | //meet.googleapis.com/spaces/SPACE_ID |
Untuk mengetahui detailnya, lihat Berlangganan acara Google Meet. |
||
Pengguna Google Meet | //cloudidentity.googleapis.com/users/USER_ID |
Untuk mengetahui detailnya, lihat Berlangganan acara Google Meet. |
Langganan menerima peristiwa tentang ruang rapat yang penggunanya adalah salah satu dari berikut ini:
|
Struktur peristiwa Google Workspace
Peristiwa Google Workspace mengikuti spesifikasi CloudEvents, yang merupakan cara standar industri untuk menjelaskan data peristiwa. Peristiwa Google Workspace mencakup hal-hal berikut:
Bagian berikut menjelaskan struktur atribut dan data untuk peristiwa Google Workspace.
Atribut CloudEvent
Peristiwa Google Workspace berisi atribut CloudEvents yang diperlukan berikut:
Atribut | Deskripsi | Contoh |
---|---|---|
|
Jenis data yang telah diteruskan dalam peristiwa. |
|
|
ID untuk CloudEvent. |
|
|
Sumber peristiwa. Untuk peristiwa Google Workspace, ini adalah nama lengkap resource langganan. |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
Versi spesifikasi CloudEvents yang digunakan untuk peristiwa ini. |
|
|
Referensi Google Workspace tempat peristiwa terjadi. |
|
|
Stempel waktu saat peristiwa terjadi, dalam format RFC 3339. |
|
|
Jenis peristiwa Google Workspace. |
|
Data peristiwa
Data peristiwa adalah payload yang mewakili perubahan pada resource target langganan Anda, termasuk resource turunan dari resource target. Di langganan, Anda dapat menentukan apakah ingin payload menyertakan data tentang resource yang diubah, atau hanya nama resource yang diubah.
Misalnya, jika memiliki langganan ruang Chat, Anda
dapat menerima peristiwa tentang pesan baru dalam ruang tersebut. Untuk peristiwa tentang
pesan baru, data peristiwa berisi payload dengan resource
spaces.message
Chat 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 hingga 7 hari. Untuk mendapatkan detail tentang peristiwa, Anda dapat membuat kueri resource menggunakan nama resource.
Opsi untuk data peristiwa ini ditampilkan di kolom payloadOptions
di 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, peristiwa berkaitan dengan pesan yang diperbarui dalam ruang.data
: Data peristiwa dengan detail tentang resourcespaces.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 Binding Protokol Google Cloud Pub/Sub untuk CloudEvents.
Topik terkait
- Berlangganan acara Google Chat
- Peristiwa siklus proses untuk langganan Google Workspace
- Memilih cakupan Google Workspace Events API
- Membuat langganan Google Workspace