Notifikasi Pub/Sub

  • Pastikan Anda menyelesaikan codelab penyiapan API untuk menyiapkan project Google Cloud dan membuat akun layanan untuk memanggil Cloud Channel API.

  • Sebaiknya gunakan Konsol Layanan Saluran Uji Coba untuk codelab ini.

  • Biasakan diri Anda dengan konsep Pub/Sub.

Ringkasan

Cloud Channel API menggunakan Pub/Sub untuk mengirimkan notifikasi tentang berbagai peristiwa pelanggan dan hak.

Hal ini sangat berguna untuk:

  • Mencerminkan perubahan yang dibuat langsung di Konsol Layanan Saluran di sistem Anda sendiri (misalnya, seseorang dari tim dukungan Anda membatalkan hak Google Ruang Kerja).
  • Mendeteksi peristiwa penting yang dipicu oleh pelanggan yang dijual kembali. Misalnya:
    • Pelanggan Google Workspace yang menyetujui Persyaratan Layanan.
    • Pelanggan Google Workspace yang memverifikasi domain mereka.
    • Pelanggan Google Workspace yang menambahkan pengguna pada hak Fleksibel.
    • Pelanggan Google Workspace yang melakukan transfer.

Menyiapkan Pub/Sub terdiri dari tiga langkah berikut:

  1. Aktifkan Pub/Sub API dan siapkan akun layanan Anda.

  2. Membuat topik Pub/Sub. Topik ini dimiliki oleh Layanan Saluran dan Anda akan menentukan akun layanan yang dapat membuat langganan.

  3. Buat langganan Pub/Sub. Langganan ini dapat berupa push menggunakan webhook (metode pilihan) atau pull.

Untuk langganan push, Anda akan menjadi host webhook yang menerima peristiwa yang dipancarkan oleh Layanan Saluran:

Notifikasi push untuk Layanan Saluran

Format notifikasi

Berikut adalah contoh notifikasi Pub/Sub. Data pesan ditransmisikan sebagai string JSON berenkode base64.

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

Ini adalah data pesan yang sama, yang didekodekan:

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

Langkah 1: Aktifkan Pub/Sub API dan siapkan akun layanan Anda

Untuk menjalankan codelab ini, Anda memerlukan hal berikut:

  • Alamat email akun layanan di project Anda. Alamat ini akan terlihat seperti: service-account@project.iam.gserviceaccount.com.
  • Akses ke akun Admin Super domain pengecer (sebaiknya Konsol Layanan Saluran Uji Coba).
  • ID Akun Anda. Anda dapat menemukannya di Setelan Konsol Layanan Channel.

Untuk menyiapkan akun layanan:

  • Buka bagian Library API di Google Cloud Console dan aktifkan Pub/Sub API.
  • Memberikan peran Pub/Sub IAM pada project ke akun layanan Anda. Pemberian roles/pubsub.editor adalah opsi yang baik untuk tujuan codelab ini, tetapi Anda dapat menggunakan hak istimewa yang lebih lengkap dalam integrasi produksi. Anda dapat menemukan referensi lengkap di halaman Kontrol akses Pub/Sub.

Langkah 2: Buat topik untuk akun Anda

Untuk membuat topik Pub/Sub, Anda perlu menggunakan metode accounts.register. Metode ini menggunakan email akun layanan sebagai parameter. Hanya akun layanan yang diotorisasi melalui metode ini yang dapat berlangganan ke topik baru Anda.

  1. Buka dokumentasi accounts.register dan klik Coba!.
  2. Di kolom account, masukkan accounts/ACCOUNT_ID, ganti ACCOUNT_ID dengan ID Akun Anda.
  3. Klik Tambahkan parameter isi permintaan, pilih serviceAccount, dan masukkan alamat email akun layanan Anda.
  4. Klik Execute, pastikan untuk login sebagai Admin Super domain reseller Anda.

Anda akan mendapatkan respons 200 seperti berikut:

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

Ini adalah topik Pub/Sub tempat peristiwa akan diposkan.

Langkah 3: Berlangganan topik

Setelah membuat topik Pub/Sub, Anda perlu menyiapkan cara aplikasi Anda menggunakan peristiwa perubahan. Anda memiliki dua opsi:

  • Langganan push: Anda memberikan callback HTTP POST. Pub/Sub akan menggunakan ini untuk memberi tahu aplikasi Anda tentang acara baru.
  • Tarik langganan: Aplikasi secara berkala melakukan panggilan HTTP untuk mendapatkan perubahan antrean.

Dalam codelab ini, kita akan menggunakan Push dan mengirim semua peristiwa ke Cloud Fungsi yang akan login di Cloud Logging.

Mendorong notifikasi Layanan Saluran ke Fungsi Cloud

Langkah 3a: Buat Fungsi Cloud

