管理服务中的产品权益Manage product entitlements from a service

如果你有应用和加载项的目录,你可以使用 Microsoft Store 收集 APIMicrosoft Store 购买 API 访问你的服务中的这些产品的权益信息。If you have a catalog of apps and add-ons, you can use the Microsoft Store collection API and Microsoft Store purchase API to access entitlement information for these products from your services. 权益表示客户使用通过 Microsoft Store 发布的应用或加载项的权利。An entitlement represents a customer's right to use an app or add-on that is published through the Microsoft Store.

这些 API 由 REST 方法组合而成,旨在供开发人员用于跨平台服务支持的加载项目录。These APIs consist of REST methods that are designed to be used by developers with add-on catalogs that are supported by cross-platform services. 这些 API 支持你执行以下操作:These APIs enable you to do the following:

备注

Microsoft Store 收集 API 和购买 API 使用 Azure Active Directory (Azure AD) 身份验证访问客户所有权信息。The Microsoft Store collection API and purchase API use Azure Active Directory (Azure AD) authentication to access customer ownership information. 要使用这些 API,你(或你的组织)必须具有 Azure AD 目录,并且你必须具有该目录的全局管理员权限。To use these APIs, you (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. 如果你已使用 Office 365 或 Microsoft 的其他业务服务,表示你已经具有 Azure AD 目录。If you already use Office 365 or other business services from Microsoft, you already have Azure AD directory.

概述Overview

以下步骤介绍了使用 Microsoft Store 收集 API 和购买 API 的端到端过程:The following steps describe the end-to-end process for using the Microsoft Store collection API and purchase API:

  1. 在 Azure AD 中配置 Web 应用程序Configure a Web application in Azure AD.
  2. 在 Windows 开发人员中心仪表板中将你的 Azure AD 客户端 ID 与应用程序相关联Associate your Azure AD client ID with your application in the Windows Dev Center dashboard.
  3. 在你的服务中,创建 Azure AD 访问令牌,这些令牌表示你的发布者标识。In your service, create Azure AD access tokens that represent your publisher identity.
  4. 在 Windows 应用的客户端代码中,创建 Microsoft Store ID 密钥(表示当前用户的标识),并将 Microsoft Store ID 密钥传递回你的服务。In client-side code in your Windows app, create a Microsoft Store ID key that represents the identity of the current user, and pass the Microsoft Store ID key back to your service.
  5. 在你具有所需的 Azure AD 访问令牌和 Microsoft Store ID 密钥后,从你的服务调用 Microsoft Store 收集 API 或购买 APIAfter you have the required Azure AD access token and Microsoft Store ID key, call the Microsoft Store collection API or purchase API from your service.

以下部分提供有关其中每个步骤的更多详细信息。The following sections provide more details about each of these steps.

步骤 1:在 Azure AD 中配置 Web 应用程序Step 1: Configure a Web application in Azure AD

你必须先创建 Azure AD Web 应用程序,检索应用程序的租户 ID 和客户端 ID 并生成一个密钥,然后才能使用 Microsoft Store 收集 API 或购买 API。Before you can use the Microsoft Store collection API or purchase API, you must create an Azure AD Web application, retrieve the tenant ID and client ID for the application, and generate a key. Azure AD 应用程序是指你想要从中调用 Microsoft Store 收集 API 或购买 API 的应用或服务。The Azure AD application represents the app or service from which you want to call the Microsoft Store collection API or purchase API. 你需要租户 ID、客户端 ID 和密钥以获取传递给 API 的 Azure AD 访问令牌。You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

备注

你只需执行一次本部分中任务。You only need to perform the tasks in this section one time. 在更新 Azure AD 应用程序清单和获得租户 ID、客户端 ID 和客户端密钥后,你可以随时重复使用这些值来创建新的 Azure AD 访问令牌。After you update your Azure AD application manifest and you have your tenant ID, client ID and client secret, you can reuse these values any time you need to create a new Azure AD access token.

  1. 按照将应用程序与 Azure Active Directory 集成中的说明将 Web 应用程序添加到 Azure AD。Follow the instructions in Integrating Applications with Azure Active Directory to add a Web application to Azure AD.

    备注

    向我们说明你的应用程序页上,确保你选择 Web 应用程序和/或 Web APIOn the Tell us about your application page, make sure that you choose Web application and/or web API. 这是必需的,以便你可以为你的应用程序检索密钥(也称为客户端密码)。This is required so that you can retrieve a key (also called a client secret) for your application. 若要调用 Microsoft Store 收集 API 或购买 API,必须在稍后步骤从 Azure AD 中请求访问令牌时提供客户端密码。In order to call the Microsoft Store collection API or purchase API, you must provide a client secret when you request an access token from Azure AD in a later step.

  2. Azure 管理门户中,导航到 Active DirectoryIn the Azure Management Portal, navigate to Active Directory. 选择你的目录、单击顶部的应用程序选项卡,然后选择你的应用程序。Select your directory, click the Applications tab at the top, and then select your application.

  3. 单击配置选项卡。在此选项卡上,为你的应用程序获取客户端 ID 并请求密钥(这在稍后的步骤中称为客户端密码)。Click the Configure tab. On this tab, obtain the client ID for your application and request a key (this is called a client secret in later steps).
  4. 在屏幕底部,单击管理清单At the bottom of the screen, click Manage manifest. 下载你的 Azure AD 应用程序清单并使用以下文本替换 "identifierUris" 部分。Download your Azure AD application manifest and replace the "identifierUris" section with the following text.

    "identifierUris" : [                                
            "https://onestore.microsoft.com",
            "https://onestore.microsoft.com/b2b/keys/create/collections",
            "https://onestore.microsoft.com/b2b/keys/create/purchase"
        ],
    

    这些字符串表示你的应用程序支持的受众。These strings represent the audiences supported by your application. 在稍后的步骤中,你将创建与其中每个受众值关联的 Azure AD 访问令牌。In a later step, you will create Azure AD access tokens that are associated with each of these audience values. 有关如何下载应用程序清单的详细信息,请参阅了解 Azure Active Directory 应用程序清单For more information about how to download your application manifest, see Understanding the Azure Active Directory application manifest.

  5. 保存你的应用程序清单,并在 Azure 管理门户中将其上传到你的应用程序。Save your application manifest and upload it to your application in the Azure Management Portal.

步骤 2:在 Windows 开发人员中心中将你的 Azure AD 客户端 ID 与应用相关联Step 2: Associate your Azure AD client ID with your app in Windows Dev Center

你必须先在开发人员中心仪表板中将 Azure AD 客户端 ID 与此应用(或者包含加载项的应用)关联,然后才能使用 Microsoft Store 收集 API 或购买 API 以在应用或加载项上操作。Before you can use the Microsoft Store collection API or purchase API to operate on an app or add-on, you must associate your Azure AD client ID with the app (or the app that contains the add-on) in the Dev Center dashboard.

备注

你只需执行一次此任务。You only need to perform this task one time.

  1. 登录开发人员中心仪表板并选择你的应用。Sign in to the Dev Center dashboard and select your app.
  2. 转到服务>产品收集和购买页并将你的 Azure AD 客户端 ID 输入到可用字段之一。Go to the Services > Product collections and purchases page and enter your Azure AD client ID into one of the available fields.

第 3 步:创建 Azure AD 访问令牌Step 3: Create Azure AD access tokens

你的服务必须先创建几个不同的表示你的发布者标识的 Azure AD 访问令牌,然后你才能检索 Microsoft Store ID 密钥或调用 Microsoft Store 收集 API 或购买 API。Before you can retrieve a Microsoft Store ID key or call the Microsoft Store collection API or purchase API, your service must create several different Azure AD access tokens that represent your publisher identity. 每个令牌将与不同的 API 一起使用。Each token will be used with a different API. 每个令牌的生命周期为 60 分钟,你可以在它们到期后进行刷新。The lifetime of each token is 60 minutes, and you can refresh them after they expire.

重要

仅在服务的上下文而非应用中创建 Azure AD 访问令牌。Create Azure AD access tokens only in the context of your service, not in your app. 客户端密码在发送到你的应用时可能会遭泄露。Your client secret could be compromised if it is sent to your app.

了解不同的令牌和受众 URIUnderstanding the different tokens and audience URIs

根据你希望在 Microsoft Store 收集 API 或购买 API 中调用的方法,你必须创建两个或三个不同的令牌。Depending on which methods you want to call in the Microsoft Store collection API or purchase API, you must create either two or three different tokens. 每个访问令牌都与不同的受众 URI(即你之前添加到 Azure AD 应用程序清单的 "identifierUris" 部分的 URI)关联。Each access token is associated with a different audience URI (these are the same URIs that you previously added to the "identifierUris" section of the Azure AD application manifest).

  • 在所有情况下,你都必须使用 https://onestore.microsoft.com 受众 URI 创建令牌。In all cases, you must create a token with the https://onestore.microsoft.com audience URI. 在稍后的步骤中,你要将此令牌传递到 Microsoft Store 收集 API 或购买 API 中的方法的授权标题。In a later step, you will pass this token to the Authorization header of methods in the Microsoft Store collection API or purchase API.

    重要

    https://onestore.microsoft.com 受众仅与安全存储在服务中的访问令牌一起使用。Use the https://onestore.microsoft.com audience only with access tokens that are stored securely within your service. 在服务之外公开访问令牌和此受众会让你的服务易受到重播攻击。Exposing access tokens with this audience outside your service could make your service vulnerable to replay attacks.

  • 如果你想要在 Microsoft Store 收集 API 中调用某个方法以查询用户拥有的产品将可消费产品报告为已完成,则还必须使用 https://onestore.microsoft.com/b2b/keys/create/collections 受众 URI 创建令牌。If you want to call a method in the Microsoft Store collection API to query for products owned by a user or report a consumable product as fulfilled, you must also create a token with the https://onestore.microsoft.com/b2b/keys/create/collections audience URI. 在稍后的步骤中,你要将此令牌传递到 Windows SDK 中的客户端方法,以请求可与 Microsoft Store 收集 API 一起使用的 Microsoft Store ID 密钥。In a later step, you will pass this token to a client method in the Windows SDK to request a Microsoft Store ID key that you can use with the Microsoft Store collection API.

  • 如果你想要调用 Microsoft Store 购买 API 中的方法来向用户授予免费产品获取用户订阅更改用户订阅的计费状态,则必须使用 https://onestore.microsoft.com/b2b/keys/create/purchase 受众 URI 创建一个令牌。If you want to call a method in the Microsoft Store purchase API to grant a free product to a user, get subscriptions for a user, or change the billing state of a subscription for a user, you must also create a token with the https://onestore.microsoft.com/b2b/keys/create/purchase audience URI. 在稍后的步骤中,你要将此令牌传递到 Windows SDK 中的客户端方法,以请求可与 Microsoft Store 购买 API 一起使用的 Microsoft Store ID 密钥。In a later step, you will pass this token to a client method in the Windows SDK to request a Microsoft Store ID key that you can use with the Microsoft Store purchase API.

创建令牌Create the tokens

若要创建访问令牌,请按照使用客户端凭据的服务到服务调用中的说明在服务中使用 OAuth 2.0 API,以便将 HTTP POST 发送到 https://login.microsoftonline.com/<tenant_id>/oauth2/token 终结点。To create the access tokens, use the OAuth 2.0 API in your service by following the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. 示例请求如下所示。Here is a sample request.

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

对于每个令牌,请指定以下参数数据:For each token, specify the following parameter data:

  • 对于 client_idclient_secret 参数,请为从 Azure 管理门户中检索到的应用程序指定客户端 ID 和客户端密钥。For the client_id and client_secret parameters, specify the client ID and the client secret for your application that you retrieved from the Azure Management Portal. 若要创建带有 Microsoft Store 收集 API 或购买 API 所需的身份验证级别的访问令牌,这两个参数都是必需的。Both of these parameters are required in order to create an access token with the level of authentication required by the Microsoft Store collection API or purchase API.

  • 对于资源参数,请指定上一节中列出的受众 URI 之一,具体取决于要创建的访问令牌的类型。For the resource parameter, specify one of the audience URIs listed in the previous section, depending on the type of access token you are creating.

在你的访问令牌到期后,可以按照此处的说明刷新令牌。After your access token expires, you can refresh it by following the instructions here. 有关访问令牌的结构的更多详细信息,请参阅支持的令牌和声明类型For more details about the structure of an access token, see Supported Token and Claim Types.

第 4 步:创建 Microsoft Store ID 密钥Step 4: Create a Microsoft Store ID key

你的应用必须先创建 Microsoft Store ID 密钥并将其发送给服务,然后你才能调用 Microsoft Store 收集 API 或购买 API 中的任何方法。Before you can call any method in the Microsoft Store collection API or purchase API, your app must create a Microsoft Store ID key and send it to your service. 此密钥是 JSON Web 令牌 (JWT),表示你想要访问其产品所有权信息的用户的标识。This key is a JSON Web Token (JWT) that represents the identity of the user whose product ownership information you want to access. 有关此密钥中的声明的详细信息,请参阅 Microsoft Store ID 密钥中的声明For more information about the claims in this key, see Claims in a Microsoft Store ID key.

当前,创建 Microsoft Store ID 密钥的唯一方法是通过你的应用中的客户端代码调用通用 Windows 平台 (UWP) API。Currently, the only way to create a Microsoft Store ID key is by calling a Universal Windows Platform (UWP) API from client code in your app. 生成的密钥表示当前在设备上登录到 Microsoft Store 的用户的身份。The generated key represents the identity of the user who is currently signed in to the Microsoft Store on the device.

备注

每个 Microsoft Store ID 密钥的有效期为 90 天。Each Microsoft Store ID key is valid for 90 days. 密钥到期后,可以续订该密钥After a key expires, you can renew the key. 我们建议你续订 Microsoft Store ID 密钥,而非创建新密钥。We recommend that you renew your Microsoft Store ID keys rather than creating new ones.

为 Microsoft Store 收集 API 创建 Microsoft Store ID 密钥To create a Microsoft Store ID key for the Microsoft Store collection API

按照以下步骤创建可与 Microsoft Store 收集 API 一起使用的 Microsoft Store ID 密钥,以查询用户拥有的产品将可消费产品报告为已完成Follow these steps to create a Microsoft Store ID key that you can use with the Microsoft Store collection API to query for products owned by a user or report a consumable product as fulfilled.

  1. 将具有受众 URI 值 https://onestore.microsoft.com/b2b/keys/create/collections 的 Azure AD 访问令牌从服务传递到客户端应用。Pass the Azure AD access token that has the audience URI value https://onestore.microsoft.com/b2b/keys/create/collections from your service to your client app. 这是你在步骤 3 的早先阶段创建的令牌之一。This is one of the tokens you created earlier in step 3.

  2. 在你的应用代码中,调用以下方法之一以检索 Microsoft Store ID 密钥:In your app code, call one of these methods to retrieve a Microsoft Store ID key:

    将 Azure AD 访问令牌传递给该方法的 serviceTicket 参数。Pass your Azure AD access token to the serviceTicket parameter of the method. 可以选择将 ID 传递给在服务上下文中标识当前用户的 publisherUserId 参数。You can optionally pass an ID to the publisherUserId parameter that identifies the current user in the context of your services. 如果你为服务维护用户 ID,可以使用此参数将这些用户 ID 与对 Microsoft Store 收集 API 进行的调用关联起来。If you maintain user IDs for your services, you can use this parameter to correlate these user IDs with the calls you make to the Microsoft Store collection API.

  3. 在应用成功创建 Microsoft Store ID 密钥后,请将该密钥传递回服务。After your app successfully creates a Microsoft Store ID key, pass the key back to your service.

为 Microsoft Store 购买 API 创建 Microsoft Store ID 密钥To create a Microsoft Store ID key for the Microsoft Store purchase API

按照以下步骤创建可与 Microsoft Store 购买 API 一起使用的 Microsoft Store ID 密钥,以向用户授予免费产品获取用户订阅更改用户订阅的计费状态Follow these steps to create a Microsoft Store ID key that you can use with the Microsoft Store purchase API to grant a free product to a user, get subscriptions for a user, or change the billing state of a subscription for a user.

  1. 将具有受众 URI 值 https://onestore.microsoft.com/b2b/keys/create/purchase 的 Azure AD 访问令牌从服务传递到客户端应用。Pass the Azure AD access token that has the audience URI value https://onestore.microsoft.com/b2b/keys/create/purchase from your service to your client app. 这是你在步骤 3 的早先阶段创建的令牌之一。This is one of the tokens you created earlier in step 3.

  2. 在你的应用代码中,调用以下方法之一以检索 Microsoft Store ID 密钥:In your app code, call one of these methods to retrieve a Microsoft Store ID key:

    将 Azure AD 访问令牌传递给该方法的 serviceTicket 参数。Pass your Azure AD access token to the serviceTicket parameter of the method. 可以选择将 ID 传递给在服务上下文中标识当前用户的 publisherUserId 参数。You can optionally pass an ID to the publisherUserId parameter that identifies the current user in the context of your services. 如果你为服务维护用户 ID,可以使用此参数将这些用户 ID 与对 Microsoft Store 购买 API 进行的调用关联起来。If you maintain user IDs for your services, you can use this parameter to correlate these user IDs with the calls you make to the Microsoft Store purchase API.

  3. 在应用成功创建 Microsoft Store ID 密钥后,请将该密钥传递回服务。After your app successfully creates a Microsoft Store ID key, pass the key back to your service.

步骤 5:从你的服务调用 Microsoft Store 收集 API 或购买 APIStep 5: Call the Microsoft Store collection API or purchase API from your service

在你的服务具有允许其访问特定用户的产品所有权信息的 Microsoft Store ID 密钥后,你的服务可通过遵循以下说明调用 Microsoft Store 收集 API 或购买 API:After your service has a Microsoft Store ID key that enables it to access a specific user's product ownership information, your service can call the Microsoft Store collection API or purchase API by following these instructions:

对于每个方案,请将以下信息传递到 API:For each scenario, pass the following information to the API:

  • 在请求标头中,传递具有受众 URI 值 https://onestore.microsoft.com 的Azure AD 访问令牌。In the request header, pass the Azure AD access token that has the audience URI value https://onestore.microsoft.com. 这是你在步骤 3 的早先阶段创建的令牌之一。This is one of the tokens you created earlier in step 3. 此令牌代表你的发布者标识。This token represents your publisher identity.
  • 在请求正文中,从你的应用中的客户端代码传递你在步骤 4 的早期阶段检索的 Microsoft Store ID 密钥。In the request body, pass the Microsoft Store ID key you retrieved earlier in step 4 from client-side code in your app. 此密钥表示你想要访问其产品所有权信息的用户的标识。This key represents the identity of the user whose product ownership information you want to access.

Microsoft Store ID 密钥中的声明Claims in a Microsoft Store ID key

Microsoft Store ID 密钥是 JSON Web 令牌 (JWT),该令牌表示你想要访问其产品所有权信息的用户的标识。A Microsoft Store ID key is a JSON Web Token (JWT) that represents the identity of the user whose product ownership information you want to access. 当使用 Base64 解码时,Microsoft Store ID 密钥包含以下声明。When decoded using Base64, a Microsoft Store ID key contains the following claims.

  • iat:   标识颁发密钥的时间。:   Identifies the time at which the key was issued. 此声明可用于确定令牌的有效期。This claim can be used to determine the age of the token. 此值表示为纪元时间。This value is expressed as epoch time.
  • iss:   标识颁发者。:   Identifies the issuer. 这与 aud 声明具有相同的值。This has the same value as the aud claim.
  • aud:   标识受众。:   Identifies the audience. 必须是下列值之一:https://collections.mp.microsoft.com/v6.0/keyshttps://purchase.mp.microsoft.com/v6.0/keysMust be one of the following values: https://collections.mp.microsoft.com/v6.0/keys or https://purchase.mp.microsoft.com/v6.0/keys.
  • exp:   标识在此时或之后不再接受密钥处理除续订密钥之外的任何操作的到期时间。:   Identifies the expiration time on or after which the key will no longer be accepted for processing anything except for renewing keys. 此声明的值表示为纪元时间。The value of this claim is expressed as epoch time.
  • nbf:   标识接受令牌进行处理的时间。:   Identifies the time at which the token will be accepted for processing. 此声明的值表示为纪元时间。The value of this claim is expressed as epoch time.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId:   标识开发人员的客户端 ID。:   The client ID that identifies the developer.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload:   包含计划仅供 Microsoft Store 服务使用的信息的不透明负载(已加密,并使用 Base64 编码)。:   An opaque payload (encrypted and Base64 encoded) that contains information that is intended only for use by Microsoft Store services.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId:   标识服务上下文中的当前用户的用户 ID。:   A user ID that identifies the current user in the context of your services. 此值与你传递到用于创建密钥的方法的可选 publisherUserId 参数中的值相同。This is the same value you pass into the optional publisherUserId parameter of the method you use to create the key.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri:   可用于续订密钥的 URI。:   The URI that you can use to renew the key.

以下是一个解码的 Microsoft Store ID 密钥标头的示例。Here is an example of a decoded Microsoft Store ID key header.

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

以下是一个解码的 Microsoft Store ID 密钥声明集的示例。Here is an example of a decoded Microsoft Store ID key claim set.

{
    "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
}