Trang này được dịch bởi Cloud Translation API.

Thông báo đẩy

Tổng quan

Reseller API sử dụng Pub/Sub API để phân phối thông báo đẩy về các sự kiện đăng ký khác nhau trong 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 Google Cloud của bạn.
Cấp vai trò IAM Pub/Sub cho tài khoản dịch vụ trên dự án trên Google Cloud. Việc cấp vai trò roles/pubsub.editor là một giải pháp thỏa hiệp hiệu quả (dễ dàng và không quá rộng), nhưng bạn nên sử dụng các quyền Pub/Sub cụ thể hơn.

Tạo một chủ đề

Để tạo chủ đề, bạn cần đăng ký với API Đại lý bằng cách sử dụng phương thức resellernotify.register. Phương thức resellernotify.register 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 theo phương thức này mới có thể đăng ký chủ đề mới tạo 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.

Sau đây là ví dụ về phản hồi:

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

Để uỷ quyền cho các tài khoản dịch vụ khác sử dụng chủ đề của bạn, bạn có thể gọi lại resellernotify.register.

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

Reseller API cũng cung cấp khả năng 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": "reseller@reseller-project.iam.gserviceaccount.com"
}

Đăng ký theo dõi một chủ đề

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

Đăng ký đẩy: Bạn cung cấp lệnh gọi lại POST HTTP. 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 tất cả thay đổi trong hàng đợi.

Sau đây là 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 của bạn trên Google Cloud.
SUBSCRIPTION_NAME: Tên nhận dạng cho gói thuê bao.
TOPIC_NAME: Chủ đề Pub/Sub mà bạn đã tạo trước đó.
PUSH_NOTIFICATION_ENDPOINT: Điểm cuối của 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. Sau đây là một phản hồi mẫu:

{
  "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 được truyền dưới dạng chuỗi JSON được mã hoá base64.

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

Sau đây là đối tượng message.data mẫu 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 depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Loại sự kiện

Danh sách sau đây chứa tất cả các loại sự kiện có thể có:

NEW_SUBSCRIPTION_CREATED: Đã 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 đổi 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 có cam kết sang gói linh hoạt trong quá trình gia hạn.
COMMITMENT_CHANGED: Mức cam kết hằng năm đã 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 trường subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: Đã thu hồi quyết định tạm ngưng đối với một gói thuê bao từng bị tạm ngưng.
SUBSCRIPTION_CANCELLED: Đã huỷ gói thuê bao. Xem trường subscription_cancellation_reason. Cũng có thể dùng để phát hiện các lượt chuyển.
SUBSCRIPTION_CONVERTED: Đã chuyển đổi gói thuê bao. Sau đây là một số ví dụ về sự kiện này:
- Chuyển đổi gói thuê bao trực tiếp thành gói thuê bao của người bán lại.
- Chuyển đổi gói thuê bao có tính phí thành ư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ụ: gói thuê bao đã được nâng cấp từ Google Workspace Business Starter lên Business Standard.
SUBSCRIPTION_DOWNGRADE: SKU của gói thuê bao đã bị hạ cấp. Ví dụ: gói thuê bao đã được hạ cấp từ Google Workspace Business Standard xuống Business Starter.
LICENSE_ASSIGNMENT_CHANGED: Giấy phép đã được chỉ định hoặc thu hồi từ người dùng. Bạn có thể sử dụng sự kiện này để 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ỷ gói thuê bao

Lý do huỷ gói thuê bao được điền khi event_type là SUBSCRIPTION_CANCELLED. Sau đây là một số lý do có thể dẫn đến việc huỷ:

TRANSFERRED_OUT: Khách hàng đã chuyển sang phương thức thanh toán trực tiếp hoặc sang 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ụ: nếu một khách hàng đang dùng gói Google Workspace Business Starter và Google Vault nâng cấp lên Google Workspace Business Plus, thì gói thuê bao Vault sẽ được đưa vào gói Google Workspace Business Plus.
RESELLER_INITIATED: Đại lý đã huỷ gói thuê bao.
OTHER: Gói thuê bao đã bị huỷ vì một số lý do khác ngoài những lý do được liệt kê.

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

Lý do tạm ngưng gói thuê bao được điền khi event_type là SUBSCRIPTION_SUSPENDED. Sau đây là một số lý do có thể dẫn đến việc tạm ngưng:

PENDING_TOS_ACCEPTANCE: Khách hàng chưa đăng nhập và chấp nhận Điều khoản dịch vụ của Google Workspace được bán lại.
RENEWAL_WITH_TYPE_CANCEL: Cam kết của khách hàng đã kết thúc và dịch vụ của họ đã bị huỷ khi hết hạn.
RESELLER_INITIATED: Người bán lại đã 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 và khách hàng không chọn gói không phải gói dùng thử.
OTHER: Khách hàng bị tạm ngưng vì lý do nội bộ của Google, ví dụ: hành vi sai trái.

Giới hạn của Pub/Sub

Chúng tôi không đảm bảo thứ tự của thông báo đẩy. Tin nhắn có thể được gửi nhiều lần và trong một số trường hợp cực đoan thì không được gửi. Bạn nên sử dụng reseller.subscriptions.get trên tất cả các gói thuê bao đã thay đổi để lấy trạng thái hiện tại.