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:
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
, masukkanaccounts/ACCOUNT_ID
, dengan menggantiACCOUNT_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.
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:
- Ubah nama fungsi. Jika ingin, pilih region yang berbeda.
- Di pemicu HTTP, ubah Authentication menjadi Allow unauthenticated invocations, lalu klik Save.
- Catat URL Pemicu. Anda akan membutuhkannya pada langkah berikutnya.
- 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, danPUSH_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.
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
danaccounts.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
danentitlements.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.