管理 SaaS 產品的客戶授權

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

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

事前準備

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

如果您為同一件商品啟用多個訂單，合作夥伴採購 API 可以傳送多個事件，其中事件類型為 ENTITLEMENT_ACTIVE，ACCOUNT_ID 值相同，每個事件都有代表不同商品的獨特 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": "...",
    "newOfferDuration": "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",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for the new offer, for offer-based entitlements
    "newProduct": "test-product.cloud.goog"
    "newOffer": "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": "...",
  },
}

帳戶工作事件類型清單

以下列出應用程式可能會在 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_CANCELLATION_REVERTED表示客戶的待處理取消訂單已撤銷。請注意，取消訂單後即無法復原。
ENTITLEMENT_CANCELLED表示客戶的方案已取消。
ENTITLEMENT_CANCELLING表示客戶的方案正在取消中。
ENTITLEMENT_RENEWED表示客戶的授權已延長一段時間。您不需要採取任何行動即可完成續約。
ENTITLEMENT_OFFER_ENDED表示客戶的私密優惠已結束。如果客戶的授權遭到取消，系統會觸發另一個 ENTITLEMENT_CANCELLED 事件。如果客戶的授權仍有效，則方案會恢復為非折扣價格。
ENTITLEMENT_DELETED表示客戶方案的相關資訊已從 Cloud Marketplace 中刪除。
上一頁
管理使用者帳戶