管理 SaaS 產品的客戶授權

當客戶針對您的軟體選擇定價方案時，Google 會建立「授權」，藉此表示客戶已透過 Cloud Marketplace 購買您的產品。本節將回顧如何使用 Partner Procurement API，為客戶建立及管理授權。

如要進一步瞭解如何管理授權，請參閱參考文件。

事前準備

  • 按照 整合應用程式一文的說明，設定 Cloud Commerce Partner Procurement API 的存取權。

如果已啟用相同產品的多個訂單，Partner Procurement API 可以針對相同的 ACCOUNT_ID 值傳送多個事件類型為 ENTITLEMENT_ACTIVE 的事件，每個事件都有代表不同方案的專屬 ENTITLEMENT_ID。也就是說，您必須確保應用程式的事件處理邏輯可以回應 ENTITLEMENT_ID，而不是 ACCOUNT_ID 或 PRODUCT_ID。

請務必確保前端整合功能可以處理 JWT 酬載中包含的新 orders 物件。詳情請參閱「整合應用程式前端」。

如要進一步瞭解如何啟用相同產品的多筆訂單，請參閱「啟用相同產品的多筆訂單」。

核准授權

當客戶選擇定價方案時，Cloud Marketplace 會建立授權，並將下列 Pub/Sub 訊息傳送至您的應用程式：

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
    "newPendingOfferDuration": "P2Y3M",   // Contract duration for offer-based entitlements
  },
}

其中 ENTITLEMENT_ID 是由 Cloud Marketplace 建立的 ID。 如果優惠有指定期限，期限會以年和月為單位提供。如果優惠有指定結束日期，而非指定時間長度，則表示時間長度的欄位會留空。

請在您的系統中將使用者帳戶更新為已選取方案的狀態。接著，如要核准授權，請向 Partner Procurement API 提出 HTTP POST 要求，並傳送您要核准的 ENTITLEMENT_ID：

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

拒絕授權

如要拒絕授權，請向 Partner Procurement API 發出 HTTP POST 要求，並在要求中使用 reject 方法：

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject

如要在要求主體中提供拒絕授權的原因，請使用下列格式：

{
  "reason": "..."
}

變更授權方案

取決於您對定價方案的設定方式，您的客戶或許能夠變更自己選擇的方案。當客戶選擇新的定價方案時，您會收到格式如下的 Pub/Sub 訊息：

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPendingPlan": "ultimate",   // New plan
    "updateTime": "...",
    "newPendingOfferDuration": "P2Y3M",   // Contract duration for the new offer, for offer-based entitlements
    "newProduct": "test-product.cloud.goog"
    "newPendingOffer": "projects/1234567/services/test-product.cloud.goog/standardOffers/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  },
}

如果優惠有指定期限，期限會以年和月為單位提供。如果優惠有指定結束日期，而非指定時間長度，則表示時間長度的欄位會留空。

如要核准方案變更，請向 Partner Procurement API 提出下列 HTTP POST 要求：

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

要求主體必須包含核准的方案：

{
  "pendingPlanName": PLAN_NAME
}

核准變更後，您會在變更生效時收到另一則 Pub/Sub 訊息，訊息中的 eventType 欄位會變更為 ENTITLEMENT_PLAN_CHANGED。如要檢查方案狀態，請向 Partner Procurement API 提出下列 HTTP GET 要求。

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

您會收到內容如下的回應，其中的 state 欄位表示新方案是否已開始生效，或者方案變更是否仍在處理中：

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

取消授權

如果使用者決定取消自身的授權，您會收到 Pub/Sub 通知。與方案變更流程類似，系統可能會在目前的帳單週期結束時才將方案確實取消。

通知的格式如下：

{
  "eventId": "...",
  // If the entitlement is canceled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "..."
  },
}

刪除授權

如果使用者直接向 Google 支援團隊提出要求，或者不再採用 Google 平台，系統會立即取消授權，並在 60 天的寬限期過後刪除授權和帳戶。為保護使用者的隱私權，您必須在收到通知時將他們的資料從伺服器中刪除。

系統會在取消授權及刪除帳戶時向您傳送通知，內容如下：

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
 
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

授權狀態轉換

下表說明權利在不同事件發生時的狀態轉換情形。

