Membuat langganan Google Workspace

Halaman ini menjelaskan cara menggunakan Google Workspace Events API untuk membuat langganan ke resource Google Workspace. Langganan Google Workspace memungkinkan aplikasi Anda menerima informasi tentang peristiwa Google Workspace, yang mewakili perubahan pada resource Google Workspace. Untuk mempelajari resource dan jenis peristiwa yang didukung Google Workspace Events API, lihat Ringkasan Google Workspace Events API.

Halaman ini berisi langkah-langkah berikut untuk membuat langganan Google Workspace:

  1. Menyiapkan lingkungan Anda.
  2. Membuat dan berlangganan topik Google Cloud Pub/Sub. Anda menggunakan topik ini sebagai endpoint untuk menerima peristiwa Google Workspace.
  3. Panggil metode create() Google Workspace Events API di resource Subscription.
  4. Uji langganan Google Workspace Anda untuk memastikan topik Pub/Sub Anda menerima peristiwa yang telah Anda ikuti.
  5. Jika perlu, konfigurasikan cara mengirim peristiwa ke endpoint untuk aplikasi Anda agar aplikasi dapat memproses peristiwa dan, jika perlu, mengambil tindakan.

Prasyarat

Python

  • Python 3.6 atau yang lebih baru
  • Alat pengelolaan paket pip
  • Library klien Google terbaru untuk Python. Untuk menginstal atau mengupdatenya, jalankan perintah berikut di antarmuka command line Anda:
      pip3 install --upgrade google-api-python-client google-auth-oauthlib
      
  • Untuk menggunakan perintah Google Cloud CLI dalam panduan ini:
    1. Instal Google Cloud CLI.
    2. Untuk menginisialisasi CLI gcloud, jalankan kode berikut:
    3.   gcloud init
        
  • Resource target untuk langganan:

    • Untuk berlangganan ruang Google Chat, ruang Chat tempat pengguna terautentikasi menjadi anggota. Pengguna harus menjadi anggota ruang melalui Google Workspace atau Akun Google mereka (Pengguna yang merupakan anggota ruang melalui Google Grup tidak didukung).

    • Untuk berlangganan ruang rapat Google Meet, ruang rapat tempat pengguna terautentikasi adalah pemilik. Untuk membuat ruang, lihat Bekerja dengan ruang rapat dalam dokumentasi Google Meet.

    • Untuk berlangganan ke pengguna Google Meet, ID user untuk Cloud Identity API.

  • Project Google Cloud dengan penagihan diaktifkan.

Untuk langganan Chat, Anda juga harus mengaktifkan Chat API di project Cloud serta mengonfigurasi kolom App name, Avatar URL, dan Description. Untuk mengetahui detailnya, lihat Membangun aplikasi Google Chat.

  • Memerlukan autentikasi pengguna dengan layar izin OAuth yang dikonfigurasi untuk aplikasi. Saat mengonfigurasi layar izin, Anda harus menentukan cakupan guna mendukung setiap jenis peristiwa untuk langganan. Untuk mengonfigurasi layar izin dan mengidentifikasi cakupan yang diperlukan, lihat bagian Memilih cakupan.

Menyiapkan lingkungan Anda

Bagian berikut menjelaskan cara menyiapkan lingkungan Anda sebelum membuat langganan Google Workspace.

Mengaktifkan Google Workspace Events API dan Google Cloud Pub/Sub API

Sebelum menggunakan Google API, Anda harus mengaktifkannya di project Google Cloud. Anda dapat mengaktifkan satu atau beberapa API dalam satu project Google Cloud.

Konsol Google Cloud

Di konsol Google Cloud, buka project Google Cloud untuk aplikasi Anda, lalu aktifkan Google Workspace Events API dan Pub/Sub API:

Aktifkan API

gcloud

  1. Di direktori kerja, login ke Akun Google Anda:

    gcloud auth login
    
  2. Tetapkan project Anda ke project Cloud untuk aplikasi Anda:

    gcloud config set project PROJECT_ID
    

    Ganti PROJECT_ID dengan project ID untuk project Cloud bagi aplikasi Anda.

  3. Aktifkan Google Workspace Events API dan Google Cloud Pub/Sub API:

    gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com
    

