ข้อความ Push

หน้านี้อธิบายวิธีใช้ข้อความ Push กับ Reseller API

ภาพรวม

Reseller API ใช้ Pub/Sub API เพื่อส่งข้อความ Push เกี่ยวกับเหตุการณ์การสมัครใช้บริการ Google Workspace เช่น คุณสามารถ ตั้งค่าข้อความ Push เพื่อรับการแจ้งเตือนเมื่อสถานะการสมัครใช้บริการของลูกค้า มีการเปลี่ยนแปลง

ข้อกำหนดเบื้องต้น

  • เปิดใช้ Pub/Sub API สำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google
  • มอบบทบาท IAM ของ Pub/Sub ให้กับบัญชีบริการในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ เราขอแนะนำให้มอบบทบาท roles/pubsub.editor แต่คุณสามารถใช้สิทธิ์ Pub/Sub ที่เจาะจงกว่าได้

สร้างหัวข้อ

หากต้องการสร้างหัวข้อ ให้ลงทะเบียนกับ Reseller API โดยใช้เมธอด resellernotify.register เมธอดนี้ใช้อีเมลบัญชีบริการเป็นพารามิเตอร์ มีเพียงบัญชีบริการที่ได้รับอนุญาตด้วยวิธีนี้เท่านั้นที่จะติดตามหัวข้อของคุณได้

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

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 และการตอบกลับ JSON ที่มีชื่อหัวข้อ Pub/Sub

ตัวอย่างการตอบกลับ

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

หากต้องการให้สิทธิ์บัญชีบริการเพิ่มเติม ให้เรียกใช้ resellernotify.register อีกครั้ง

เพิกถอนสิทธิ์เข้าถึงสำหรับบัญชีบริการ

Reseller API สามารถยกเลิกการลงทะเบียนบัญชีบริการได้โดยใช้ resellernotify.unregister ปลายทาง

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

ติดตามหัวข้อ

หลังจากสร้างหัวข้อ Pub/Sub แล้ว ให้ตั้งค่าวิธีที่แอปพลิเคชันใช้ เหตุการณ์การเปลี่ยนแปลง เลือกข้อใดข้อหนึ่งต่อไปนี้

  • การสมัครรับข้อมูลแบบพุช: คุณระบุการเรียกกลับ HTTP POST Pub/Sub ใช้ การเรียกกลับนี้เพื่อแจ้งให้แอปพลิเคชันทราบเกี่ยวกับเหตุการณ์ใหม่
  • การสมัครใช้บริการแบบดึงข้อมูล: แอปพลิเคชันของคุณจะเรียกใช้ HTTP เป็นระยะๆ เพื่อรับการเปลี่ยนแปลงที่อยู่ในคิว

ตัวอย่างคำขอสมัครรับข้อมูลหัวข้อ

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

แทนที่ค่าต่อไปนี้

  • PROJECT: โปรเจ็กต์ Google Cloud ของคุณ
  • SUBSCRIPTION_NAME: ชื่อที่ใช้ระบุสำหรับการสมัครใช้บริการ
  • TOPIC_NAME: หัวข้อ Pub/Sub ที่คุณสร้างไว้ก่อนหน้านี้
  • PUSH_NOTIFICATION_ENDPOINT: จุดสิ้นสุดของตัวแฮนเดิลข้อความ Push ของคุณ

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 ตัวอย่างการตอบกลับ

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

รูปแบบการแจ้งเตือน

ต่อไปนี้เป็นตัวอย่างการแจ้งเตือน Pub/Sub ข้อมูลข้อความเป็นสตริง JSON ที่เข้ารหัส Base64

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

ตัวอย่างออบเจ็กต์ message.data หลังจากถอดรหัส

{
  "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"
}

ประเภทกิจกรรม

