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:

  1. Aplikasi Chat berlangganan ruang Chat.
  2. Ruang Chat akan berubah. Misalnya, pesan baru diposting yang besar.
  3. 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.
  4. 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 Acara yang didukung
Ruang Google Chat
  • Pesan
  • Langganan
  • Reaksi
  • Spasi
Pengguna Google Chat
  • Langganan
Ruang rapat Google Meet
  • Konferensi
  • Sesi peserta
  • Rekaman
  • Transkrip
Pengguna Google Meet
  • Konferensi
  • Sesi peserta
  • Rekaman
  • Transkrip

Untuk mempelajari lebih lanjut, lihat panduan berikut:

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 langganan, 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.