Membuat kredensial client ID OAuth

Pilih jenis aplikasi untuk mendapatkan petunjuk spesifik tentang cara membuat client ID OAuth:

Aplikasi web

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Buat Kredensial > Client ID OAuth.
  3. Klik Jenis aplikasi > Aplikasi web.
  4. Di kolom Name, ketik nama untuk kredensial tersebut. Nama ini hanya ditampilkan di Konsol Google Cloud.
  5. Tambahkan URI resmi yang terkait dengan aplikasi Anda:
    • Aplikasi sisi klien (JavaScript)–Pada Asal JavaScript yang diizinkan, klik Tambahkan URI. Kemudian, masukkan URI yang akan digunakan untuk permintaan browser. Atribut ini mengidentifikasi domain tempat aplikasi Anda dapat mengirim permintaan API ke server OAuth 2.0.
    • Aplikasi sisi server (Java, Python, dan lainnya)–Di bagian URI pengalihan yang diotorisasi, klik Tambahkan URI. Kemudian, masukkan URI endpoint yang dapat menjadi tujuan pengiriman respons oleh server OAuth 2.0.
  6. Klik Create. Layar yang dibuat klien OAuth akan muncul, yang menampilkan Client ID dan Rahasia klien Anda yang baru.

    Catat Client-ID. Rahasia klien tidak digunakan untuk aplikasi Web.

  7. Klik OK. Kredensial yang baru dibuat akan muncul di Client ID OAuth 2.0.

Android

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Buat Kredensial > Client ID OAuth.
  3. Klik Jenis aplikasi > Android.
  4. Di kolom "Nama", ketik nama untuk kredensial. Nama ini hanya ditampilkan di Konsol Google Cloud.
  5. Di kolom "Nama paket", masukkan nama paket dari file AndroidManifest.xml Anda.
  6. Di kolom "SHA-1 certificate sidik jari", masukkan sidik jari sertifikat SHA-1 yang dihasilkan.
  7. Klik Create. Layar yang dibuat klien OAuth akan muncul, menampilkan Client ID baru Anda.
  8. Klik OK. Kredensial yang baru dibuat akan muncul di bagian "Client ID OAuth 2.0".

iOS

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Buat Kredensial > Client ID OAuth.
  3. Klik Jenis aplikasi > iOS.
  4. Di kolom "Nama", ketik nama untuk kredensial. Nama ini hanya ditampilkan di Konsol Google Cloud.
  5. Di kolom "ID Paket", masukkan ID paket seperti yang tercantum di file Info.plist aplikasi.
  6. Opsional: Jika aplikasi Anda muncul di Apple App Store, masukkan ID App Store.
  7. Opsional: Di kolom "Team ID", masukkan string 10 karakter unik, yang dibuat oleh Apple dan ditetapkan ke tim Anda.
  8. Klik Create. Layar yang dibuat klien OAuth akan muncul, yang menampilkan Client ID dan Rahasia klien Anda yang baru.
  9. Klik OK. Kredensial yang baru dibuat akan muncul di bagian "Client ID OAuth 2.0".

Aplikasi Chrome

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Buat Kredensial > Client ID OAuth.
  3. Klik Jenis aplikasi > Aplikasi Chrome.
  4. Di kolom "Nama", ketik nama untuk kredensial. Nama ini hanya ditampilkan di Konsol Google Cloud.
  5. Di kolom "ID Aplikasi", masukkan string ID unik 32 karakter aplikasi Anda. Anda dapat menemukan nilai ID ini di URL Chrome Web Store aplikasi dan di Dasbor Developer Chrome Web Store.
  6. Klik Create. Layar yang dibuat klien OAuth akan muncul, yang menampilkan Client ID dan Rahasia klien Anda yang baru.
  7. Klik OK. Kredensial yang baru dibuat akan muncul di bagian "Client ID OAuth 2.0".

