Halaman ini diterjemahkan oleh Cloud Translation API.

Berlangganan acara menggunakan Google Workspace Events API

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

Peristiwa Google Workspace merepresentasikan perubahan pada resource Google Workspace, seperti kapan fasilitas dibuat, diperbarui, atau dihapus. Aplikasi Anda dapat berlangganan ke referensi Google Workspace agar Anda dapat menerima acara 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.

Berikut cara Google Workspace Events API mengirimkan peristiwa ke aplikasi Anda melalui langganan:

Aplikasi Anda berlangganan resource dalam aplikasi Google Workspace, seperti ruang Google Chat.
Resource langganan Anda berubah.
Aplikasi Google Workspace mengirimkan peristiwa ke topik di Google Cloud Pub/Sub, yang berfungsi sebagai endpoint notifikasi untuk langganan Google Workspace Anda. Peristiwa ini berisi data tentang apa yang berubah pada resource.
Aplikasi Anda 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:

Acara Google Workspace

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

Acara 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 peristiwa Google Workspace.
Peristiwa siklus proses: Acara tentang langganan Google Workspace Anda. Peristiwa siklus proses akan memberi tahu Anda tentang masalah dan status langganan, sehingga Anda dapat menghindari peristiwa langganan tidak ada. 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 ditampilkan dalam kolom targetResource pada langganan Google Workspace. Setiap langganan hanya dapat memantau satu resource. Untuk melihat referensi Google Workspace yang didukung Google Workspace Events API, lihat Peristiwa Google Workspace yang didukung.
Jenis peristiwa: Jenis perubahan yang ingin Anda dapatkan notifikasinya untuk resource target. Misalnya, jika telah berlangganan ruang Google Chat, Anda dapat memilih apakah akan menerima peristiwa tentang 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 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	Format	Peristiwa yang didukung	Batasan (jika berlaku)
Google Chat
Ruang Google Chat	`//chat.googleapis.com/spaces/SPACE_ID`	Pesan Langganan Reaksi Ruang Untuk mengetahui detailnya, lihat Berlangganan acara Google Chat.	Pengguna Google Chat yang memberikan otorisasi langganan harus menjadi anggota ruang melalui Google Workspace atau Akun Google mereka.
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 memberikan otorisasi langganan. Pengguna tidak dapat memberi otorisasi 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 mendeskripsikan data peristiwa. Peristiwa Google Workspace berisi 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 acara 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 Anda 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 berapa banyak 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 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 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 tersebut dienkode sebagai pesan Google Cloud Pub/Sub. Aplikasi Anda dapat memproses pesan Google Cloud Pub/Sub untuk mengambil tindakan atau merespons peristiwa tersebut.

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 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