REST Resource: subscriptions

資源：訂閱

訂閱項目的 JSON 範本。

JSON 表示法 
{
  "customerId": string,
  "subscriptionId": string,
  "skuId": string,
  "creationTime": string,
  "kind": string,
  "seats": {
    object (Seats)
  },
  "renewalSettings": {
    object (RenewalSettings)
  },
  "purchaseOrderId": string,
  "status": string,
  "resourceUiUrl": string,
  "billingMethod": string,
  "suspensionReasons": [
    string
  ],
  "customerDomain": string,
  "dealCode": string,
  "skuName": string,
  "plan": {
    "planName": string,
    "isCommitmentPlan": boolean,
    "commitmentInterval": {
      "startTime": string,
      "endTime": string
    }
  },
  "trialSettings": {
    "isInTrial": boolean,
    "trialEndTime": string
  },
  "transferInfo": {
    "transferabilityExpirationTime": string,
    "minimumTransferableSeats": integer,
    "currentLegacySkuId": string
  }
}
欄位
customerId

string

系統一律會在回應中傳回這個屬性，做為 Google 產生的專屬 ID。在要求中，這項資源可以是主網域或 Google 產生的專屬 ID。
subscriptionId

string

subscriptionId 是訂閱項目 ID，為每個客戶提供的專屬 ID。這是必要屬性。由於 subscriptionId 會在訂閱更新時變更，因此建議您不要使用這組 ID 做為永久資料的金鑰。使用擷取所有經銷商訂閱項目中所述的 subscriptionId。
skuId

string

必要屬性。skuId 是指派給產品中客戶產品的 SKU 專屬系統 ID。如要瞭解這個 API 版本提供的產品和 SKU，請參閱「產品與 SKU ID」。
creationTime

string (int64 format)

creationTime 屬性是建立訂閱項目的日期。以毫秒為單位使用 Epoch 格式表示。請參閱 Epoch 轉換工具範例。
kind

string

將資源識別為訂閱項目。值：reseller#subscription
seats

object (Seats)

這是必要屬性。方案中使用者名額授權數量和限制。
renewalSettings

object (RenewalSettings)

年約方案的續約設定。如需瞭解詳情，請前往管理員說明中心查看續約選項。
purchaseOrderId

string

這是選用屬性。這份訂購單 (PO) 資訊可供經銷商用於追蹤公司使用情形。指定 purchaseOrderId 值後，就會顯示在 API 回應中，並顯示在月結單中。屬性可接受最多 80 個純文字字元。
status

string

這是選用屬性。
resourceUiUrl

string

管理控制台中「訂閱」頁面的網址。唯讀網址是由 API 服務產生。如果您的客戶應用程式需要使用管理控制台中的「訂閱」頁面來完成工作，就會使用這個選項。
billingMethod

string

唯讀欄位，用於傳回訂閱項目目前的付款方式。
suspensionReasons[]

string

唯讀欄位，當中含有訂閱項目目前所有停權原因的列舉。訂閱項目的並行原因可能有很多、重疊。訂閱STATUS為SUSPENDED，直到所有暫停訂閱狀態移除為止。

可能的選項包括：

  • PENDING_TOS_ACCEPTANCE - 客戶尚未登入並接受 G Suite 經銷商服務條款。
  • RENEWAL_WITH_TYPE_CANCEL - 客戶的承諾已終止，且服務在約期結束時取消。
  • RESELLER_INITIATED - 由經銷商叫用的手動停權處分。
  • TRIAL_ENDED - 客戶的試用期已結束，且未選擇任何方案。
  • OTHER - 客戶因內部 Google 原因 (例如濫用或以其他方式) 遭到停權。
customerDomain

string

客戶的主網域名稱
dealCode

string

Google 針對訂閱方案提供折扣價格的代碼 (最多 100 個字元)。優惠代碼必須包含在 insert 要求中，才能享有折扣費率。這個屬性是選填項目，如果留空，則須套用一般價格。
skuName

string

訂閱中客戶指派給產品 SKU 的唯讀外部顯示名稱。Google 可自行斟酌變更 SKU 名稱。如要瞭解這個 API 版本提供的產品和 SKU，請參閱「產品與 SKU ID」。
plan

object

必須提供 plan 屬性。這個版本的 API 是彈性方案、年約方案和 30 天免費試用方案。如要進一步瞭解 API 的付款方案，請參閱 API 概念。
plan.planName

string

必須提供 planName 屬性。這是訂閱項目的方案名稱。如要進一步瞭解 Google 付款方案，請參閱 API 概念。