Aplikasi desktop

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Buat Kredensial > Client ID OAuth.
  3. Klik Jenis aplikasi > Aplikasi desktop.
  4. Di kolom Name, ketik nama untuk kredensial tersebut. Nama ini hanya ditampilkan di Konsol Google Cloud.
  5. Klik Create. Layar yang dibuat klien OAuth akan muncul, yang menampilkan Client ID dan Rahasia klien Anda yang baru.
  6. Klik OK. Kredensial yang baru dibuat akan muncul di Client ID OAuth 2.0.

TV & Perangkat Input Terbatas

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Buat Kredensial > Client ID OAuth.
  3. Klik Jenis aplikasi > TV & Perangkat input Terbatas.
  4. Di kolom "Nama", ketik nama untuk kredensial. Nama ini hanya ditampilkan di Konsol Google Cloud.
  5. Klik Create. Layar yang dibuat klien OAuth akan muncul, yang menampilkan Client ID dan Rahasia klien Anda yang baru.
  6. Klik OK. Kredensial yang baru dibuat akan muncul di bagian "Client ID OAuth 2.0".

Universal Windows Platform (UWP)

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Buat Kredensial > Client ID OAuth.
  3. Klik Jenis aplikasi > Universal Windows Platform (UWP).
  4. Di kolom "Nama", ketik nama untuk kredensial. Nama ini hanya ditampilkan di Konsol Google Cloud.
  5. Di kolom "ID Toko", masukkan nilai ID Microsoft Store yang unik dan terdiri dari 12 karakter untuk aplikasi Anda. Anda dapat menemukan ID ini di URL Microsoft Store aplikasi Anda dan di Pusat Partner.
  6. Klik Create. Layar yang dibuat klien OAuth akan muncul, yang menampilkan Client ID dan Rahasia klien Anda yang baru.
  7. Klik OK. Kredensial yang baru dibuat akan muncul di bagian "Client ID OAuth 2.0".

Download file JSON rahasia klien

File rahasia klien adalah representasi JSON dari kredensial client ID OAuth yang dapat direferensikan aplikasi Anda saat memberikan kredensial.

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Pada Client ID OAuth 2.0, klik client ID yang Anda buat.

  3. Klik Download JSON.

  4. Simpan file sebagai client_secrets.json.

Membuat dan berlangganan topik Pub/Sub

Di bagian ini, Anda akan membuat topik Pub/Sub dan berlangganan ke topik tersebut. Topik Pub/Sub Anda berfungsi sebagai endpoint notifikasi tempat langganan Google Workspace Anda menerima peristiwa.

Untuk mempelajari lebih lanjut cara membuat dan mengelola topik Pub/Sub, lihat dokumentasi Pub/Sub.

Untuk membuat dan berlangganan topik Pub/Sub:

Konsol Google Cloud

  1. Di konsol Google Cloud, buka halaman Pub/Sub:

    Buka Google Cloud Pub/Sub

    Pastikan bahwa project Cloud untuk aplikasi Anda sudah dipilih.

  2. Klik Create topic dan lakukan tindakan berikut:

    1. Masukkan nama untuk topik Anda, misalnya workspace-events-topic.
    2. Biarkan Add a default subscription dipilih. Pub/Sub memberi nama langganan default ini mirip dengan nama topik Anda, misalnya workspace-events-topic-sub.
    3. Opsional: Perbarui atau konfigurasi properti tambahan untuk topik Anda.
  3. Klik Create. Nama topik lengkap Anda diformat sebagai projects/PROJECT_ID/topics/TOPIC_ID. Anda akan menggunakan nama lengkap ini di langkah berikutnya.

  4. Berikan akses untuk memublikasikan pesan Pub/Sub ke topik Anda:

    1. Di halaman topik, buka panel samping dan buka tab Izin.
    2. Klik Add Principal.
    3. Di kolom Tambahkan akun utama, tambahkan akun layanan untuk aplikasi Google Workspace yang mengirimkan peristiwa ke langganan Anda:
      1. Untuk peristiwa Chat, chat-api-push@system.gserviceaccount.com.
      2. Untuk acara Meet, meet-api-event-push@system.gserviceaccount.com.
    4. Di menu Tetapkan peran, pilih Pub/Sub Publisher.
    5. Klik Save. Perlu waktu beberapa menit untuk memperbarui izin untuk topik Anda.