目前情況 觸發事件 新州 附註
(無) ENTITLEMENT_CREATION_REQUESTED ENTITLEMENT_ACTIVATION_REQUESTED 顧客選取方案。
ENTITLEMENT_ACTIVATION_REQUESTED 供應商核准授權 ENTITLEMENT_ACTIVE 授權生效。
ENTITLEMENT_ACTIVATION_REQUESTED 供應商拒絕授權 ENTITLEMENT_CANCELLED 系統不會建立授權。
ENTITLEMENT_ACTIVE ENTITLEMENT_PLAN_CHANGE_REQUESTED ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL或ENTITLEMENT_PENDING_PLAN_CHANGE 顧客要求變更方案。
ENTITLEMENT_ACTIVE ENTITLEMENT_CANCELLING ENTITLEMENT_PENDING_CANCELLATION 客戶取消方案，取消會在當期結束時生效。
ENTITLEMENT_ACTIVE ENTITLEMENT_CANCELLED ENTITLEMENT_CANCELLED 客戶立即取消方案。
ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL 供應商核准方案變更 ENTITLEMENT_PENDING_PLAN_CHANGE或ENTITLEMENT_ACTIVE 如果目前的方案必須完成帳單週期，就會進入待處理狀態。否則會啟用。
ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL 供應商拒絕變更方案 ENTITLEMENT_ACTIVE 授權會還原為舊方案。
ENTITLEMENT_PENDING_PLAN_CHANGE ENTITLEMENT_PLAN_CHANGED ENTITLEMENT_ACTIVE 帳單週期結束，新方案生效。
ENTITLEMENT_PENDING_PLAN_CHANGE ENTITLEMENT_OFFER_ENDED，然後是 ENTITLEMENT_PLAN_CHANGED ENTITLEMENT_PENDING_CANCELLATION 客戶接受私密優惠，導致方案變更，且轉換生效。
ENTITLEMENT_PENDING_CANCELLATION ENTITLEMENT_CANCELLED ENTITLEMENT_CANCELLED 帳單週期結束，權益完全取消。
ENTITLEMENT_PENDING_CANCELLATION ENTITLEMENT_CANCELLATION_REVERTED ENTITLEMENT_ACTIVE 顧客已取消待處理的取消要求。

帳戶工作事件類型清單

以下列出應用程式可能會在 Pub/Sub 訊息中收到的 eventType：

eventType說明
ACCOUNT_CREATION_REQUESTED已淘汰
ACCOUNT_ACTIVE表示已建立客戶帳戶。
ACCOUNT_DELETED表示客戶的帳戶已從 Google Cloud 系統中刪除。
ENTITLEMENT_CREATION_REQUESTED表示顧客已選取其中一個定價方案。
ENTITLEMENT_OFFER_ACCEPTED表示顧客已接受優惠。如果有的話，也會包含優惠的排定開始時間。這項事件會針對私密優惠和標準優惠 (公開購買) 傳送。
ENTITLEMENT_ACTIVE表示客戶選擇的方案現已啟用。
ENTITLEMENT_PLAN_CHANGE_REQUESTED表示顧客選擇了新方案。
ENTITLEMENT_PLAN_CHANGED表示客戶的方案變更已獲准，且變更已生效。
ENTITLEMENT_PLAN_CHANGE_CANCELLED表示客戶的方案變更已取消，可能是因為未獲核准，或是客戶改回舊方案。
ENTITLEMENT_PENDING_CANCELLATION表示客戶已取消方案，但系統會在帳單週期結束時才取消。如果客戶接受私密優惠而變更方案，也適用此狀態。收到事件 ENTITLEMENT_PLAN_CHANGE_REQUESTED 和 ENTITLEMENT_OFFER_ENDED 後，當收到事件 ENTITLEMENT_PLAN_CHANGED 時，授權會處於這個狀態。
ENTITLEMENT_CANCELLATION_REVERTED表示客戶的待處理取消要求已還原。請注意，取消作業一經完成即無法復原。
ENTITLEMENT_CANCELLED表示客戶已取消方案。
ENTITLEMENT_CANCELLING表示客戶的方案正在取消中。
ENTITLEMENT_RENEWED表示客戶的授權已續約。你不需要採取任何行動，系統就會自動續訂。
ENTITLEMENT_OFFER_ENDED表示顧客的私密優惠已結束。如果取消顧客的授權，系統會觸發個別的 ENTITLEMENT_CANCELLED 事件。如果客戶的權益仍有效，方案價格會恢復為未折扣的價格。
ENTITLEMENT_DELETED表示系統已從 Cloud Marketplace 刪除客戶方案的相關資訊。
上一頁
管理使用者帳戶