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 untuk mendapatkan notifikasi saat status langganan pelanggan berubah.

Prasyarat

  • Aktifkan Pub/Sub API untuk project Google Cloud Anda.
  • Berikan peran IAM Pub/Sub ke akun layanan Anda di project Cloud. 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 menggunakan metode resellernotify.register. Metode resellernotify.register menggunakan alamat email akun layanan sebagai parameter. Hanya akun layanan yang diotorisasi oleh metode ini yang dapat berlangganan topik yang baru saja Anda buat.

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 dapat memanggil resellernotify.register lagi.

Membatalkan 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 ke topik

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

  • Langganan push: Anda menyediakan callback POST HTTP. 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 identitas untuk langganan Anda.
  • TOPIC_NAME: Topik Pub/Sub yang sebelumnya Anda buat.
  • PUSH_NOTIFICATION_ENDPOINT: Endpoint pengendali 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 ditransmisikan 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 decoding:

{
  "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 berakhir untuk langganan.
  • PRICE_PLAN_SWITCHED: Pelanggan dikonversi dari paket fleksibel ke paket tahunan. Peristiwa ini tidak dipicu jika pelanggan melakukan konversi dari paket jenis komitmen ke paket fleksibel sebagai bagian dari perpanjangan.
  • COMMITMENT_CHANGED: Komitmen tahunan dinaikkan atau diturunkan.
  • SUBSCRIPTION_RENEWED: Langganan tahunan diperpanjang.
  • SUBSCRIPTION_SUSPENDED: Langganan ditangguhkan. Lihat kolom subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: Penangguhan dicabut untuk langganan yang sebelumnya ditangguhkan.
  • SUBSCRIPTION_CANCELLED: Langganan dibatalkan. Lihat kolom subscription_cancellation_reason. Juga dapat 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 ke 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 ke 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 adalah 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 mengganti SKU lain. Misalnya, jika pelanggan dengan Google Workspace Business Starter dan Google Vault mengupgrade ke Google Workspace Business Plus, langganan Vault akan digabungkan 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 Google Workspace yang Dijual Kembali.
  • 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 telah berakhir, dan pelanggan tidak memilih paket non-uji coba.
  • OTHER: Pelanggan ditangguhkan karena alasan internal Google—misalnya, penyalahgunaan.

Batasan Pub/Sub

Pengurutan notifikasi push tidak dijamin. Pesan mungkin dikirim beberapa kali dan dalam situasi ekstrem, tidak sama sekali. Sebaiknya gunakan reseller.subscriptions.get di semua langganan yang diubah untuk mengambil status saat ini.