ข้อความ Push

ภาพรวม

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

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

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

สร้างหัวข้อ

หากต้องการสร้างหัวข้อ คุณจะต้องลงทะเบียนกับตัวแทนจําหน่าย API โดยใช้เมธอด resellernotify.register เมธอด 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 อีกครั้ง

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

นอกจากนี้ตัวแทนจําหน่าย 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 ที่เข้ารหัสฐาน 64

{
  "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 depended 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 ที่ลบล้างอื่น เช่น หากลูกค้าที่มี Google Workspace Business Starter และ Google ห้องนิรภัยอัปเกรดเป็น Google Workspace Business Plus การสมัครใช้บริการห้องนิรภัยจะได้รับการต่ออายุเนื่องจากได้รวมอยู่ใน Google Workspace Business Plus
  • RESELLER_INITIATED: ตัวแทนจำหน่ายยกเลิกการสมัครใช้บริการ
  • OTHER: การสมัครใช้บริการถูกยกเลิกเนื่องจากเหตุผลบางอย่างอื่นนอกเหนือจากในรายการ

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

ระบบจะป้อนข้อมูลเหตุผลในการระงับการสมัครใช้บริการเมื่อ event_type คือ SUBSCRIPTION_SUSPENDED สาเหตุที่เป็นไปได้ของการระงับมีดังนี้

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

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

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