ประเภทเหตุการณ์ที่เป็นไปได้

  • NEW_SUBSCRIPTION_CREATED: สร้างการสมัครใช้บริการใหม่แล้ว
  • SUBSCRIPTION_TRIAL_ENDED: ช่วงทดลองใช้ของการสมัครใช้บริการสิ้นสุดแล้ว
  • PRICE_PLAN_SWITCHED: ลูกค้าเปลี่ยนจากแพ็กเกจแบบยืดหยุ่นเป็น แพ็กเกจรายปี ระบบจะไม่ทริกเกอร์เหตุการณ์นี้หากลูกค้าเปลี่ยนจาก แพ็กเกจรายปีเป็นแพ็กเกจแบบยืดหยุ่นซึ่งเป็นส่วนหนึ่งของการต่ออายุ
  • COMMITMENT_CHANGED: สัญญาผูกมัดรายปีเพิ่มขึ้นหรือลดลง
  • SUBSCRIPTION_RENEWED: ต่ออายุการสมัครใช้บริการรายปีแล้ว
  • SUBSCRIPTION_SUSPENDED: การสมัครใช้บริการถูกระงับ ดูsubscription_suspension_reasons
  • SUBSCRIPTION_SUSPENSION_REVOKED: ยกเลิกการระงับแล้ว
  • SUBSCRIPTION_CANCELLED: ยกเลิกการสมัครใช้บริการแล้ว ดูsubscription_cancellation_reason ตรวจจับการโอนได้ด้วย
  • SUBSCRIPTION_CONVERTED: เปลี่ยนการสมัครใช้บริการแล้ว ตัวอย่างกรณีการใช้งาน
    • แปลงการสมัครใช้บริการโดยตรงเป็นการสมัครใช้บริการผ่านตัวแทนจำหน่าย
    • เปลี่ยนการสมัครใช้บริการแบบชำระเงินเป็นข้อเสนอระยะเวลาผ่อนผัน
    • เปลี่ยนการสมัครใช้บริการออนไลน์เป็นการสมัครใช้บริการออฟไลน์
  • SUBSCRIPTION_UPGRADE: อัปเกรด SKU ของการสมัครใช้บริการแล้ว ตัวอย่าง Google Workspace Business Starter เป็น Business Standard
  • SUBSCRIPTION_DOWNGRADE: ดาวน์เกรด SKU ของการสมัครใช้บริการแล้ว ตัวอย่าง Google Workspace Business Standard เป็น Business Starter
  • LICENSE_ASSIGNMENT_CHANGED: มีการมอบหมายหรือเพิกถอนใบอนุญาต ใช้เพื่อติดตามการเปลี่ยนแปลงจำนวนที่นั่งสำหรับการสมัครใช้บริการแบบยืดหยุ่น

เหตุผลในการยกเลิกการสมัครใช้บริการ

ระบบจะป้อนเหตุผลการยกเลิกเมื่อ event_type เป็น SUBSCRIPTION_CANCELLED ซึ่งอาจเป็นรายการต่อไปนี้

  • TRANSFERRED_OUT: ลูกค้าโอนไปใช้การเรียกเก็บเงินโดยตรงหรือตัวแทนจำหน่ายรายอื่น
  • PURCHASE_OF_SUBSUMING_SKU: ลูกค้าอัปเกรดเป็น SKU ที่ ลบล้าง SKU อื่น ตัวอย่าง: ลูกค้าที่ใช้ Google Workspace Business Starter และอัปเกรดห้องนิรภัยเป็น Business Plus ซึ่ง มีห้องนิรภัยรวมอยู่ด้วย
  • RESELLER_INITIATED: ตัวแทนจำหน่ายยกเลิกการสมัครใช้บริการ
  • OTHER: การสมัครใช้บริการถูกยกเลิกด้วยเหตุผลอื่น

เหตุผลในการระงับการสมัครใช้บริการ

ระบบจะป้อนเหตุผลในการระงับเมื่อ event_type is SUBSCRIPTION_SUSPENDED ซึ่งอาจเป็นรายการต่อไปนี้

  • PENDING_TOS_ACCEPTANCE: ลูกค้ายังไม่ได้ยอมรับ ข้อกำหนดในการให้บริการของ Google Workspace ที่ขายต่อ
  • RENEWAL_WITH_TYPE_CANCEL: ระยะเวลาผูกมัดของลูกค้าสิ้นสุดลงและมีการยกเลิกบริการ
  • RESELLER_INITIATED: ตัวแทนจำหน่ายระงับการสมัครใช้บริการด้วยตนเอง
  • TRIAL_ENDED: ช่วงทดลองใช้ของลูกค้าหมดอายุแล้วโดยที่ไม่ได้เลือกแพ็กเกจที่ไม่ใช่ช่วงทดลองใช้
  • OTHER: ลูกค้าถูกระงับเนื่องจากเหตุผลภายในของ Google เช่น การละเมิด

ข้อจำกัดของ Pub/Sub

การเรียงลำดับข้อความ Push อาจไม่เป็นไปตามลำดับเสมอไป ข้อความอาจส่ง หลายครั้งหรือไม่ส่งเลย เราขอแนะนำให้ใช้ reseller.subscriptions.get ในการสมัครใช้บริการที่เปลี่ยนแปลงเพื่อดึงข้อมูลสถานะปัจจุบัน