Halaman ini diterjemahkan oleh Cloud Translation API.

Berlangganan acara menggunakan Google Workspace Events API

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.

Ilustrasi cara Google Workspace Events API menayangkan 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 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: `//chat.googleapis.com/spaces/SPACE_ID` Untuk berlangganan ke semua ruang tempat pengguna menjadi anggota: `//chat.googleapis.com/spaces/-`	Pesan Langganan Reaksi Ruang 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`	Langganan 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`	Konferensi Sesi peserta Rekaman Transkrip Untuk mengetahui detailnya, lihat Berlangganan acara Google Meet.
Pengguna Google Meet	`//cloudidentity.googleapis.com/users/USER_ID`	Konferensi Sesi peserta Rekaman Transkrip Untuk mengetahui detailnya, lihat Berlangganan acara Google Meet.	Langganan menerima peristiwa tentang ruang rapat yang penggunanya adalah salah satu dari berikut ini: Pemilik ruang rapat. Penyelenggara acara Google Kalender yang terkait dengan ruang rapat.

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:

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

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
`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 lengkap resource langganan.	`//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg`
`specversion`	Versi spesifikasi CloudEvents yang digunakan untuk peristiwa ini.	`1.0`
`subject`	Referensi 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. 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 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 Binding Protokol Google Cloud Pub/Sub untuk CloudEvents.

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