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 liên quan đến gói thuê bao Google Workspace. Ví dụ: bạn có thể thiết lập thông báo đẩy để nhận 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 API Pub/Sub 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 trong 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ý bằng 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 uỷ quyền bằng phương thức này mới có thể đăng ký theo dõi chủ đề của bạn.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "[e-mail]"
}

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và một 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 của tài khoản dịch vụ

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

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "[e-mail]"
}

Đăng ký theo dõi 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:

• Đăng ký đẩy: Bạn cung cấp một 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.
• Đăng ký kéo: Ứng dụng của bạn định kỳ thực hiện một lệnh gọi HTTP để nhận các thay đổi được đưa vào hàng đợi.

Lưu ý: Sử dụng ứng dụng Pub/Sub để đưa ra yêu cầu này. Bạn phải xác thực bằng một trong các tài khoản dịch vụ đã đăng ký ở bước trước. Để biết thêm thông tin, hãy xem phần Người đăng ký.

Ví dụ về yêu cầu đăng ký theo dõi 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 trên đám mây 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 của bạn.

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: Bạn đã tạo một gói thuê bao mới.
• SUBSCRIPTION_TRIAL_ENDED: Thời gian dùng thử gói thuê bao đã kết thúc.
• 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 sẽ không được kích hoạt nếu khách hàng chuyển đổi từ gói hằng năm sang gói linh hoạt trong quá trình gia hạn.
• COMMITMENT_CHANGED: Gói cam kết hàng năm đã được tăng hoặc giảm.
• SUBSCRIPTION_RENEWED: 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: Lệnh tạm ngưng đã được 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 khoản.
• SUBSCRIPTION_CONVERTED: Gói thuê bao đã được chuyển đổi. Ví dụ về các trường hợp:
  • Chuyển đổi gói thuê bao trực tiếp sang gói thuê bao qua người bán lại.
  • Chuyển đổi gói thuê bao có tính phí sang ưu đãi gia hạn.
  • Chuyển đổi gói thuê bao trực tuyến sang gói thuê bao ngoại tuyến.
• SUBSCRIPTION_UPGRADE: SKU của gói thuê bao đã được nâng cấp. Ví dụ: Google Workspace Business Starter lên Business Standard.
• SUBSCRIPTION_DOWNGRADE: SKU của gói thuê bao đã bị hạ cấp. Ví dụ: Google Workspace Business Standard sang Business Starter.
• LICENSE_ASSIGNMENT_CHANGED: Giấy phép đã được chỉ định hoặc thu hồi. Dùng để theo dõi số lượng chỗ ngồi thay đổi đối với gói thuê bao linh hoạt.

Lý do huỷ gói thuê bao

Lý do hủy được điền sẵn khi event_type là SUBSCRIPTION_CANCELLED. Lý do có thể là:

• TRANSFERRED_OUT: Khách hàng đã chuyển sang phương thức 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 đang dùng Google Workspace Business Starter và Vault nâng cấp lên gói Business Plus (có Vault).
• RESELLER_INITIATED: Người bán lại đã huỷ gói thuê bao.
• OTHER: Gói thuê bao bị huỷ vì lý do khác.

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

Lý do tạm ngưng sẽ được điền sẵn khi event_type là SUBSCRIPTION_SUSPENDED. 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 sai trái.

Giới hạn Pub/Sub

Thông báo đẩy không phải lúc nào cũng theo thứ tự. Tin nhắn 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.