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

Tạo một chủ đề

Để tạo một chủ đề, bạn cần đăng ký với Reseller API 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 bằng phương thức này mới có thể đăng ký theo dõi chủ đề bạn vừa tạo.

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.

Sau đây là một 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 của 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ý nhận thông báo đẩ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.
Gói thuê bao kéo: Ứng dụng của bạn định kỳ thực hiện một lệnh gọi HTTP để nhận tất cả các thay đổi trong hàng đợi.

Sau đây là 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 của bạn trên Google Cloud.
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. Sau đây là một 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 đượ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: 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 có cam kết 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 trường subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: Lệnh tạm ngưng đã bị thu hồi đối với một gói thuê bao từng bị tạm ngưng.
SUBSCRIPTION_CANCELLED: Gói thuê bao đã bị huỷ. Xem trường subscription_cancellation_reason. Cũng có thể dùng để phát hiện các giao dịch chuyển tiền.
SUBSCRIPTION_CONVERTED: Gói thuê bao đã được chuyển đổi. Sau đây là một số trường hợp ví dụ cho sự kiện này:
- 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ụ: 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 cho hoặc thu hồi của một người dùng. Bạn có thể sử dụng sự kiện này để theo dõi một cách thụ động các thay đổi về số lượng chỗ cho gói thuê bao linh hoạt.

Lý do huỷ gói thuê bao

Lý do huỷ gói thuê bao sẽ được điền sẵn khi event_type là SUBSCRIPTION_CANCELLED. Sau đây là những 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 chuyển 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 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 gộp vào vì gói này có trong 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 không được liệt kê.

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

Lý do tạm ngưng gói thuê bao sẽ được điền khi event_type là SUBSCRIPTION_SUSPENDED. Sau đây là những lý do có thể dẫn đến việc bị 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 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ụ của họ đã bị huỷ khi hết thời 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: Khách hàng đã hết thời gian dùng thử và 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.

Các 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 trường hợp nghiêm trọng, tin nhắn sẽ không được gửi. Bạn nên sử dụng reseller.subscriptions.get trên tất cả các thuê bao đã thay đổi để kéo trạng thái hiện tại.