Thông báo đẩy

Trang này mô tả cách sử dụng thông báo đẩy với Reseller API.

Tổng quan

Reseller API sử dụng Pub/Sub API để gửi thông báo đẩy về các sự kiện gói thuê baoGoogle Workspace. Ví dụ: bạn có thể thiết lập thông báo đẩy để được thông báo khi trạng thái gói thuê bao của khách hàng thay đổi.

Điều kiện tiên quyết

Bật Pub/Sub API cho dự án trên đám mây của bạn.
Cấp vai trò IAM Pub/Sub cho tài khoản dịch vụ của bạn trên dự án trên đám mây. Bạn nên cấp vai trò roles/pubsub.editor nhưng bạn có thể sử dụng các quyền Pub/Sub cụ thể hơn.

Tạo một chủ đề

Để tạo một chủ đề, hãy đăng ký với Reseller API bằng phương thức resellernotify.register. Phương thức này lấy địa chỉ email của tài khoản dịch vụ làm tham số. Chỉ những tài khoản dịch vụ được phương thức này uỷ quyền mới có thể đăng ký chủ đề của bạn.

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

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và phản hồi JSON chứa tên chủ đề Pub/Sub của bạn.

Ví dụ về phản hồi:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Để uỷ quyền cho nhiều tài khoản dịch vụ hơn, hãy gọi lại resellernotify.register.

Thu hồi quyền truy cập đối với tài khoản dịch vụ

Reseller API có thể huỷ đăng ký tài khoản dịch vụ bằng điểm cuối resellernotify.unregister:

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

Đăng ký một chủ đề

Sau khi tạo chủ đề Pub/Sub, hãy thiết lập cách ứng dụng của bạn sử dụng các sự kiện thay đổi. Chọn một trong các lựa chọn sau:

Gói thuê bao đẩy: Bạn cung cấp lệnh gọi lại HTTP POST. Pub/Sub sử dụng lệnh gọi lại này để thông báo cho ứng dụng của bạn về các sự kiện mới.
Gói thuê bao kéo: Ứng dụng của bạn định kỳ thực hiện lệnh gọi HTTP để nhận các thay đổi đã xếp hàng.

Ví dụ về yêu cầu đăng ký một chủ đề:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Thay thế nội dung sau:

PROJECT: Dự án Google Cloud của bạn.
SUBSCRIPTION_NAME: Tên nhận dạng cho gói thuê bao của bạn.
TOPIC_NAME: Chủ đề Pub/Sub mà bạn đã tạo trước đó.
PUSH_NOTIFICATION_ENDPOINT: Điểm cuối trình xử lý thông báo đẩy.

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Ví dụ về phản hồi:

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Định dạng thông báo

Sau đây là ví dụ về thông báo Pub/Sub. Dữ liệu thông báo là một chuỗi JSON được mã hoá base64.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Ví dụ về đối tượng message.data sau khi giải mã:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Loại sự kiện

Các loại sự kiện có thể có:

NEW_SUBSCRIPTION_CREATED: Một gói thuê bao mới đã được tạo.
SUBSCRIPTION_TRIAL_ENDED: Thời gian dùng thử đã kết thúc đối với một gói thuê bao.
PRICE_PLAN_SWITCHED: Khách hàng đã chuyển từ gói linh hoạt sang gói hằng năm. Sự kiện này không được kích hoạt nếu khách hàng chuyển từ gói hằng năm sang gói linh hoạt trong quá trình gia hạn.
COMMITMENT_CHANGED: Cam kết hằng năm đã được tăng hoặc giảm.
SUBSCRIPTION_RENEWED: Một gói thuê bao hằng năm đã được gia hạn.
SUBSCRIPTION_SUSPENDED: Gói thuê bao bị tạm ngưng. Xem subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: Quyền tạm ngưng đã bị thu hồi.
SUBSCRIPTION_CANCELLED: Gói thuê bao đã bị huỷ. Xem subscription_cancellation_reason. Cũng có thể phát hiện các lượt chuyển.
SUBSCRIPTION_CONVERTED: Gói thuê bao đã được chuyển đổi. Các trường hợp ví dụ:
- Chuyển đổi gói thuê bao trực tiếp thành gói thuê bao đại lý.
- Chuyển đổi gói thuê bao có tính phí thành ưu đãi ân hạn.
- Chuyển đổi gói thuê bao trực tuyến thành gói thuê bao ngoại tuyến.
SUBSCRIPTION_UPGRADE: SKU gói thuê bao đã được nâng cấp. Ví dụ: Google Workspace Business Starter thành Business Standard.
SUBSCRIPTION_DOWNGRADE: SKU gói thuê bao đã được hạ cấp. Ví dụ: Google Workspace Business Standard thành Business Starter.
LICENSE_ASSIGNMENT_CHANGED: Giấy phép đã được chỉ định hoặc thu hồi. Sử dụng để theo dõi các thay đổi về số lượng chỗ ngồi cho gói thuê bao Linh hoạt.

Lý do huỷ đăng ký

Lý do huỷ được điền khi event_type là SUBSCRIPTION_CANCELLED. Các lý do có thể là:

TRANSFERRED_OUT: Khách hàng đã chuyển sang thanh toán trực tiếp hoặc một đại lý khác.
PURCHASE_OF_SUBSUMING_SKU: Khách hàng đã nâng cấp lên một SKU ghi đè một SKU khác. Ví dụ: Một khách hàng có Google Workspace Business Starter và Vault nâng cấp lên Business Plus, trong đó có Vault.
RESELLER_INITIATED: Đại lý đã huỷ gói thuê bao.
OTHER: Gói thuê bao đã bị huỷ vì một lý do khác.

Lý do tạm ngưng gói thuê bao

Lý do tạm ngưng được điền khi event_type là SUBSCRIPTION_SUSPENDED. Các lý do có thể là:

PENDING_TOS_ACCEPTANCE: Khách hàng chưa chấp nhận Điều khoản dịch vụ được bán lại của Google Workspace.
RENEWAL_WITH_TYPE_CANCEL: Cam kết của khách hàng đã kết thúc và dịch vụ đã bị huỷ.
RESELLER_INITIATED: Đại lý đã tạm ngưng gói thuê bao theo cách thủ công.
TRIAL_ENDED: Thời gian dùng thử của khách hàng đã hết hạn mà không chọn gói không dùng thử.
OTHER: Khách hàng bị tạm ngưng vì một lý do nội bộ của Google, chẳng hạn như hành vi lạm dụng.

Các giới hạn của Pub/Sub

Thứ tự thông báo đẩy không phải lúc nào cũng tuần tự. Thông báo có thể được gửi nhiều lần hoặc không được gửi. Bạn nên sử dụng reseller.subscriptions.get trên các gói thuê bao đã thay đổi để kéo trạng thái hiện tại.