XUser 对象的账号绑定。在 PC 上，此身份与登录 Microsoft Store 应用并用于购买的账号绑定。
在 PC 上，Microsoft Store 应用的账号身份可能与登录 XBOX Live 并游玩游戏的账号不同。
- User Collections ID，用于对 Microsoft Store Collections 服务进行身份验证
- User Purchase ID，用于对 Microsoft Store Purchase 服务进行身份验证
- 配置 Microsoft Entra ID 应用程序。
- 在合作伙伴中心将你的 Microsoft Entra 应用程序 ID 与你的客户端应用关联。
- 在你的服务中，创建代表你的发行商身份的 Microsoft Entra ID 访问令牌。
- 在你的游戏中，创建代表用户身份的 User Store ID 密钥，并将该密钥传回你的服务。
- 对 Microsoft Store API 的请求进行身份验证。
- 在密钥过期时续订 User Store ID 密钥。
- 你的服务： 用于创建 Microsoft Entra 访问令牌并调用 Store API 的安全后端。
- 你的游戏： 为已登录用户创建 User Store ID 密钥并将其传递给你的服务的客户端。
Microsoft.StoreServices .NET 库和示例
若要简化集成，请使用 GitHub 上的 Microsoft.StoreServices。该库处理身份验证和密钥流程，并为 Store 服务调用提供包装器。示例包含消耗品、退款对账和密钥续订的端到端模式。步骤 1：配置 Microsoft Entra ID 应用程序
在使用 Microsoft Store API 之前，请创建一个 Microsoft Entra Web 应用程序来标识你在调用 API 时的服务。从注册的 Web 应用中获取租户 ID、应用程序 ID 和密钥，以便在后续步骤中生成所需的访问令牌。你可以在你的发行商下的多个游戏和产品中重用 Web 应用的租户 ID、应用程序 ID 和密钥。不需要为每个游戏创建新的。
- 如果尚未完成，请按照快速入门：向 Microsoft 身份平台注册应用程序中的说明，向 Microsoft Entra ID 注册一个 Web app / API 应用程序。
[!NOTE] 注册应用程序时，选择 Web app / API 作为应用程序类型。此类型允许你为应用程序获取密钥（也称为 client secret）。若要调用 Microsoft Store API，在后续步骤中从 Microsoft Entra ID 请求访问令牌时，你必须提供 client secret。
- 在 Azure 管理门户中，转到 Microsoft Entra ID。在左侧窗格中选择你的目录、App registrations，然后选择你的应用程序。
- 复制 Application (client) ID 和 Directory (tenant) ID 值以备后用。
- 在左侧窗格的 Certificates & Secrets 下创建并复制新的 client secret。
步骤 2：在合作伙伴中心将你的 Microsoft Entra 应用程序 ID 与你的客户端应用关联
- 登录合作伙伴中心，然后选择你的游戏。
- 选择 Services > Product collections and purchases。在其中一个可用的 Client ID 字段中输入你的 Microsoft Entra 应用程序 ID。
- 选择 Save。
- 将游戏及其附加内容重新发布到商店。
附加内容产品从其父游戏的 Product collections and purchases 页面继承保存的 Client ID。游戏捆绑包产品有自己的 Product collections and purchases 页面，你需要在其中添加 Client ID。
步骤 3：创建 Microsoft Entra ID 访问令牌
所有 API 请求都需要在 Authorization 头中包含一个 Bearer 令牌，称为 Service 访问令牌。所需的其他访问令牌取决于你调用的是哪些服务或 API。仅在你的服务上下文中创建 Microsoft Entra ID 访问令牌，不要在你的应用中创建。如果将 client secret 发送到你的应用，可能会遭到泄露。
了解不同的访问令牌与受众 URI
每个访问令牌都与用于创建它的不同受众 URI 关联。切勿将使用
https://onestore.microsoft.com/.default 受众的服务访问令牌发送给客户端。请在你的服务内部安全存储。创建访问令牌
若要创建访问令牌，请在你的服务中使用 OAuth 2.0 API。按照 Microsoft 身份平台和 OAuth 2.0 客户端凭据流程中的说明，向https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token 端点发送 HTTP POST。以下示例展示了一个样例请求。
- 将
client_id和client_secret设置为你在 Azure 管理门户中的应用注册值。 - 将
resource设置为你所需令牌类型的受众 URI。请参阅了解不同的访问令牌与受众 URI。
步骤 4：创建 User Store ID 密钥
为了在请求中标识用户，你的服务需要获取一个 User Store ID 密钥。User Store ID 是 User Collections ID 或 User Purchase ID 的通用术语。这些密钥之间的唯一区别是它们可以对哪个对应的服务进行身份验证。 你可以在客户端使用 GDK API 或在你的服务上生成 User Store ID 密钥。本节重点介绍通过 GDK API 在客户端创建 User Store ID 密钥。有关如何在你的服务上生成 User Store ID 密钥的更多信息，请参阅使用 X-token 或 OAuth 2.0 从你的服务请求 User Store ID。 User Store ID 密钥是代表登录到 Microsoft Store 应用的用户的 JSON Web Token (JWT)。有关此密钥中声明的更多信息，请参阅 User Store ID 密钥中的声明。每个 User Store ID 密钥有效期为 30 天。你的服务可以在密钥过期前续订它。如果你的服务需要持续访问以查询用户的权益，请续订你的 Microsoft Store ID 密钥，而不是重新创建。有关更多信息，请参阅续订 User Store ID 密钥。
为 Microsoft Store Collections 服务创建 User Collections ID 密钥
User Collections ID 密钥使你能够使用 Collections API 查询用户拥有的产品并管理消耗品。有关消耗品管理的更多信息，请参阅从你的服务管理消耗品产品。- 将你在步骤 3 中创建的 Collections 访问令牌传递给游戏。
- 在游戏中，调用 XStoreGetUserCollectionsIdAsync 检索 User Collections ID 密钥。将 Collections 访问令牌作为
serviceTicket参数传递。可选地，在publisherUserId中传入你的内部用户标识符。 - 在应用成功创建 User Collections ID 密钥后，将该密钥传回你的服务。
为 Microsoft Store Purchase 服务创建 User Purchase ID 密钥
User Purchase ID 密钥使你能够使用 Purchase API 查询用户拥有的产品并管理消耗品。有关消耗品管理的更多信息，请参阅从你的服务管理消耗品产品。- 将你在步骤 3 中创建的 Purchase 访问令牌传递给游戏。
- 在游戏中，调用 XStoreGetUserPurchaseIdAsync 检索 User Purchase ID 密钥。将 Purchase 访问令牌作为
serviceTicket参数传递。可选地，在publisherUserId中传入你的内部用户标识符。 - 在应用成功创建 User Purchase ID 密钥后，将该密钥传回你的服务。
步骤 5：对 Microsoft Store API 的调用进行身份验证
有关说明，请参阅使用 Microsoft Entra ID 和 User Store ID 进行身份验证。步骤 6：当 User Store ID 密钥过期时续订它
有关说明，请参阅续订 User Store ID 密钥。附加信息
创建 User Store ID 密钥的示意图
下图展示了创建 User Store ID 密钥的流程。
User Store ID 密钥中的声明
User Store ID 密钥是一个 JWT，代表你想要访问其产品所有权信息的用户身份。使用 Base64 解码后，User Store ID 密钥包含下表中显示的声明。
以下示例展示了解码后的 User Store ID 头。
kid 声明视为不透明值。Store API 会验证签名。
解码后的 User Store ID 声明集示例。