管理来自服务的产品授权

项目
07/05/2024

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

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

Microsoft应用商店收集 API：查询用户拥有的产品，并将易耗品报告为已完成。
Microsoft应用商店购买 API：向用户授予免费产品、获取用户的订阅，以及更改用户的订阅的计费状态。

注意

Microsoft应用商店收集 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 应用商店收集 API 和购买 API 的端到端过程：

在 Azure AD 中配置应用程序。
在合作伙伴中心将你的 Azure AD 应用程序 ID 与应用相关联。
在你的服务中，创建表示你的发布者身份的 Azure AD 访问令牌。
在客户端 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 访问令牌。

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

注意

注册应用程序时，必须选择“Web 应用/API”作为应用程序类型，以便可以检索应用程序的密钥（也称为客户端机密）。若要调用 Microsoft 应用商店收集 API 或购买 API，必须在后续步骤中从 Azure AD 请求访问令牌时提供客户端密码。
在 Azure 管理门户中，导航到“Azure Active Directory”。选择你的目录，在左侧导航窗格中单击“应用注册”，然后选择你的应用程序。
随后你将转到该应用程序的注册主页。在此页上，复制“应用程序 ID”值供稍后使用。
创建一个稍后需要用到的密钥（称为客户端机密）。在左侧窗格中，依次单击“设置”、“密钥”。在此页上，完成创建密钥的步骤。复制此密钥供稍后使用。

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

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

注意

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

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

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

在检索Microsoft应用商店 ID 密钥或调用 Microsoft 应用商店收集 API 或购买 API 之前，服务必须创建表示发布者标识的多个不同的 Azure AD 访问令牌。每个令牌将用于不同的 API。每个令牌的生存期为 60 分钟，可以在令牌过期后对其进行刷新。

重要

仅在服务的上下文而非应用中创建 Azure AD 访问令牌。如果客户端机密发送到应用，则可能会泄露该机密。

了解不同的令牌和受众 URI

根据要在 Microsoft 应用商店集合 API 或购买 API 中调用的方法，必须创建两个或三个不同的令牌。每个访问令牌都与不同的访问群体 URI 相关联。

在所有情况下，都必须使用访问群体 URI 创建令牌 https://onestore.microsoft.com 。在后面的步骤中，你将此令牌传递给 Microsoft Store 集合 API 或购买 API 中方法的授权 标头。

重要

仅对 https://onestore.microsoft.com 安全存储在服务中的访问令牌使用受众。在服务外部向此受众公开访问令牌可能会使服务容易受到重播攻击。
如果要在 Microsoft 应用商店集合 API 中调用方法以查询用户拥有的产品或将易耗品报告为已完成的产品，则还必须使用 https://onestore.microsoft.com/b2b/keys/create/collections 受众 URI 创建令牌。在后面的步骤中，你将此令牌传递给 Windows SDK 中的客户端方法，以请求可与 Microsoft 应用商店集合 API 一起使用的Microsoft应用商店 ID 密钥。
如果要调用 Microsoft 应用商店购买 API 中的方法，向用户授予免费产品、获取用户的订阅或更改用户的订阅的计费状态，则还必须使用https://onestore.microsoft.com/b2b/keys/create/purchase受众 URI 创建令牌。在后面的步骤中，你将此令牌传递给 Windows SDK 中的客户端方法，以请求可与 Microsoft 应用商店购买 API 一起使用的 Microsoft 应用商店 ID 密钥。

创建令牌

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

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应用商店收集 API 或购买 API 所需的身份验证级别的访问令牌。
对于资源参数，根据要创建的访问令牌的类型，指定上一节中列出的访问群体 URI 之一。

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

步骤 4：创建Microsoft应用商店 ID 密钥

在Microsoft应用商店收集 API 或购买 API 中调用任何方法之前，应用必须创建Microsoft应用商店 ID 密钥并将其发送到服务。此密钥是一个 JSON Web 令牌（JWT），表示要访问其产品所有权信息的用户的标识。有关此密钥中的声明的详细信息，请参阅 Microsoft应用商店 ID 密钥中的声明。

目前，创建Microsoft应用商店 ID 密钥的唯一方法是从应用中的客户端代码调用通用 Windows 平台（UWP） API。生成的密钥表示当前登录到设备上的 Microsoft Store 的用户的标识。

注意

每个Microsoft应用商店 ID 密钥有效期为 90 天。密钥过期后，可以续订密钥。建议续订Microsoft应用商店 ID 密钥，而不是创建新密钥。

为 Microsoft 应用商店集合 API 创建Microsoft应用商店 ID 密钥

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

将具有受众 URI 值的 https://onestore.microsoft.com/b2b/keys/create/collections Azure AD 访问令牌从服务传递到客户端应用。这是在步骤 3 前面创建的令牌之一。
在应用代码中，调用以下方法之一来检索Microsoft应用商店 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 参数。

应用成功创建Microsoft应用商店 ID 密钥后，将密钥传递回服务。

为 Microsoft 应用商店购买 API 创建Microsoft应用商店 ID 密钥

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

将具有受众 URI 值的 https://onestore.microsoft.com/b2b/keys/create/purchase Azure AD 访问令牌从服务传递到客户端应用。这是在步骤 3 前面创建的令牌之一。
在应用代码中，调用以下方法之一来检索Microsoft应用商店 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 参数。

应用成功创建Microsoft应用商店 ID 密钥后，将密钥传递回服务。

图示

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

创建 Windows 应用商店 ID 密钥

Microsoft应用商店 ID 密钥中的声明

Microsoft应用商店 ID 密钥是一个 JSON Web 令牌（JWT），表示要访问其产品所有权信息的用户的标识。使用 Base64 解码时，Microsoft应用商店 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应用商店 ID 密钥标头的示例。

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

下面是已解码Microsoft应用商店 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.StoreServices 库

概述

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

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

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

了解不同的令牌和受众 URI

创建令牌

步骤 4：创建Microsoft应用商店 ID 密钥

为 Microsoft 应用商店集合 API 创建Microsoft应用商店 ID 密钥

为 Microsoft 应用商店购买 API 创建Microsoft应用商店 ID 密钥

图示

Microsoft应用商店 ID 密钥中的声明

反馈

反馈

其他资源

通过

管理来自服务的产品授权

Microsoft.StoreServices 库

概述

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

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

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

了解不同的令牌和受众 URI

创建令牌

步骤 4：创建Microsoft应用商店 ID 密钥

为 Microsoft 应用商店集合 API 创建Microsoft应用商店 ID 密钥

为 Microsoft 应用商店购买 API 创建Microsoft应用商店 ID 密钥

图示

Microsoft应用商店 ID 密钥中的声明

相关主题

反馈

反馈

其他资源