ข้อความ Push

ภาพรวม

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

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

  • เปิดใช้ Pub/Sub API สำหรับโปรเจ็กต์ Google Cloud
  • มอบบทบาท Pub/Sub IAM ให้กับบัญชีบริการบน โปรเจ็กต์ที่อยู่ในระบบคลาวด์ การให้สิทธิ์ บทบาท 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 แล้ว คุณจะต้องตั้งค่าวิธีแอปพลิเคชัน จะใช้เหตุการณ์การเปลี่ยนแปลง เลือกตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้

  • พุชการสมัครใช้บริการ: คุณระบุ Callback ของ HTTP POST การใช้ Pub/Sub Callback นี้เพื่อแจ้งแอปพลิเคชันของคุณเกี่ยวกับกิจกรรมใหม่
  • การสมัครใช้บริการแบบพุล: แอปพลิเคชันของคุณทำการเรียก 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: ลูกค้าเปลี่ยนจากแพ็กเกจแบบยืดหยุ่นเป็นแพ็กเกจรายปี เหตุการณ์นี้จะไม่ทริกเกอร์หากลูกค้าทำ Conversion จาก แพ็กเกจประเภทสัญญาผูกมัดเป็นแพ็กเกจแบบยืดหยุ่นสำหรับการต่ออายุ
  • 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 แล้ว มาตรฐาน

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