获取用户订阅

在 Microsoft Store 购买 API 中使用此方法来获取给定用户有权使用的订阅加载项。

注意

此方法仅供已由 Microsoft 预配能够为通用 Windows 平台 (UWP) 应用创建订阅加载项的开发人员帐户使用。 对于大多数开发人员帐户来说，订阅加载项目前尚不可用。

Microsoft.StoreServices 库通过 StoreServicesClient.RecurrenceQueryAsync API 提供此方法的功能。

先决条件

若要使用此方法，你需要：

• 受众 URI 值为 https://onestore.microsoft.com 的 Azure AD 访问令牌。
• 一个 Microsoft Store ID 密钥，表示要获得其订阅的用户的身份。

有关详细信息，请参阅管理来自服务的产品授权。

请求

请求语法

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

请求头

标头	类型	说明
授权	字符串	必需。 Azure AD 访问令牌的格式为 Bearertoken<>。
主机	string	必须设置为值 purchase.mp.microsoft.com。
Content-Length	数值	请求正文的长度。
Content-Type	字符串	指定请求和响应类型。 当前，唯一受支持的值为 application/json。

请求正文

参数	类型	描述	必须
b2bKey	string	Microsoft Store ID 密钥，表示要获取其订阅的用户的身份。	是
continuationToken	string	如果用户具有多个订阅的权利，则在达到页面限制时，响应正文将会返回一个延续令牌。 在后续调用中提供此处的延续令牌以检索剩余产品。	否
pageSize	string	要在一次响应中返回的最大订阅数。 默认值为 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"
    }
  ]
}

响应正文

响应正文包含以下数据。

Value	类型	描述
items	array	对象数组，包含指定用户有权使用的每个订阅加载项的数据。 有关每个对象中的数据的详细信息，请参阅下表。

items 数组中的每个对象包含以下值。

值	类型	说明
autoRenew	布尔	表示是否已将订阅配置为在当前订阅期结束时自动续订。
受益人	string	与此订阅关联的权利受益人的 ID。
expirationTime	string	订阅截止日期和时间（ISO 8601 格式）。 仅当订阅处于特定状态时，此字段才可用。 截止时间通常表示当前状态截止的时间。 例如，对于活动的订阅，截止日期表示下一次自动续订发生的时间。
expirationTimeWithGrace	string	订阅到期的日期和时间，包括宽限期（采用 ISO 8601 格式）。 此值指示订阅未能自动续订后用户何时将失去订阅的访问权限。
id	string	订阅 ID。 使用此方法表示在你调用更改用户订阅的计费状态方法时想要修改的订阅。
isTrial	布尔	表示订阅是否为试用版。
lastModified	string	上次修改订阅的日期和时间（ISO 8601 格式）。
market	string	用户在其中获取订阅的国家/地区代码（两个字母 ISO 3166-1 alpha-2 格式）。
productId	string	表示 Microsoft Store 目录中的订阅加载项的产品的 Store ID。 产品的示例应用商店 ID 为 9NBLGGH42CFD。
skuId	string	表示 Microsoft Store 目录中的订阅加载项的 SKU 的 Store ID。 SKU 的示例应用商店 ID 为 0010。
startTime	string	订阅的开始日期和时间（ISO 8601 格式）。
recurrenceState	string	以下值之一： None：这指示永久订阅。 Active：订阅有效且用户有权使用服务。 Inactive：订阅已过期，并且用户已关闭订阅的自动续订选项。 Canceled：订阅已在截止日期之前被故意终止，提供或不提供退款。 InDunning：订阅正处于“催缴”状态（即，订阅即将过期，且 Microsoft 正尝试获取款项以自动续订此订阅）。 Failed：催缴期已结束，并且在多次尝试后仍无法续订此订阅。 注意： Inactive/Canceled/Failed 为终端状态。 当订阅处于这些状态之一时，用户必须重新购买订阅才能再次激活订阅。 在这些状态下，用户无权使用服务。 当订阅处于 Canceled 状态时，expirationTime 将会更新为取消的日期和时间。 在整个生命周期中，订阅 ID 将保持相同。 打开或关闭自动续订选项并不会更改订阅 ID。 如果用户在达到终端状态之后重新购买了订阅，则会创建新的订阅 ID。 订阅 ID 可用于在单个订阅上执行任何操作。 当用户在取消或中断订阅之后重新购买了订阅时，如果查询该用户的结果，则你将会获得两个条目：一个处于终端状态的旧订阅 ID 和一个处于活动状态的新订阅 ID。 最好始终检查 recurrenceState 和 expirationTime，因为更新至 recurrenceState 可能会延迟几分钟（有时候会是几小时）。
cancellationDate	string	用户订阅取消的日期和时间（ISO 8601 格式）。

相关主题

• 管理来自服务的产品授权
• 更改用户订阅的计费状态
• 查询产品
• 将可消费产品报告为已完成。
• 续订 Microsoft Store ID 密钥
• Microsoft.StoreServices 库 (GitHub)