取得使用者的訂用帳戶

2025-06-10

在Microsoft市集購買 API 中使用這個方法，取得指定使用者有權使用的訂用帳戶附加元件。

備註

這個方法只能由經 Microsoft 設定的開發人員帳戶使用，這些帳戶可以為通用 Windows 平台 (UWP) 應用程式建立訂閱附加元件。訂用帳戶附加元件目前不適用於大多數開發人員帳戶。

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

先決條件

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

具備受眾 URI 值 https://onestore.microsoft.com的 Azure AD 存取令牌。
Microsoft Store 識別符密鑰，代表您想要取得其訂用帳戶的使用者身分識別。

如需詳細資料，請參閱從服務中管理產品使用權。

請求

請求語法

方法	請求網址識別碼 (URI)
郵件	`https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query`

請求標頭

頁首	類型	說明
授權	字符串	必須的。 Azure AD 存取令牌的形式為 Bearer<token>。
主辦人	字符串	必須設定為 purchase.mp.microsoft.com的值。
內容長度	數字	請求正文的長度。
內容-類型	字符串	指定要求和回應類型。目前，唯一支援的值是 application/json。

請求主體

參數	類型	說明	為必填項目
b2bKey	字符串	Microsoft市集標識符金鑰，代表您想要取得其訂用帳戶的使用者身分識別。	是的
延續標記	字符串	如果用戶擁有多個訂閱的權限，當達到頁面限制時，回應內容會傳回接續令牌。請在後續呼叫中提供續傳標記，以檢索剩餘的產品。	否
頁面大小	字符串	單一回應中所能返回的最大訂閱數量。預設值為 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"
    }
  ]
}

回應主體

回應內容包含下列資料。

價值觀	類型	說明
項目	陣列	指定使用者有權使用的每個訂閱附加元件的資料物件陣列。如需每個物件中數據的詳細資訊，請參閱下表。

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

價值觀	類型	說明
自動續訂	布爾邏輯	指出訂用帳戶是否設定為在目前訂閱期間結束時自動更新。
受益人	字符串	與此訂閱相關聯之權利受益者的識別碼。
到期時間	字符串	訂閱到期的日期和時間，格式為 ISO 8601。只有在訂用帳戶處於特定狀態時，才能使用此欄位。到期時間通常表示目前狀態何時到期。例如，對於使用中的訂用帳戶，到期日會指出何時會發生下一次自動更新。
有寬限的過期時間	字符串	訂閱到期的日期和時間，包括寬限期，以 ISO 8601 格式顯示。這個值表示使用者在訂用帳戶無法自動更新之後，何時會失去訂用帳戶的存取權。
識別碼	字符串	訂用帳戶的標識碼。在您呼叫使用者訂用帳戶方法以變更計費狀態時，使用此值來指出您想要修改的訂用帳戶。
isTrial	布爾邏輯	指出訂閱是否為試用版。
上次修改	字符串	上次修改訂閱的日期和時間，格式為 ISO 8601。
市場	字符串	使用者取得訂閱的國家代碼（ISO 3166-1 alpha-2 格式，兩個字母）。
產品ID	字符串	產品市集標識碼，代表 Microsoft Store 目錄中的訂閱附加元件。產品的市集標識碼範例為 9NBLGGH42CFD。
skuId 的	字符串	代表 Microsoft 市集目錄中訂閱附加元件的 SKU 的市集標識碼。 SKU 的市集標識碼範例為 0010。
開始時間	字符串	訂閱的開始日期和時間，格式為 ISO 8601。
重複狀態	字符串	下列其中一個值： None：這表示永久訂閱。有效：訂閱是有效的，且使用者有權使用服務。非使用中：訂用帳戶超過到期日，而使用者已關閉訂閱的自動更新選項。取消：訂閱在到期日之前已故意終止，且不需退款。 InDunning：訂用帳戶（也就是訂用帳戶即將到期，Microsoft嘗試取得資金以自動更新訂閱）。失敗：催收期間已結束，訂閱在多次嘗試後無法續約。注意：非使用中/已取消/失敗為終端機狀態。當訂用帳戶進入其中一個狀態時，用戶必須重新購買訂用帳戶，才能再次啟用訂閱。用戶無權使用這些狀態中的服務。當訂用帳戶被取消時，到期時間將會更新為取消的日期和時間。訂用帳戶的標識碼在整個存留期內會維持不變。如果自動續約選項已開啟或關閉，則不會變更。如果使用者在達到終端機狀態之後重新購買訂用帳戶，將會建立新的訂用帳戶標識碼。訂用帳戶的標識碼應該用來在個別訂用帳戶上執行任何作業。當使用者在取消或停止訂閱之後重新購買訂閱時，如果您查詢該用戶的結果，您會得到兩個條目：一個是處於終止狀態的舊訂閱 ID，另一個是處於活躍狀態的新訂閱 ID。檢查 recurrenceState 和 expirationTime 始終是個好習慣，因為 recurrenceState 的更新仍可能會延遲幾分鐘（或偶爾數小時）。
取消日期	字符串	以 ISO 8601 格式取消使用者的訂閱日期和時間。

共用方式為