可能的值包括：

  • ANNUAL_MONTHLY_PAY：按月付款的年約方案。
  • ANNUAL_YEARLY_PAY：年約方案 (按年付款)
  • FLEXIBLE - 彈性方案
  • TRIAL：30 天的免費試用期方案。如未指派付款方案，免費試用訂閲項目在 30 天後就會暫停。呼叫 changePlan 後，系統會將付款方案指派給試用方案，但不會啟用該方案。免費試用期將在 30 天過後，或直接撥打 startPaidService 後自動開始指定的付款方案。
  • FREE：這項免費方案僅適用於 Cloud Identity SKU，不產生任何帳單費用。
plan.isCommitmentPlan

boolean

isCommitmentPlan 屬性的布林值會表示年約方案為年約方案：

  • true：訂閱是年約方案。
  • false：此方案並非年約方案。
plan.commitmentInterval

object

在這個版本的 API 中，每年的承諾使用方案為一年。
plan.commitmentInterval.startTime

string (int64 format)

使用 UNIX Epoch 紀元格式的年約方案承諾使用價格 (以毫秒為單位) startTime。請參閱 Epoch 轉換工具範例。
plan.commitmentInterval.endTime

string (int64 format)

使用 UNIX Epoch 紀元格式的年度承諾使用合約 (以毫秒為單位) endTime。請參閱 Epoch 轉換工具範例。
trialSettings

object

G Suite 年約方案 (彈性方案) 和彈性付款方案皆可申請 30 天。詳情請參閱 API 概念。
trialSettings.isInTrial

boolean

決定訂閱項目是否處於 30 天的免費試用期：

  • true — 這個方案目前為試用期。
  • false — 這個方案尚未結束。
trialSettings.trialEndTime

string (int64 format)

試用期的結束日期。這個值以 UNIX Epoch 紀元格式表示 (以毫秒為單位)。請參閱 Epoch 轉換工具範例。
transferInfo

object

訂閱項目的唯讀轉移相關資訊。詳情請參閱為客戶擷取可轉移的訂閱。
transferInfo.transferabilityExpirationTime

string (int64 format)

轉移權杖或轉移意圖的到期時間。使用 UNIX Epoch 紀元格式的時間 (以毫秒為單位)。
transferInfo.minimumTransferableSeats

integer

插入訂閱項目時，這是指這項產品的訂購單中所列的帳戶名額下限。舉例來說，如果客戶有 20 位使用者，經銷商最多只能訂購 15 個帳戶名額。至少要有 20 個帳戶名額。
transferInfo.currentLegacySkuId

string

目前經銷的 skuId。只有在客戶使用舊版 SKU 的訂閱，且訂閱資源填入了建議轉移的 SKU 的 skuId 時，系統才會填入這項設定。

座位數

訂閱座位的 JSON 範本。

JSON 表示法 
{
  "numberOfSeats": integer,
  "maximumNumberOfSeats": integer,
  "licensedNumberOfSeats": integer,
  "kind": string
}
欄位
numberOfSeats

integer

此為必要屬性，僅適用於設有 ANNUAL_MONTHLY_PAY 和 ANNUAL_YEARLY_PAY 方案的訂閱項目。這項資源會設定可指派給使用者訂閱的授權數量上限。經銷商可以新增更多授權，但設定完畢後，numberOfSeats 就無法續約。無論指派多少使用者授權，經銷商都會根據 numberOfSeats 的值開立發票。
maximumNumberOfSeats

integer

這是選用屬性，僅適用於訂閱「FLEXIBLE」或「TRIAL」方案的訂閱項目。這項資源會設定訂閱數量上限的授權使用者。您可以將這個數量調高至經銷商合約中定義的上限。最低數量是指客戶帳戶中的目前使用者人數。
licensedNumberOfSeats

integer

唯讀欄位，包含目前指派給 skuId 產品中授權的使用者人數。這個欄位的值相當於 Enterprise License Manager API 方法傳回的使用者數量：listForProductAndSku。
kind

string

將資源視為訂閱座椅設定。值：subscriptions#seats

RenewalSettings

訂閱續約設定的 JSON 範本。

JSON 表示法 
{
  "renewalType": string,
  "kind": string
}
欄位
renewalType

string

年約方案的續約設定。如需瞭解詳情，請前往管理員說明中心查看續約選項。續訂時，renewalType 為必要屬性。
kind

string

標識資源訂閱設定。值：subscriptions#renewalSettings

方法

activate

 啟用經銷商先前遭到停權的訂閱。

changePlan

 更新訂閱方案。

changeRenewalSettings

 更新使用者的授權設定。

changeSeats

 更新訂閱項目的使用者授權設定。

delete

 取消、暫停或將訂閱轉移給直接客戶。

get

 取得特定訂閱項目。

insert

 建立或轉移訂閱。

list

 轉移至經銷商管理的訂閱清單。

startPaidService

 立即將 30 天的免費試用訂閱轉換為付費服務訂閱。

suspend

 可將有效的訂閱停權。