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

Thông báo đẩy

Tổng quan

API Đại lý sử dụng API Pub/Sub để gửi thông báo đẩy về các sự kiện thuê bao 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ấp các vai trò IAM của Pub/Sub cho tài khoản dịch vụ trong dự án của bạn trên Google Cloud. Việc cấp vai trò roles/pubsub.editor là một phương án tối ưu (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 thông 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ủ đề mới 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à phản hồi mẫu:

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

Để cho phép 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 một tài khoản dịch vụ

API Đại lý cũng cho phép huỷ đăng ký các 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ý 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:

Gói thuê bao đẩy: Bạn cung cấp một lệnh gọi lại HTTP POST. Pub/Sub 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.
Kéo gói thuê bao: Ứng dụng của bạn sẽ đị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ế các đoạn mã sau:

PROJECT: Dự án của bạn trên Google Cloud.
SUBSCRIPTION_NAME: Tên nhận dạng gói thuê bao của bạn.
TOPIC_NAME: Chủ đề Pub/Sub mà bạn đã tạo trước đây.
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"
}

Dưới đâ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: Một gói thuê bao mới đã được tạo.
SUBSCRIPTION_TRIAL_ENDED: Thời gian dùng thử của một 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 không được kích hoạt nếu khách hàng chuyển đổi từ gói loại cam kết sang gói linh hoạt trong quá trình gia hạn.
COMMITMENT_CHANGED: Tăng hoặc giảm Mức cam kết hằng nă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 bị tạm ngưng trước đó.
SUBSCRIPTION_CANCELLED: Gói thuê bao đã bị huỷ. Xem trường subscription_cancellation_reason. Cũng có thể dùng để phát hiện hoạt động chuyể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 thành gói thuê bao của đại lý.
- 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 thành 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 gói Business Standard.
SUBSCRIPTION_DOWNGRADE: Đã hạ cấp SKU của gói thuê bao. Ví dụ: gói thuê bao đã bị hạ cấp từ Google Workspace Business Standard xuống gói Business Starter.
LICENSE_ASSIGNMENT_CHANGED: Giấy phép đã được chuyển nhượng cho hoặc thu hồi từ một người dùng. Bạn có thể sử dụng sự kiện này để chủ động theo dõi các thay đổi về số lượng giấy phép cho Gói thuê bao linh hoạt.

Lý do huỷ gói thuê bao

Hệ thống sẽ điền lý do huỷ gói thuê bao khi event_type là SUBSCRIPTION_CANCELLED. Sau đây là những lý do có thể khiến bạn huỷ:

TRANSFERRED_OUT: Khách hàng đã chuyển sang hình 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 sử dụng gói Google Workspace Business Starter và Google Vault nâng cấp lên gói Google Workspace Business Plus, thì gói thuê bao Vault sẽ được gộp vào vì gói thuê bao này đi kèm với 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 lý do nào đó ngoài lý do được nêu.

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

Hệ thống sẽ điền lý do tạm ngưng gói thuê bao khi event_type là SUBSCRIPTION_SUSPENDED. Sau đây là một số lý do có thể khiến tài khoản 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ụ do Google Workspace 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 thời hạn.
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 và khách hàng chưa chọn gói không phải gói dùng thử.
OTHER: Khách hàng bị tạm ngưng vì một lý do nội bộ của Google, ví dụ: lạm dụng.

Giới hạn đối với Pub/Sub

Thứ tự thông báo đẩy không được đảm bảo. Tin nhắn có thể được gửi nhiều lần và trong các tình huống nghiêm trọng, thậm chí không ổn định. Bạn nên sử dụng reseller.subscriptions.get trên mọi gói thuê bao đã thay đổi để lấy trạng thái hiện tại.