Notifikasi push

Ringkasan

Reseller API menggunakan Pub/Sub API untuk mengirimkan notifikasi push tentang berbagai peristiwa langganan Google Workspace. Misalnya, Anda dapat menyiapkan notifikasi push agar diberi tahu saat status langganan pelanggan Anda berubah.

Prasyarat

  • Aktifkan Pub/Sub API untuk project Google Cloud Anda.
  • Berikan peran IAM Pub/Sub ke akun layanan Anda di project Cloud Anda. Memberikan peran roles/pubsub.editor adalah kompromi yang baik (mudah dan tidak terlalu luas), tetapi Anda mungkin ingin menggunakan izin Pub/Sub yang lebih spesifik.

Membuat topik

Untuk membuat topik, Anda harus mendaftar ke Reseller API dengan menggunakan metode resellernotify.register. Metode resellernotify.register menggunakan alamat email akun layanan sebagai parameter. Hanya akun layanan yang diotorisasi dengan metode ini yang dapat berlangganan topik yang baru dibuat.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Respons yang berhasil akan menampilkan kode status HTTP 200 dan respons JSON yang berisi nama topik Pub/Sub Anda.

Berikut adalah contoh respons:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Untuk memberi otorisasi akun layanan tambahan agar dapat menggunakan topik Anda, Anda dapat memanggil resellernotify.register lagi.

Mencabut akses untuk akun layanan

Reseller API juga memberikan kemampuan untuk membatalkan pendaftaran akun layanan dengan menggunakan endpoint resellernotify.unregister:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Berlangganan topik

Setelah membuat topik Pub/Sub, Anda perlu menyiapkan cara aplikasi menggunakan peristiwa perubahan. Pilih salah satu opsi berikut:

  • Langganan push: Anda menyediakan callback HTTP POST. Pub/Sub menggunakan callback ini untuk memberi tahu aplikasi Anda tentang peristiwa baru.
  • Langganan pull: Aplikasi Anda secara berkala melakukan panggilan HTTP untuk mendapatkan semua perubahan yang diantrekan.

Berikut adalah contoh permintaan untuk berlangganan topik:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Ganti kode berikut:

  • PROJECT: Project Google Cloud Anda.
  • SUBSCRIPTION_NAME: Nama identifikasi untuk langganan Anda.
  • TOPIC_NAME: Topik Pub/Sub yang sebelumnya Anda buat.
  • PUSH_NOTIFICATION_ENDPOINT: Endpoint handler notifikasi push Anda.

Respons yang berhasil akan menampilkan kode status HTTP 200. Berikut adalah contoh respons: 

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Format notifikasi

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

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Berikut adalah contoh objek message.data setelah dekode:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Jenis peristiwa

Daftar berikut berisi semua kemungkinan jenis peristiwa:

  • NEW_SUBSCRIPTION_CREATED: Langganan baru telah dibuat.
  • SUBSCRIPTION_TRIAL_ENDED: Uji coba langganan berakhir.
  • PRICE_PLAN_SWITCHED: Pelanggan beralih dari paket fleksibel ke paket tahunan. Peristiwa ini tidak dipicu jika pelanggan beralih dari paket jenis komitmen ke paket fleksibel sebagai bagian dari perpanjangan.
  • COMMITMENT_CHANGED: Komitmen tahunan ditingkatkan atau diturunkan.
  • SUBSCRIPTION_RENEWED: Langganan tahunan diperpanjang.
  • SUBSCRIPTION_SUSPENDED: Langganan ditangguhkan. Lihat kolom subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: Penangguhan dibatalkan untuk langganan yang sebelumnya ditangguhkan.
  • SUBSCRIPTION_CANCELLED: Langganan dibatalkan. Lihat kolom subscription_cancellation_reason. Dapat juga digunakan untuk mendeteksi transfer.

  • SUBSCRIPTION_CONVERTED: Langganan dikonversi. Beberapa contoh kasus untuk peristiwa ini adalah sebagai berikut:

    • Mengonversi langganan langsung menjadi langganan reseller.
    • Mengonversi langganan berbayar ke penawaran masa tenggang.
    • Mengonversi langganan online menjadi langganan offline.

  • SUBSCRIPTION_UPGRADE: SKU langganan diupgrade. Misalnya, langganan diupgrade dari Google Workspace Business Starter ke Business Standard.

  • SUBSCRIPTION_DOWNGRADE: SKU langganan didowngrade. Misalnya, langganan didowngrade dari Google Workspace Business Standard ke Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED: Lisensi ditetapkan kepada atau dicabut dari pengguna. Anda dapat menggunakan peristiwa ini untuk melacak perubahan jumlah kursi secara reaktif untuk Langganan fleksibel.

Alasan pembatalan langganan

Alasan pembatalan langganan diisi saat event_type SUBSCRIPTION_CANCELLED. Berikut adalah kemungkinan alasan pembatalan:

  • TRANSFERRED_OUT: Pelanggan telah beralih ke penagihan langsung atau ke reseller lain.
  • PURCHASE_OF_SUBSUMING_SKU: Pelanggan telah mengupgrade ke SKU yang menggantikan SKU lain. Misalnya, jika pelanggan dengan Google Workspace Business Starter dan Google Vault mengupgrade ke Google Workspace Business Plus, langganan Vault akan tercakup karena disertakan dengan Google Workspace Business Plus.
  • RESELLER_INITIATED: Reseller membatalkan langganan.
  • OTHER: Langganan dibatalkan karena alasan selain yang tercantum.

Alasan penangguhan langganan

Alasan penangguhan langganan diisi saat event_type adalah SUBSCRIPTION_SUSPENDED. Berikut adalah kemungkinan alasan penangguhan:

  • PENDING_TOS_ACCEPTANCE: Pelanggan belum login dan menyetujui Persyaratan Layanan yang Dijual Ulang Google Workspace.
  • RENEWAL_WITH_TYPE_CANCEL: Komitmen pelanggan berakhir dan layanannya dibatalkan di akhir periode.
  • RESELLER_INITIATED: Reseller menangguhkan langganan secara manual.
  • TRIAL_ENDED: Uji coba pelanggan berakhir, dan pelanggan tidak memilih paket non-uji coba.
  • OTHER: Pelanggan ditangguhkan karena alasan internal Google—misalnya, penyalahgunaan.

Batasan Pub/Sub

Urutan notifikasi push tidak dijamin. Pesan mungkin dikirimkan beberapa kali dan dalam situasi ekstrem, tidak dikirimkan sama sekali. Sebaiknya gunakan reseller.subscriptions.get pada semua langganan yang berubah untuk menarik status saat ini.