Pada langkah ini, kita akan membuat Fungsi Cloud yang akan mencatat pesan yang diterima.

  1. Buka bagian Cloud Functions di Google Cloud Console. Anda mungkin harus mengaktifkan Cloud Functions API.
  2. Klik Buat Fungsi.
  3. Di layar Konfigurasi:
    1. Ubah nama fungsi. Atau, pilih wilayah lain.
    2. Di pemicu HTTP, ubah Authentication menjadi Izinkan pemanggilan yang tidak diautentikasi, dan klik Save.
    3. Catat URL Pemicu. Anda akan memerlukannya di langkah berikutnya.
    4. Klik Next.
  4. Di layar Kode:

    1. Pilih waktu proses Node.js
    2. Ubah Titik masuk menjadi log
    3. Di file index.js, ganti kode contoh dengan:
    exports.log = (req, res) => {
      if (req.body && req.body.message) {
        console.log(req.body);
        const message = req.body.message;
        // data is base64-encoded JSON
        const data = new Buffer.from(message.data, 'base64').toString();
        console.log(data);
      }
      res.status(200).send('OK');
    };
    

Anda dapat melanjutkan ke langkah berikutnya saat Fungsi Cloud diterapkan.

Langkah 3b: Buat langganan

Hanya akun layanan yang telah terdaftar untuk topik Layanan Saluran (lihat langkah 2) yang dapat membuat langganan.

Anda dapat melakukannya dengan kode dengan memanggil Pub/Sub API dengan kredensial akun layanan Anda. Pastikan Anda tidak meniru Super Admin domain pengecer — yang diperlukan saat memanggil Cloud Channel API.

Untuk keperluan codelab ini, Anda akan menggunakan fitur fitur gcloud di Cloud Shell.

  1. Klik Aktifkan Cloud Shell di bagian atas Google Cloud Console.

  2. Setelah shell siap, jalankan perintah berikut. Ganti nilai SERVICE_ACCOUNT dengan alamat email akun layanan Anda, TOPIC dengan topik yang dibuat di langkah 2, dan PUSH_ENDPOINT dengan URL Pemicu Fungsi Cloud yang dibuat di langkah 3a:

    SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
    TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
    PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
    
  3. Aktifkan akun layanan di shell:

    gcloud iam service-accounts keys create sa-keys.json \
        --iam-account=$SERVICE_ACCOUNT
    gcloud auth activate-service-account --key-file=sa-keys.json
    
  4. Buat langganan:

    gcloud pubsub subscriptions create channel-pubsub-test \
        --topic=$TOPIC \
        --push-endpoint=$PUSH_ENDPOINT
    

Anda dapat mengonfirmasi bahwa langganan telah disiapkan dengan membuka bagian langganan Pub/Sub.

Buat beberapa data

Setelah menyelesaikan langkah sebelumnya, Anda siap menerima data.

Cara termudah adalah membuat pelanggan di Konsol Layanan Channel dan menyediakan produk. Jika Anda telah menyelesaikan codelab penyediaan ruang kerja menyeluruh, Anda dapat membuat pelanggan dengan Google Ruang Kerja dengan menjalankan kode contoh.

Buka fungsi Anda di Google Cloud Console dan buka tab Log. Berikut ini adalah contoh yang harus Anda lihat.

Contoh log untuk aktivitas Pub/Sub

Pembersihan

  • Hapus Fungsi Cloud
  • Hapus langganan

Topik akan dihapus secara otomatis jika tidak ada pelanggan yang tersisa.

Langkah berikutnya

Codelab ini memandu Anda menemukan bagaimana Layanan Channel memanfaatkan Pub/Sub untuk memungkinkan Anda membangun integrasi dengan cara yang reaktif, dan dalam skala besar.

Referensi peristiwa

Lihat referensi RPC untuk daftar peristiwa yang dihasilkan oleh Layanan Saluran.

Referensi API

Codelab ini memanfaatkan Google Cloud Console, tetapi Anda dapat melakukan langkah-langkah ini secara terprogram. Untuk melakukannya:

Jaminan Pub/Sub dan praktik terbaik

Penundaan antara acara dan notifikasi tidak dijamin. Demikian pula, urutan notifikasi tidak dijamin. Terakhir, pesan dapat dikirim beberapa kali.

Mendorong praktik terbaik endpoint:

  • Karena pesan mungkin tertunda, tidak teratur, atau dikirim beberapa kali, endpoint Anda harus idempoten, dan gunakan customers.get dan entitlements.get

  • Meskipun waktu tunggu Pub/Sub default untuk push adalah 10 detik (ini dapat ditingkatkan melalui ackDeadline langganan Pub/Sub), sebaiknya gunakan arsitektur berbasis pesan dan buat endpoint merespons secepat mungkin.

  • Jika endpoint Anda tidak aktif atau menampilkan error 5xx, Pub/Sub akan mencoba lagi. Anda dapat menemukan informasi lebih lanjut tentang cara menerima pesan melalui push di dokumentasi Pub/Sub.

Jika Anda lebih suka menggunakan pull, Anda dapat menemukan informasi tentang cara menerima pesan melalui pull di dokumentasi Pub/Sub.

Pemfilteran peristiwa

Karena notifikasi Layanan Saluran menyertakan attributes, Anda dapat membuat langganan yang terperinci dengan membuat langganan Pub/Sub tertentu dengan pemfilteran Pub/Sub.

Misalnya, memfilter dengan attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" memungkinkan Anda melacak semua perubahan kursi Google Workspace.