取得使用者訂閱

  • 發行項

在 Microsoft Store 購買 API 中使用此方法，取得特定使用者有權使用的訂用帳戶附加元件。

注意

這個方法只能由 Microsoft 佈建的開發人員帳戶使用，才能為通用 Windows 平台 (UWP) 應用程式建立訂用帳戶附加元件。 訂用帳戶附加元件目前不提供大多數開發人員帳戶使用。

Microsoft.StoreServices 程式庫透過 StoreServicesClient.RecurrenceQueryAsync API 提供此方法的功能。

必要條件

若要使用此方法，您將需要：

  • Azure AD 存取權杖，具有對象 URI 值 https://onestore.microsoft.com。
  • Microsoft Store ID 金鑰，代表您要取得其訂用帳戶的使用者身分識別。

如需詳細資訊，請參閱從服務管理產品權利。

要求

要求語法

方法 要求 URI
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query

要求標頭

標題 類型 描述
授權 字串 必要。 持有人<權杖>形式的 Azure AD 存取權杖。
Host 字串 必須設定為值 purchase.mp.microsoft.com。
Content-Length 值 要求本文的長度。
內容-類型 字串 指定要求和回應類型。 目前唯一支援的值是 application/json。

要求本文

參數 類型 描述 必要
b2bKey 字串 Microsoft Store ID 金鑰，代表您要取得其訂用帳戶的使用者身分識別。 是
continuationToken 字串 如果使用者擁有多個訂用帳戶的權利，當達到頁面限制時，回應本文會傳回接續權杖。 在後續呼叫中提供該接續權杖，以擷取剩餘的產品。 否
pageSize 字串 在一個回應中傳回的訂用帳戶數目上限。 預設值為 25。 否

要求範例

下列範例示範如何使用此方法取得指定使用者有權使用的訂用帳戶附加元件。 將 b2bKey 值取代為代表您要取得其訂用帳戶之使用者身分識別的 Microsoft Store ID 金鑰。

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ..."
}

回應

這個方法會傳回 JSON 回應本文，其中包含資料物件的集合，描述使用者有權使用的訂用帳戶附加元件。 下列範例示範具有一個訂用帳戶權利之使用者的回應本文。

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-11T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-08T21:07:51.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

回應本文

此回應本文包含下列資料。

值 類型 描述
項目 陣列 物件的陣列，其中包含指定使用者有權使用之每個訂用帳戶附加元件的相關資料。 如需每個物件中資料的詳細資訊，請參閱下表。

items 陣列中的每個物件都包含下列值。

值 類型 描述
autoRenew 布林值 指出訂用帳戶是否設定為在目前訂用帳戶期間結束時自動更新。
beneficiary 字串 與此訂用帳戶相關聯之權利受益者的識別碼。
expirationTime 字串 訂用帳戶到期的日期和時間，格式為 ISO 8601。 只有在訂用帳戶處於特定狀態時，才能使用此欄位。 到期時間通常表示目前狀態何時到期。 例如，對於作用中的訂用帳戶，到期日會指出下一次自動更新會在何時發生。
expirationTimeWithGrace 字串 訂用帳戶到期的日期和時間，包括 ISO 8601 格式的寬限期。 這個值表示使用者在訂用帳戶無法自動更新之後，何時會失去訂用帳戶的存取權。
id 字串 訂用帳戶的識別碼。 使用此值來指出當您呼叫變更使用者的訂用帳戶計費狀態方法時，想要修改的訂用帳戶。
isTrial 布林值 指出訂用帳戶是否為試用版。
lastModified 字串 上次修改訂閱的日期和時間，格式為 ISO 8601。
market 字串 使用者取得訂用帳戶的國家/地區代碼 (兩個字母的 ISO 3166-1 alpha-2 格式)。
productId 字串 代表 Microsoft Store 目錄中訂用帳戶附加元件之產品的 Store ID。 產品的範例 Store ID 為 9NBLGGH42CFD。
skuId 字串 代表 Microsoft Store 目錄中訂用帳戶附加元件之 SKU 的 Store ID。 SKU 的範例 Store ID 為 0010。
startTime 字串 訂閱的開始日期和時間，格式為 ISO 8601。
recurrenceState 字串 下列其中一個值：
  • None：這表示永久訂用帳戶。
  • Active：訂用帳戶為作用中，且使用者有權使用服務。
  • Inactive：訂用帳戶已超過到期日，且使用者已關閉訂用帳戶的自動更新選項。
  • Canceled：訂用帳戶在到期日之前在有無退款下特意終止。
  • InDunning：訂用帳戶處於「催繳」狀態 (也就是訂用帳戶即將到期，而 Microsoft 正嘗試取得資金以自動更新訂用帳戶)。
  • Failed：催繳期間已結束，訂用帳戶在多次嘗試之後無法續約。

注意：

  • Inactive/Canceled/Failed 是末期狀態。 當訂用帳戶進入其中一個狀態時，使用者必須重新購買訂用帳戶，才能再次啟用訂閱。 使用者在這些狀態下無權使用服務。
  • 當訂用帳戶為 Canceled 時，expirationTime 會以取消的日期和時間進行更新。
  • 訂用帳戶的識別碼在整個存留期內會維持不變。 如果自動更新選項已開啟或關閉，則不會變更。 如果使用者在達到末期狀態之後重新購買訂用帳戶，將會建立新的訂用帳戶識別碼。
  • 應將訂用帳戶的識別碼用在個別訂用帳戶上執行任何作業。
  • 當使用者在取消或停止之後重新購買訂用帳戶時，如果您查詢使用者的結果，您會收到兩個項目：一個是處於末期狀態的舊訂用帳戶識別碼，另一個是處於作用中狀態的新訂用帳戶識別碼。
  • 檢查 recurrenceState 和 expirationTime 向來是個不錯的做法，因為 recurrenceState 可能會延遲幾分鐘 (或偶爾數小時) 更新。
cancellationDate 字串 取消使用者的訂閱日期和時間 (ISO 8601 格式)。