管理来自服务的产品授权

如果你有应用和加载项的目录，你可以使用 Microsoft Store 收集 API 和 Microsoft Store 购买 API 访问你的服务中的这些产品的权益信息。 权益表示客户使用通过 Microsoft Store 发布的应用或加载项的权利。

这些 API 由 REST 方法组合而成，旨在供开发人员用于跨平台服务支持的加载项目录。 这些 API 支持你执行以下操作：

• Microsoft Store 收集 API：查询用户拥有的产品和将可消费产品报告为已完成。
• Microsoft Store 购买 API：向用户授予免费产品、获取用户订阅和更改用户订阅的计费状态。

注意

Microsoft Store 收集 API 和购买 API 使用 Azure Active Directory (Azure AD) 身份验证访问客户所有权信息。 要使用这些 API，你（或你的组织）必须具有 Azure AD 目录，并且你必须具有该目录的全局管理员权限。 如果你已使用 Microsoft 365 或 Microsoft 的其他业务服务，表示你已经具有 Azure AD 目录。

Microsoft.StoreServices 库

若要帮助简化身份验证流和调用 Microsoft Store 服务，请查看 Github 上的 Microsoft.StoreServices 项目和示例。 Microsoft.StoreServices 库可帮助你管理身份验证密钥，并提供包装器 API 来调用用于管理产品的 Microsoft Store 服务。 示例项目重点介绍了服务如何使用 Microsoft.StoreServices 库、用于管理消耗品的示例逻辑、核对已退款商品、续订已过期的凭据，等等。 示例随附了分步配置指南，介绍如何在电脑上或通过 Azure 设置示例服务。

• Microsoft.StoreServices 库 (GitHub)
• Microsoft.StoreServices 示例 (GitHub)

概述

以下步骤介绍了使用 Microsoft Store 收集 API 和购买 API 的端到端过程：

1. 在 Azure AD 中配置应用程序。
2. 在合作伙伴中心将你的 Azure AD 应用程序 ID 与应用相关联。
3. 在你的服务中，创建 Azure AD 访问令牌，这些令牌表示你的发布者标识。
4. 在客户端 Windows 应用中，创建一个 Microsoft Store ID 密钥表示当前用户的标识，并将此密钥传回到服务。

此端到端过程涉及到两个执行不同任务的软件组件：

• 你的服务。 这是一个在你业务环境上下文中安全运行的应用程序，可以使用你选择的任何开发平台来实现它。 你的服务负责创建方案所需的 Azure AD 访问令牌，并调用 Microsoft Store 收集 API 和购买 API 的 REST URI。
• 你的客户端 Windows 应用。 这是你要访问和管理其客户权利信息的应用（包括该应用的加载项）。 此应用负责创建所需的 Microsoft Store ID 密钥，以便能够从服务调用 Microsoft Store 收集 API 和购买 API。

步骤 1：在 Azure AD 中配置应用程序

必须先创建一个 Azure AD Web 应用程序，检索应用程序的租户 ID 和应用程序 ID 并生成一个密钥，然后才能使用 Microsoft Store 收集 API 或购买 API。 该 Azure AD Web 应用程序表示你要从中调用 Microsoft Store 收集 API 或购买 API 的服务。 需要使用该租户 ID、应用程序 ID 和密钥来生成调用 API 时所需的 Azure AD 访问令牌。

1. 按照将应用程序与 Azure Active Directory 集成中的说明将一个 Web 应用/API 应用程序注册到 Azure AD（如果尚未这样做）。

   注意

   注册应用程序时，必须选择“Web 应用/API”作为应用程序类型，以便可以检索应用程序的密钥（也称为客户端机密）。 若要调用 Microsoft Store 收集 API 或购买 API，必须在稍后步骤从 Azure AD 中请求访问令牌时提供客户端密码。

2. 在 Azure 管理门户中，导航到“Azure Active Directory”。 选择你的目录，在左侧导航窗格中单击“应用注册”，然后选择你的应用程序。

3. 随后你将转到该应用程序的注册主页。 在此页上，复制“应用程序 ID”值供稍后使用。

