ภาพรวม
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 CloudSUBSCRIPTION_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 StandardSUBSCRIPTION_DOWNGRADE
: SKU การสมัครใช้บริการถูกดาวน์เกรด เช่น การสมัครใช้บริการถูกดาวน์เกรดจาก Google Workspace Business Standard เป็น Business StarterLICENSE_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 PlusRESELLER_INITIATED
: ตัวแทนจำหน่ายยกเลิกการสมัครใช้บริการOTHER
: การสมัครใช้บริการถูกยกเลิกเนื่องจากเหตุผลบางอย่างอื่นนอกเหนือจากในรายการ
เหตุผลที่ระงับการสมัครใช้บริการ
ระบบจะป้อนข้อมูลเหตุผลในการระงับการสมัครใช้บริการเมื่อ event_type
คือ SUBSCRIPTION_SUSPENDED
สาเหตุที่เป็นไปได้ของการระงับมีดังนี้
PENDING_TOS_ACCEPTANCE
: ลูกค้าไม่ได้เข้าสู่ระบบและยอมรับข้อกำหนดในการให้บริการจากพาร์ทเนอร์ของ Google WorkspaceRENEWAL_WITH_TYPE_CANCEL
: สัญญาผูกมัดของลูกค้าสิ้นสุดลงและระบบได้ยกเลิกบริการเมื่อสิ้นสุดระยะเวลาRESELLER_INITIATED
: ตัวแทนจำหน่ายระงับการสมัครใช้บริการด้วยตนเองTRIAL_ENDED
: ช่วงทดลองใช้ของลูกค้าหมดอายุแล้ว และลูกค้าไม่ได้เลือกแพ็กเกจที่ไม่ใช่ช่วงทดลองใช้OTHER
: ลูกค้าถูกระงับด้วยเหตุผลภายในของ Google เช่น การละเมิด
ข้อจำกัดของ Pub/Sub
ไม่รับประกันการเรียงลำดับข้อความ Push อาจมีการส่งข้อความหลายครั้งและในสถานการณ์ที่รุนแรงไม่ได้เลย เราขอแนะนำให้ใช้ reseller.subscriptions.get
กับการสมัครใช้บริการที่เปลี่ยนแปลงทั้งหมดเพื่อดึงสถานะปัจจุบัน