ข้อความ Push

ภาพรวม

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

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

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

สร้างหัวข้อ

หากต้องการสร้างหัวข้อ คุณต้องลงทะเบียนกับ Reseller 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 อีกครั้ง

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

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

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

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

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

  • การสมัครรับ Push: คุณระบุการเรียกกลับ POST ของ HTTP 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 ที่ลบล้าง 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 กับการติดตามทั้งหมดที่มีการเปลี่ยนแปลงเพื่อดึงสถานะปัจจุบัน