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 Partner Sales Console Uji untuk codelab ini.

• Pelajari 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 dilakukan langsung di Partner Sales Console di sistem Anda sendiri (misalnya, seseorang dari tim dukungan Anda membatalkan hak Google Workspace).
• Mendeteksi peristiwa penting yang dipicu oleh pelanggan yang menjual kembali produk Anda. Misalnya:
  • Pelanggan Google Workspace menyetujui Persyaratan Layanan.
  • Pelanggan Google Workspace yang memverifikasi domainnya.
  • Pelanggan Google Workspace menambahkan pengguna dengan hak Fleksibel.
  • Pelanggan Google Workspace yang mentransfer.

Penyiapan Pub/Sub terdiri dari tiga langkah berikut:

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

2. Buat 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 didorong menggunakan webhook (metode yang lebih disukai) atau ditarik.

Untuk langganan push, Anda akan menghosting webhook yang menerima peristiwa yang dikeluarkan oleh Layanan Channel:

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 didekode:

{
  "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: [e-mail].
• Akses ke akun Admin Super domain reseller (sebaiknya Partner Sales Console Pengujian Anda).
• ID Akun Anda. Anda dapat menemukannya di Setelan Partner Sales Console.

Untuk menyiapkan akun layanan:

• Buka bagian Library API di konsol Google Cloud dan aktifkan Pub/Sub API.
• Berikan peran IAM Pub/Sub ke akun layanan Anda di project. Memberikan roles/pubsub.editor (nama peran = 'Pub/Sub Editor') sudah cukup baik untuk codelab ini, tetapi Anda mungkin ingin menggunakan hak istimewa yang lebih terperinci dalam integrasi produksi Anda. Anda dapat menemukan detail peran IAM lengkap di halaman Kontrol akses Pub/Sub.
• Jika memilih untuk menerapkan peran khusus, Anda harus memberikan izin pubsub.subscriptions.create kepada peran tersebut untuk membuat langganan.

Mungkin ada penundaan setelah menerapkan peran dan izin ini ke akun Anda.

Perhatian: Anda akan menerima error 403 jika tidak ada peran IAM di akun layanan.

Langkah 2: Buat topik untuk akun Anda

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

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

Anda akan mendapatkan respons 200 yang mirip dengan berikut ini:

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

Ini adalah topik Pub/Sub tempat peristiwa akan diposting.

Catatan: Nilai ini diperlukan di langkah 3b.

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 menyediakan callback POST HTTP. Pub/Sub akan menggunakannya untuk memberi tahu aplikasi Anda tentang peristiwa baru.
• Langganan pull: Aplikasi Anda secara berkala melakukan panggilan HTTP untuk mendapatkan perubahan yang diantrekan.

Dalam codelab ini, kita akan menggunakan Push dan mengirim semua peristiwa ke fungsi Cloud Run yang akan mencatat log di Cloud Logging.

Langkah 3a: Buat fungsi Cloud Run

Pada langkah ini, kita akan membuat fungsi Cloud Run yang akan mencatat pesan yang diterima ke dalam log.

1. Buka bagian Fungsi Cloud Run di konsol Google Cloud. Anda mungkin harus mengaktifkan Cloud Run Functions API.
2. Klik Create Function.
3. Di layar Konfigurasi:
   1. Ubah nama fungsi. Atau, pilih region lain.
   2. Di pemicu HTTP, ubah Autentikasi menjadi Izinkan pemanggilan yang tidak diautentikasi, lalu klik Simpan.
   3. Catat URL Pemicu. Anda akan membutuhkannya pada langkah berikutnya.
   4. Klik Berikutnya.

4. Di layar Code:

   1. Memilih runtime Node.js
   2. Ubah Titik entri 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 Run di-deploy.

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 menggunakan kredensial akun layanan Anda. Pastikan Anda tidak meniru identitas Super Admin domain reseller Anda, yang diperlukan saat memanggil Cloud Channel API.

Untuk tujuan codelab ini, Anda akan menggunakan alat gcloud CLI di Cloud Shell.

1. Klik Activate Cloud Shell di bagian atas Konsol Google Cloud.

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 Run yang dibuat di langkah 3a:

   SERVICE_ACCOUNT=[e-mail]
   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.

Membuat beberapa data

Setelah menyelesaikan langkah-langkah sebelumnya, Anda siap menerima data.

Cara termudah adalah membuat pelanggan di Partner Sales Console dan menyediakan produk. Jika telah menyelesaikan codelab penyediaan Workspace menyeluruh, Anda dapat membuat pelanggan dengan Google Workspace dengan menjalankan kode contoh.

Buka fungsi Anda di konsol Google Cloud dan buka tab Logs. Berikut adalah contoh yang akan Anda lihat.

Catatan: dalam kasus yang jarang terjadi, mungkin perlu waktu beberapa menit agar langganan Pub/Sub mulai menerima peristiwa dari topik.

Pembersihan

• Menghapus fungsi Cloud Run
• Menghapus langganan

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

Langkah berikutnya

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

Referensi peristiwa

Lihat referensi RPC untuk mengetahui daftar peristiwa yang dihasilkan oleh Layanan Channel.

Referensi API

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

• Gunakan accounts.register untuk membuat topik.
• Gunakan subscriptions.create Pub/Sub API untuk membuat langganan Pub/Sub.
• Lihat accounts.listSubscribers dan accounts.unregister untuk mengetahui endpoint tambahan yang dapat Anda gunakan dalam integrasi.

Jaminan dan praktik terbaik Pub/Sub

Penundaan antara peristiwa dan notifikasinya tidak dijamin. Demikian pula, pengurutan notifikasi tidak dijamin. Terakhir, pesan dapat dikirim beberapa kali.

Praktik terbaik endpoint push:

• Karena pesan dapat tertunda, dikirim tidak berurutan, atau dikirim beberapa kali, endpoint Anda harus idempoten, dan menggunakan 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 lebih memilih untuk menggunakan pull, Anda dapat menemukan informasi tentang cara menerima pesan melalui pull dalam dokumentasi Pub/Sub.

Pemfilteran peristiwa

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

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