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 kapan resource dibuat, diperbarui, atau dihapus. Aplikasi Anda dapat berlangganan ke resource Google Workspace sehingga Anda menerima peristiwa relevan yang Anda minati.

Cara aplikasi Anda menerima peristiwa

Agar aplikasi Anda dapat menerima peristiwa Google Workspace, Anda menggunakan 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:

1. Aplikasi Chat berlangganan ke ruang Chat.
2. Ruang Chat berubah. Misalnya, pesan baru diposting di ruang.
3. Chat mengirimkan peristiwa ke suatu topik di Google Cloud Pub/Sub, yang berfungsi sebagai notification endpoint 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.
4. Aplikasi Chat memproses pesan Google Cloud Pub/Sub yang berisi peristiwa tersebut, 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 resource 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 seberapa banyak detail yang ingin Anda terima tentang resource yang berubah. Untuk mengetahui detailnya, lihat Struktur acara Google Workspace.

Peristiwa siklus proses

Acara terkait langganan Google Workspace Anda. Peristiwa siklus proses memberi tahu Anda tentang masalah dan status langganan sehingga Anda dapat menghindari kehilangan peristiwa langganan. 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 langganan Google Workspace. Setiap langganan hanya dapat memantau satu resource. Untuk melihat resource Google Workspace mana yang didukung oleh Google Workspace Events API, lihat Acara Google Workspace yang didukung.

Jenis acara

Jenis perubahan yang ingin Anda dapatkan notifikasinya untuk target resource. 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 notification endpoint. 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 berubah.

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

Untuk mempelajari lebih lanjut, lihat panduan berikut:

• Berlangganan ke peristiwa Google Chat
• Berlangganan peristiwa Google Drive
• Berlangganan ke acara Google Meet

Struktur peristiwa Google Workspace

Peristiwa Google Workspace mengikuti spesifikasi CloudEvents, yang merupakan cara standar industri untuk mendeskripsikan data peristiwa. Acara 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

Acara Google Workspace berisi atribut CloudEvents wajib berikut:

Data peristiwa

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

Misalnya, jika Anda 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 spaces.message Chat yang dibuat.

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

• Menyertakan 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 di seluruh domain.
• Mengecualikan 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 notification endpoint 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, acara tersebut adalah tentang pesan yang diperbarui di ruang.
• data: Data peristiwa dengan detail tentang resource spaces.message yang diperbarui, 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 Pengikatan Protokol Google Cloud Pub/Sub untuk CloudEvents.

Topik terkait

• Memilih cakupan Google Workspace Events API
• Membuat langganan Google Workspace