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 Test Partner Sales Console untuk codelab ini.
Pahami konsep Pub/Sub.

Ringkasan

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

Hal ini sangat berguna untuk:

Cerminkan perubahan yang dilakukan langsung di Partner Sales Console di sistem Anda sendiri (misalnya, seseorang dari tim dukungan Anda yang membatalkan hak Google Workspace).
Deteksi peristiwa penting yang dipicu oleh pelanggan reseller Anda. Contoh:
- Pelanggan Google Workspace yang menyetujui Persyaratan Layanan.
- Pelanggan Google Workspace yang memverifikasi domainnya.
- Pelanggan Google Workspace yang menambahkan pengguna dengan hak Fleksibel.
- Pelanggan Google Workspace ditransfer keluar.

Penyiapan Pub/Sub terdiri dari tiga langkah berikut:

Aktifkan Pub/Sub API dan siapkan akun layanan Anda.
Buat topik Pub/Sub. Topik ini dimiliki oleh Layanan Saluran dan Anda akan menentukan akun layanan yang dapat membuat langganan.
Membuat langganan Pub/Sub. Langganan ini dapat bersifat push menggunakan webhook (metode yang disukai) atau pull.

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

Notifikasi push untuk Layanan Saluran

Format notifikasi

Berikut adalah contoh notifikasi Pub/Sub. Data pesan dikirim 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 ini: service-account@project.iam.gserviceaccount.com.
Akses ke akun Admin Super domain reseller (sebaiknya Test Partner Sales Console 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.
Beri akun layanan Anda peran IAM Pub/Sub pada project. Memberikan roles/pubsub.editor (nama peran = 'Pub/Sub Editor') sudah cukup baik untuk codelab ini, tetapi sebaiknya gunakan 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 memberi peran tersebut izin pubsub.subscriptions.create untuk membuat langganan.

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

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 diizinkan melalui metode ini yang dapat berlangganan topik baru Anda.

Buka dokumentasi accounts.register, lalu klik Coba!.
Di kolom account, masukkan accounts/ACCOUNT_ID, dengan mengganti ACCOUNT_ID dengan ID Akun Anda.
Klik Tambahkan parameter isi permintaan, pilih serviceAccount, lalu masukkan alamat email akun layanan Anda.
Klik Execute, pastikan Anda 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.

Langkah 3: Berlangganan topik

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

Langganan push: Anda menyediakan callback HTTP POST. Pub/Sub akan menggunakannya untuk memberi tahu aplikasi Anda tentang peristiwa baru.
Langganan pull: Aplikasi Anda melakukan panggilan HTTP secara berkala untuk mendapatkan perubahan yang dimasukkan ke dalam antrean.

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

Mengirim notifikasi Layanan Saluran ke Cloud Function

Langkah 3a: Buat Cloud Function

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

Buka bagian Cloud Functions di Google Cloud Console. Anda mungkin harus mengaktifkan Cloud Functions API.
Klik Create Function.
Di layar Configuration:
1. Ubah nama fungsi. Jika ingin, pilih region yang berbeda.
2. Di pemicu HTTP, ubah Authentication menjadi Allow unauthenticated invocations, lalu klik Save.
3. Catat URL Pemicu. Anda akan membutuhkannya pada langkah berikutnya.
4. Klik Next.

Di layar Code:

Pilih runtime Node.js mana pun
Ubah Titik entri menjadi log
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 selagi Cloud Function 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 menggunakan kode dengan memanggil Pub/Sub API menggunakan kredensial akun layanan Anda. Pastikan Anda tidak meniru identitas Admin Super domain reseller—yang diperlukan saat memanggil Cloud Channel API.

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

Klik Activate Cloud Shell di bagian atas Konsol Google Cloud.
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 Cloud Function yang dibuat pada 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
```

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

Buat langganan:

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

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

Membuat beberapa data

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

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

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

Contoh log untuk peristiwa Pub/Sub

Pembersihan

Menghapus Cloud Function
Menghapus langganan

Topik akan otomatis dihapus jika tidak ada pelanggan yang tersisa.

Langkah berikutnya

Codelab ini memandu Anda mempelajari cara Layanan Saluran memanfaatkan Pub/Sub untuk memungkinkan Anda membangun integrasi secara 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:

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

Jaminan dan praktik terbaik Pub/Sub

Penundaan antara peristiwa dan notifikasinya tidak dijamin. Demikian pula, urutan 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 tidak aktif atau menampilkan error 5xx, Pub/Sub akan mencoba lagi. Anda dapat menemukan informasi lebih lanjut tentang cara menerima pesan melalui push dalam dokumentasi Pub/Sub.

Jika 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 lebih mendetail dengan membuat langganan Pub/Sub tertentu dengan pemfilteran Pub/Sub.

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