4. 创建一个稍后需要用到的密钥（称为客户端机密）。 在左侧窗格中，依次单击“设置”、“密钥”。 在此页上，完成创建密钥的步骤。 复制此密钥供稍后使用。

步骤 2：在合作伙伴中心将你的 Azure AD 应用程序 ID 与客户端应用相关联

必须先在合作伙伴中心将你的 Azure AD 应用程序 ID 与应用（或包含加载项的应用）相关联，然后才能使用 Microsoft Store 收集 API 或购买 API 来配置该应用或加载项的所有权和购买。

注意

你只需执行一次此任务。 获取租户 ID、应用程序 ID 和客户端机密后，每当需要创建新的 Azure AD 访问令牌时，都可以重复使用这些值。

1. 登录到合作伙伴中心并选择你的应用。
2. 转到“服务”>“产品收集和购买”页，然后在提供的“客户端 ID”字段之一中输入你的 Azure AD 应用程序 ID。

第 3 步：创建 Azure AD 访问令牌

你的服务必须先创建几个不同的表示你的发布者标识的 Azure AD 访问令牌，然后你才能检索 Microsoft Store ID 密钥或调用 Microsoft Store 收集 API 或购买 API。 每个令牌将与不同的 API 一起使用。 每个令牌的生命周期为 60 分钟，你可以在它们到期后进行刷新。

重要

仅在服务的上下文而非应用中创建 Azure AD 访问令牌。 客户端密码在发送到你的应用时可能会遭泄露。

了解不同的令牌和受众 URI

根据你希望在 Microsoft Store 收集 API 或购买 API 中调用的方法，你必须创建两个或三个不同的令牌。 每个访问令牌与不同的受众 URI 相关联。

• 在所有情况下，你都必须使用 https://onestore.microsoft.com 受众 URI 创建令牌。 在稍后的步骤中，你要将此令牌传递到 Microsoft Store 收集 API 或购买 API 中的方法的授权标题。

  重要

  将 https://onestore.microsoft.com 受众仅与安全存储在服务中的访问令牌一起使用。 在服务之外公开访问令牌和此受众会让你的服务易受到重播攻击。

• 如果你想要在 Microsoft Store 收集 API 中调用某个方法以查询用户拥有的产品或将可消费产品报告为已完成，则还必须使用 https://onestore.microsoft.com/b2b/keys/create/collections 受众 URI 创建令牌。 在稍后的步骤中，你要将此令牌传递到 Windows SDK 中的客户端方法，以请求可与 Microsoft Store 收集 API 一起使用的 Microsoft Store ID 密钥。

• 如果你想要调用 Microsoft Store 购买 API 中的方法来向用户授予免费产品、获取用户订阅或更改用户订阅的计费状态，则必须使用 https://onestore.microsoft.com/b2b/keys/create/purchase 受众 URI 创建一个令牌。 在稍后的步骤中，你要将此令牌传递到 Windows SDK 中的客户端方法，以请求可与 Microsoft Store 购买 API 一起使用的 Microsoft Store ID 密钥。

创建令牌

若要创建访问令牌，请按照使用客户端凭据的服务到服务调用中的说明在服务中使用 OAuth 2.0 API，以便将 HTTP POST 发送到 https://login.microsoftonline.com/<tenant_id>/oauth2/token 终结点。 示例请求如下所示。

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://onestore.microsoft.com

对于每个令牌，请指定以下参数数据：

• 对于 client_id 和 client_secret 参数，请指定应用程序的应用程序 ID 和客户端机密（前面已从 Azure 管理门户中检索到这些值）。 若要创建带有 Microsoft Store 收集 API 或购买 API 所需的身份验证级别的访问令牌，这两个参数都是必需的。

• 对于资源参数，请指定上一节中列出的受众 URI 之一，具体取决于要创建的访问令牌的类型。

在你的访问令牌到期后，你可按照此处的说明刷新令牌。 有关访问令牌的结构的更多详细信息，请参阅支持的令牌和声明类型。