gcloud

  1. Dalam project Cloud Anda, buat topik dengan menjalankan perintah berikut:

    gcloud pubsub topics create TOPIC_ID
    

    Ganti TOPIC_ID dengan ID unik untuk topik Anda, seperti workspace-events-topic.

    Output menampilkan nama topik lengkap, yang diformat sebagai projects/PROJECT_ID/topics/TOPIC_ID. Catat namanya, dan pastikan nilai untuk PROJECT_ID adalah project ID Cloud untuk aplikasi Anda. Anda menggunakan nama topik pada langkah berikut, dan untuk membuat langganan Google Workspace di lain waktu.

  2. Berikan akses untuk memublikasikan pesan ke topik Anda:

    gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'
    

    Ganti kode berikut:

    • TOPIC_NAME: Nama topik lengkap, yang merupakan output dari langkah sebelumnya. Diformat sebagai projects/PROJECT_ID/topics/TOPIC_ID.
    • GOOGLE_WORKSPACE_APPLICATION: Aplikasi Google Workspace yang harus mengirimkan peristiwa ke langganan Anda:

      • Untuk menerima peristiwa dari Chat, gunakan chat-api-push@system.gserviceaccount.com.
      • Untuk menerima acara dari Meet, gunakan meet-api-event-push@system.gserviceaccount.com.

    Diperlukan waktu beberapa menit untuk memperbarui izin topik Anda.

  3. Buat langganan Pub/Sub untuk topik:

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME
    

    Ganti kode berikut:

    • SUBSCRIPTION_NAME: Nama untuk langganan Anda, seperti workspace-events-subscription.
    • TOPIC_NAME: Nama topik yang Anda buat di langkah sebelumnya.

Membuat langganan Google Workspace

Di bagian ini, Anda akan menggunakan metode subscriptions.create() Google Workspace Events API untuk membuat resource Subscription. Anda menentukan kolom berikut:

  • targetResource: Resource Google Workspace untuk memantau peristiwa, seperti ruang Chat.
  • eventTypes: Array dari satu atau beberapa jenis peristiwa yang ingin Anda terima tentang resource. Misalnya, jika aplikasi Anda hanya perlu mengetahui pesan baru yang diposting ke ruang Chat, aplikasi Anda cukup berlangganan ke acara tentang pesan yang dibuat.
  • notificationEndpoint: Endpoint notifikasi tempat langganan Google Workspace mengirimkan peristiwa. Gunakan topik Pub/Sub yang Anda buat di bagian sebelumnya.
  • payloadOptions: Opsi untuk menentukan jumlah data resource yang akan disertakan dalam payload peristiwa. Konfigurasi ini memengaruhi waktu habis masa berlaku langganan Anda. Untuk mempelajari lebih lanjut, lihat Data peristiwa.

Untuk membuat langganan Google Workspace:

Python

  1. Di direktori kerja, buat file bernama create_subscription.py dan tambahkan kode berikut:

    """Create subscription."""
    
    from google_auth_oauthlib.flow import InstalledAppFlow
    from googleapiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = [SCOPES]
    
    # Authenticate with Google Workspace and get user authentication.
    flow = InstalledAppFlow.from_client_secrets_file('client_secrets.json', SCOPES)
    CREDENTIALS = flow.run_local_server()
    
    # The Google Workspace resource to monitor for events.
    TARGET_RESOURCE = 'TARGET_RESOURCE'
    
    # The types of events to receive.
    EVENT_TYPES = [EVENT_TYPES]
    
    # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
    TOPIC = 'TOPIC_NAME'
    
    # Call the Workspace Events API using the service endpoint.
    service = build(
        'workspaceevents',
        'v1',
        credentials=CREDENTIALS,
    )
    
    BODY = {
        'target_resource': TARGET_RESOURCE,
        'event_types': EVENT_TYPES,
        'notification_endpoint': {'pubsub_topic': TOPIC},
        'payload_options': {'include_resource': RESOURCE_DATA},
    }
    response = service.subscriptions().create(body=BODY).execute()
    print(response)
    

    Ganti kode berikut:

    • SCOPES: Satu atau beberapa cakupan OAuth yang mendukung setiap jenis peristiwa untuk langganan. Diformat sebagai array string. Untuk mencantumkan beberapa cakupan, pisahkan dengan koma. Misalnya, 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
    • TARGET_RESOURCE: Resource Google Workspace langganan Anda, diformat sebagai nama resource lengkap. Misalnya, untuk berlangganan ruang Google Chat dengan ID ruang AAAABBBB, gunakan //chat.googleapis.com/spaces/AAAABBBB.
    • EVENT_TYPES: Satu atau beberapa jenis peristiwa yang ingin Anda ikuti di resource target. Format sebagai array string seperti 'google.workspace.chat.message.v1.created'.
    • TOPIC_NAME: Nama lengkap topik Pub/Sub yang Anda buat di project Cloud. Diformat sebagai projects/PROJECT_ID/topics/TOPIC_ID.
    • RESOURCE_DATA: Boolean yang menentukan apakah langganan menyertakan data resource dalam payload:

      • True: Menyertakan semua data resource. Untuk membatasi kolom yang disertakan, tambahkan kolom fieldMask dan tentukan setidaknya satu kolom untuk resource yang diubah. Hanya langganan ke resource Chat yang mendukung, termasuk data resource.
      • False: Mengecualikan data resource.
  2. Untuk membuat langganan Google Workspace, jalankan perintah berikut di terminal Anda:

    python3 create_subscription.py
    

