Notifikasi push

Halaman ini menjelaskan cara menggunakan notifikasi push dengan Reseller API.

Ringkasan

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

Prasyarat

Membuat topik

Untuk membuat topik, daftar ke Reseller API menggunakan resellernotify.register metode. Metode ini menggunakan alamat email akun layanan sebagai parameter. Hanya akun layanan yang diotorisasi oleh 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 mengotorisasi lebih banyak akun layanan, 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 Anda buat sebelumnya.
  • PUSH_NOTIFICATION_ENDPOINT: Endpoint pengendali 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 didekode:

{
  "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 berakhir untuk langganan.
  • 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 dicabut.
  • SUBSCRIPTION_CANCELLED: Langganan dibatalkan. Lihat subscription_cancellation_reason. Juga dapat mendeteksi transfer.
  • SUBSCRIPTION_CONVERTED: Langganan dikonversi. Contoh kasus:
    • Mengonversi langganan langsung ke langganan reseller.
    • Mengonversi langganan berbayar ke penawaran masa tenggang.
    • Mengonversi langganan online ke langganan offline.
  • SUBSCRIPTION_UPGRADE: SKU langganan diupgrade. Contoh: Google Workspace Business Starter ke Business Standard.
  • SUBSCRIPTION_DOWNGRADE: SKU langganan diturunkan. Contoh: Google Workspace Business Standard ke Business Starter.
  • LICENSE_ASSIGNMENT_CHANGED: Lisensi ditetapkan atau dicabut. Gunakan 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 ditransfer ke penagihan langsung atau reseller lain.
  • PURCHASE_OF_SUBSUMING_SKU: Pelanggan mengupgrade ke SKU yang mengganti SKU lain. Contoh: Pelanggan dengan Google Workspace Business Starter dan Vault mengupgrade ke Business Plus, yang menyertakan 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 pemilihan paket non-uji coba.
  • OTHER: Pelanggan ditangguhkan karena alasan internal Google, seperti penyalahgunaan.

Batasan Pub/Sub

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