第 4 步：创建 Microsoft Store ID 密钥

你的应用必须先创建 Microsoft Store ID 密钥并将其发送给服务，然后你才能调用 Microsoft Store 收集 API 或购买 API 中的任何方法。 此密钥是 JSON Web 令牌 (JWT)，表示你想要访问其产品所有权信息的用户的标识。 有关此密钥中的声明的详细信息，请参阅 Microsoft Store ID 密钥中的声明。

当前，创建 Microsoft Store ID 密钥的唯一方法是通过你的应用中的客户端代码调用通用 Windows 平台 (UWP) API。 生成的密钥表示当前在设备上登录到 Microsoft Store 的用户的身份。

注意

每个 Microsoft Store ID 密钥的有效期为 90 天。 密钥到期后，可以续订该密钥。 我们建议你续订 Microsoft Store ID 密钥，而非创建新密钥。

为 Microsoft Store 收集 API 创建 Microsoft Store ID 密钥

按照以下步骤创建可与 Microsoft Store 收集 API 一起使用的 Microsoft Store ID 密钥，以查询用户拥有的产品或将可消费产品报告为已完成。

1. 将具有受众 URI 值 https://onestore.microsoft.com/b2b/keys/create/collections 的 Azure AD 访问令牌从服务传递到客户端应用。 这是你在步骤 3 的早先阶段创建的令牌之一。

2. 在你的应用代码中，调用以下方法之一以检索 Microsoft Store ID 密钥：

• 如果你的应用使用 Windows.Services.Store 命名空间中的 StoreContext 类来管理应用内购买，请使用 StoreContext.GetCustomerCollectionsIdAsync 方法。

• 如果你的应用使用 Windows.ApplicationModel.Store 命名空间中的 CurrentApp 类来管理应用内购买，请使用 CurrentApp.GetCustomerCollectionsIdAsync 方法。

  将 Azure AD 访问令牌传递给该方法的 serviceTicket 参数。 如果在作为当前应用发布者管理的服务上下文中维护匿名用户 ID，则还可将用户 ID 传递给 publisherUserId 参数，以将当前用户与新的 Microsoft Store ID 密钥相关联（用户 ID 将嵌入到密钥中）。 否则，如果不需要将用户 ID 与 Microsoft Store ID 密钥相关联，则可将任何字符串值传递给 publisherUserId 参数。

3. 在应用成功创建 Microsoft Store ID 密钥后，请将该密钥传递回服务。

为 Microsoft Store 购买 API 创建 Microsoft Store ID 密钥

按照以下步骤创建可与 Microsoft Store 购买 API 一起使用的 Microsoft Store ID 密钥，以向用户授予免费产品、获取用户订阅或更改用户订阅的计费状态。

1. 将具有受众 URI 值 https://onestore.microsoft.com/b2b/keys/create/purchase 的 Azure AD 访问令牌从服务传递到客户端应用。 这是你在步骤 3 的早先阶段创建的令牌之一。

2. 在你的应用代码中，调用以下方法之一以检索 Microsoft Store ID 密钥：

• 如果你的应用使用 Windows.Services.Store 命名空间中的 StoreContext 类来管理应用内购买，请使用 StoreContext.GetCustomerPurchaseIdAsync 方法。

• 如果你的应用使用 Windows.ApplicationModel.Store 命名空间中的 CurrentApp 类来管理应用内购买，请使用 CurrentApp.GetCustomerPurchaseIdAsync 方法。

  将 Azure AD 访问令牌传递给该方法的 serviceTicket 参数。 如果在作为当前应用发布者管理的服务上下文中维护匿名用户 ID，则还可将用户 ID 传递给 publisherUserId 参数，以将当前用户与新的 Microsoft Store ID 密钥相关联（用户 ID 将嵌入到密钥中）。 否则，如果不需要将用户 ID 与 Microsoft Store ID 密钥相关联，则可将任何字符串值传递给 publisherUserId 参数。

3. 在应用成功创建 Microsoft Store ID 密钥后，请将该密钥传递回服务。

图示