Google Workspace Events API menampilkan operasi berdurasi panjang yang telah selesai dan berisi instance resource Subscription yang Anda buat.

Menguji langganan Google Workspace Anda

Untuk menguji apakah Anda menerima peristiwa Google Workspace, Anda dapat memicu suatu peristiwa dan menarik pesan ke langganan Pub/Sub.

Untuk menguji langganan Google Workspace Anda:

Konsol Google Cloud

  1. Picu satu atau beberapa jenis peristiwa di resource target langganan Google Workspace Anda. Misalnya, jika Anda telah berlangganan pesan baru di ruang Chat, posting pesan tersebut ke ruang tersebut.

  2. Di konsol Google Cloud, buka halaman Pub/Sub:

    Buka Pub/Sub

    Pastikan bahwa project Cloud untuk aplikasi Anda sudah dipilih.

  3. Di menu Pub/Sub, klik Subscriptions.

  4. Pada tabel, cari langganan Pub/Sub untuk topik Anda, lalu klik nama langganan.

  5. Klik tab Pesan.

  6. Klik Tarik. Diperlukan waktu hingga beberapa menit bagi peristiwa untuk menghasilkan pesan Pub/Sub.

gcloud

  1. Picu satu atau beberapa jenis peristiwa di resource target langganan Google Workspace Anda. Misalnya, jika Anda telah berlangganan pesan baru di ruang Chat, posting pesan tersebut dalam ruang.

  2. Jalankan perintah berikut:

    gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack
    

    Ganti kode berikut:

    • PUBSUB_SUBSCRIPTION_NAME: Nama lengkap langganan Pub/Sub Anda, yang diformat sebagai projects/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID.
    • MESSAGE_COUNT: Jumlah maksimum pesan Pub/Sub yang ingin Anda tarik.

    Diperlukan waktu hingga beberapa menit agar peristiwa dapat menghasilkan pesan Pub/Sub.

Untuk setiap peristiwa Google Workspace yang Anda picu, pesan akan dikirimkan ke langganan Pub/Sub yang berisi peristiwa tersebut. Untuk mengetahui detailnya, lihat Menerima peristiwa sebagai pesan Google Cloud Pub/Sub.

Mengonfigurasi cara aplikasi Anda menerima peristiwa

Langganan Pub/Sub yang Anda buat berbasis pull. Setelah menguji langganan Pub/Sub, Anda dapat memperbarui jenis pengiriman untuk mengubah cara aplikasi menerima peristiwa. Misalnya, Anda dapat mengonfigurasi langganan Pub/Sub ke jenis pengiriman push sehingga aplikasi Anda dapat menerima peristiwa secara langsung ke endpoint aplikasi.

Untuk mempelajari cara mengonfigurasi langganan Pub/Sub, lihat dokumentasi Pub/Sub.