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 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 di project Cloud Anda. Memberikan peran roles/pubsub.editor adalah kompromi yang baik (mudah dan tidak terlalu luas), tetapi Anda dapat 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 diizinkan oleh metode ini yang dapat berlangganan topik yang baru Anda buat.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "[e-mail]"
}

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

Berikut adalah contoh respons:

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

Untuk mengizinkan akun layanan tambahan menggunakan topik Anda, Anda dapat memanggil resellernotify.register lagi.

Mencabut akses untuk akun layanan

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

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "[e-mail]"
}

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 POST HTTP. Pub/Sub menggunakan callback ini untuk memberi tahu aplikasi Anda tentang peristiwa baru.
• Langganan pull: Aplikasi Anda melakukan panggilan HTTP secara berkala untuk mendapatkan semua perubahan dalam antrean.

Catatan: Anda memerlukan klien Pub/Sub untuk membuat permintaan ini dan harus melakukan autentikasi menggunakan salah satu akun layanan yang terdaftar pada langkah sebelumnya. Untuk mengetahui informasi selengkapnya, lihat Subscriber.

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 Anda buat sebelumnya.
• 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 dikirim 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 jenis peristiwa yang mungkin:

• NEW_SUBSCRIPTION_CREATED: Langganan baru telah dibuat.
• SUBSCRIPTION_TRIAL_ENDED: Masa uji coba untuk langganan telah berakhir.
• PRICE_PLAN_SWITCHED: Pelanggan melakukan konversi 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 telah 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 acara ini adalah sebagai berikut:

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

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

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

• LICENSE_ASSIGNMENT_CHANGED: Lisensi ditetapkan kepada atau dicabut dari pengguna. Anda dapat menggunakan peristiwa ini untuk secara reaktif melacak perubahan jumlah slot 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 ditransfer ke penagihan langsung atau ke reseller lain.
• PURCHASE_OF_SUBSUMING_SKU: Pelanggan telah melakukan upgrade ke SKU yang menggantikan SKU lainnya. Misalnya, jika pelanggan dengan Google Workspace Business Starter dan Google Vault mengupgrade ke Google Workspace Business Plus, langganan Vault akan disertakan karena disertakan dalam 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 Reseller Google Workspace.
• RENEWAL_WITH_TYPE_CANCEL: Komitmen pelanggan berakhir dan layanan mereka dibatalkan di akhir periode.
• RESELLER_INITIATED: Reseller menangguhkan langganan secara manual.
• TRIAL_ENDED: Masa 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

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