下图演示了创建 Microsoft Store ID 密钥的过程。

Microsoft Store ID 密钥中的声明

Microsoft Store ID 密钥是 JSON Web 令牌 (JWT)，该令牌表示你想要访问其产品所有权信息的用户的标识。 当使用 Base64 解码时，Microsoft Store ID 密钥包含以下声明。

• iat：指定颁发密钥的时间。 此声明可用于确定令牌的有效期。 此值表示为纪元时间。
• iss：指定颁发者。 这与 aud 声明具有相同的值。
• aud：指定受众。 必须是下列值之一：https://collections.mp.microsoft.com/v6.0/keys 或 https://purchase.mp.microsoft.com/v6.0/keys。
• exp：指定过期时间，在达到此时间或过后，将不再允许使用该密钥来处理除续订密钥以外的其他任何操作。 此声明的值表示为纪元时间。
• nbf：指定允许使用该令牌进行处理的时间。 此声明的值表示为纪元时间。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId：用于标识开发人员的客户端 ID。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload：一个不透明有效负载（已加密并已经过 Base64 编码），包含仅供 Microsoft Store 服务使用的信息。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId：用于在服务上下文中标识当前用户的用户 ID。 此值与你传递到用于创建密钥的方法的可选 publisherUserId 参数中的值相同。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri：可用于续订密钥的 URI。

以下是一个解码的 Microsoft Store ID 密钥标头的示例。

{
    "typ":"JWT",
    "alg":"RS256",
    "x5t":"agA_pgJ7Twx_Ex2_rEeQ2o5fZ5g"
}

以下是一个解码的 Microsoft Store ID 密钥声明集的示例。

{
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId": "1d5773695a3b44928227393bfef1e13d",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload": "ZdcOq0/N2rjytCRzCHSqnfczv3f0343wfSydx7hghfu0snWzMqyoAGy5DSJ5rMSsKoQFAccs1iNlwlGrX+/eIwh/VlUhLrncyP8c18mNAzAGK+lTAd2oiMQWRRAZxPwGrJrwiq2fTq5NOVDnQS9Za6/GdRjeiQrv6c0x+WNKxSQ7LV/uH1x+IEhYVtDu53GiXIwekltwaV6EkQGphYy7tbNsW2GqxgcoLLMUVOsQjI+FYBA3MdQpalV/aFN4UrJDkMWJBnmz3vrxBNGEApLWTS4Bd3cMswXsV9m+VhOEfnv+6PrL2jq8OZFoF3FUUpY8Fet2DfFr6xjZs3CBS1095J2yyNFWKBZxAXXNjn+zkvqqiVRjjkjNajhuaNKJk4MGHfk2rZiMy/aosyaEpCyncdisHVSx/S4JwIuxTnfnlY24vS0OXy7mFiZjjB8qL03cLsBXM4utCyXSIggb90GAx0+EFlVoJD7+ZKlm1M90xO/QSMDlrzFyuqcXXDBOnt7rPynPTrOZLVF+ODI5HhWEqArkVnc5MYnrZD06YEwClmTDkHQcxCvU+XUEvTbEk69qR2sfnuXV4cJRRWseUTfYoGyuxkQ2eWAAI1BXGxYECIaAnWF0W6ThweL5ZZDdadW9Ug5U3fZd4WxiDlB/EZ3aTy8kYXTW4Uo0adTkCmdLibw=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId": "infusQMLaYCrgtC0d/SZWoPB4FqLEwHXgZFuMJ6TuTY=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri": "https://collections.mp.microsoft.com/v6.0/b2b/keys/renew",
    "iat": 1442395542,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1450171541,
    "nbf": 1442391941
}

相关主题

• 查询产品
• 将可消费产品报告为已完成。
• 授予免费产品
• 获取用户订阅
• 更改用户订阅的计费状态
• 续订 Microsoft Store ID 密钥
• 将应用程序与 Azure Active Directory 集成
• 了解 Azure Active Directory 应用程序清单
• 支持的令牌和声明类型
• Microsoft.StoreServices 库 (GitHub)