Notifikasi push

Halaman ini menjelaskan cara menggunakan notifikasi push dengan Reseller API.

Ringkasan

Reseller API menggunakan Pub/Sub API untuk mengirimkan notifikasi push tentang peristiwa langganan Google Workspace. Misalnya, Anda dapat menyiapkan notifikasi push untuk menerima 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 Anda. Pemberian peran roles/pubsub.editor direkomendasikan, tetapi Anda dapat menggunakan izin Pub/Sub yang lebih spesifik.

Membuat topik

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

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.

Contoh respons:

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

Untuk memberikan otorisasi pada akun layanan lainnya, panggil resellernotify.register lagi.

Mencabut akses untuk akun layanan

Reseller API dapat membatalkan pendaftaran akun layanan 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, siapkan cara aplikasi Anda 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 perubahan yang diantrekan.

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. 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 adalah string JSON berenkode base64.

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

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 dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Jenis peristiwa

Jenis peristiwa yang mungkin:

  • 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 tahunan ke paket fleksibel sebagai bagian dari perpanjangan.
  • COMMITMENT_CHANGED: Komitmen tahunan ditingkatkan atau diturunkan.
  • SUBSCRIPTION_RENEWED: Langganan tahunan diperpanjang.
  • SUBSCRIPTION_SUSPENDED: Langganan ditangguhkan. Lihat subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: Penangguhan telah dicabut.
  • SUBSCRIPTION_CANCELLED: Langganan dibatalkan. Lihat subscription_cancellation_reason. Juga dapat mendeteksi transfer.
  • SUBSCRIPTION_CONVERTED: Langganan dikonversi. Contoh kasus:
    • Mengonversi langganan langsung menjadi langganan reseller.
    • Mengonversi langganan berbayar ke penawaran masa tenggang.
    • Mengonversi langganan online menjadi langganan offline.
  • SUBSCRIPTION_UPGRADE: SKU langganan diupgrade. Contoh: Google Workspace Business Starter ke Business Standard.
  • SUBSCRIPTION_DOWNGRADE: SKU langganan didowngrade. Contoh: Google Workspace Business Standard ke Business Starter.
  • LICENSE_ASSIGNMENT_CHANGED: Lisensi ditetapkan atau dicabut. Digunakan untuk melacak perubahan jumlah kursi untuk langganan Fleksibel.

Alasan pembatalan langganan

Alasan pembatalan diisi saat event_type adalah SUBSCRIPTION_CANCELLED. Kemungkinan penyebab:

  • TRANSFERRED_OUT: Pelanggan beralih ke penagihan langsung atau reseller lain.
  • PURCHASE_OF_SUBSUMING_SKU: Pelanggan mengupgrade ke SKU yang menggantikan SKU lain. Contoh: Pelanggan dengan Google Workspace Business Starter dan Vault melakukan upgrade ke Business Plus, yang mencakup Vault.
  • RESELLER_INITIATED: Reseller membatalkan langganan.
  • OTHER: Langganan dibatalkan karena alasan lain.

Alasan penangguhan langganan

Alasan penangguhan diisi saat event_type adalah SUBSCRIPTION_SUSPENDED. Kemungkinan penyebab:

  • PENDING_TOS_ACCEPTANCE: Pelanggan belum menyetujui Persyaratan Layanan Google Workspace yang Dijual Kembali.
  • RENEWAL_WITH_TYPE_CANCEL: Komitmen pelanggan berakhir dan layanan dibatalkan.
  • RESELLER_INITIATED: Reseller menangguhkan langganan secara manual.
  • TRIAL_ENDED: Uji coba pelanggan berakhir tanpa memilih paket non-uji coba.
  • OTHER: Pelanggan ditangguhkan karena alasan internal Google, seperti penyalahgunaan.

Batasan Pub/Sub

Urutan notifikasi push tidak selalu berurutan. Pesan mungkin dikirimkan beberapa kali atau tidak dikirimkan sama sekali. Sebaiknya gunakan reseller.subscriptions.get pada langganan yang berubah untuk menarik status saat ini.