ข้อความ Push

ภาพรวม

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

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

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

สร้างหัวข้อ

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

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 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 is SUBSCRIPTION_SUSPENDED สาเหตุที่เป็นไปได้ของการระงับมีดังนี้

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

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

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