Halaman ini diterjemahkan oleh Cloud Translation API.

Berlangganan acara menggunakan Google Workspace Events API

Halaman ini menyediakan ringkasan Google Workspace Events API dan menjelaskan caranya Anda dapat menggunakan API 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 ke resource Google Workspace agar Anda menerima peristiwa relevan yang membuat Anda tertarik.

Cara aplikasi Anda menerima peristiwa

Agar aplikasi Anda dapat menerima peristiwa Google Workspace, gunakan Google Workspace Events API untuk membuat langganan ke Google Workspace Google Cloud Platform.

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

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

Aplikasi Chat berlangganan ruang Chat.
Ruang Chat akan berubah. Misalnya, pesan baru diposting yang besar.
Chat mengirimkan peristiwa ke topik di Google Cloud Pub/Sub, yang berfungsi sebagai endpoint notifikasi untuk langganan. Acara berisi data tentang apa yang berubah. Misalnya, untuk acara tentang pesan tersebut, peristiwa tersebut berisi detail tentang resource Message yang dibuat.
Aplikasi Chat memproses data Google Cloud Pesan 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 CloudEvents spesifikasi, 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 berapa yang ingin Anda terima tentang sumber daya 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 agar peristiwa langganan tidak hilang. Secara default, langganan Anda akan 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 Google Workspace aplikasi. Langganan diwakili oleh Subscription resource Anda Langganan ditentukan oleh informasi berikut:

Resource target: Resource Google Workspace yang ingin Anda pantau. Resource ini diwakili di kolom targetResource dari kolom Google Workspace Anda. Setiap langganan hanya dapat memantau satu resource. Untuk melihat referensi Google Workspace mana yang Dukungan Google Workspace Events API, lihat Peristiwa Google Workspace yang didukung.
Jenis acara: Jenis perubahan yang ingin Anda dapatkan notifikasinya resource target. Misalnya, jika Anda telah berlangganan Ruang Google Chat, Anda dapat memilih apakah akan menerima acara tentang ruang dan resource turunannya, seperti keanggotaan dan pesan.
Endpoint notifikasi: Endpoint tempat Langganan Google Workspace menerima peristiwa. Tujuan 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 masing-masing 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 Spasi Untuk mengetahui detailnya, lihat Berlangganan acara Google Chat.	Pengguna Google Chat yang memberi otorisasi langganan harus menjadi anggota ruang melalui fitur Google Workspace atau menggunakan Akun Layanan Anda.
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 tempat 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 CloudEvents spesifikasi, yang merupakan cara standar industri untuk menggambarkan data peristiwa. Google Workspace peristiwa berisi hal berikut:

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

Bagian berikut ini menjelaskan struktur atribut dan data untuk Acara Google Workspace.

Atribut CloudEvent

Peristiwa Google Workspace berisi hal-hal berikut yang diperlukan Atribut CloudEvents:

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 sumber daya 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 target langganan Anda termasuk resource turunan dari resource target. Di Anda dapat menentukan apakah Anda ingin {i>payload<i} menyertakan data tentang sumber daya yang diubah, atau hanya nama sumber daya yang diubah.

Misalnya, jika Anda berlangganan ruang Chat, Anda dapat menerima peristiwa tentang pesan baru dalam ruang. Untuk acara tentang pesan baru, data peristiwa berisi payload dengan Chat spaces.message resource yang telah 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 yang diubah resource Anda Jika Anda memilih untuk menyertakan data resource, langganan Anda durasi dibatasi hingga 4 jam, atau 24 jam jika Anda menggunakan seluruh domain delegasi.
Kecualikan data resource: Hanya berisi nama resource yang diubah resource Anda Durasi langganan Anda hingga 7 hari. Untuk mendapatkan detail tentang acara tersebut, Anda dapat melakukan kueri sumber daya menggunakan nama sumber daya.

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

Peristiwa sebagai pesan Google Cloud Pub/Sub

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

Contoh berikut menampilkan pesan Google Cloud Pub/Sub yang berisi acara 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 di spasi.
data: Data peristiwa dengan detail tentang data yang diperbarui Resource spaces.message, yang diformat sebagai string berenkode Base64.
messageId: ID untuk pesan Google Cloud Pub/Sub.

Untuk mempelajari lebih lanjut cara CloudEvents ditentukan di 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