使用 Microsoft Store API 验证您的服务

本主题介绍如何获取并使用委派验证 XSTS 令牌或用户 Store ID 来通过 Microsoft Store 服务进行身份验证。

可以通过以下两种方式使用 Microsoft Store API 进行身份验证。

• 用户 Store ID 和 Microsoft Entra ID：将身份验证以及结果绑定到登录 Microsoft Store 应用的用户帐户。
• 委派验证 XSTS 令牌：将身份验证和结果绑定到当前正在玩游戏的用户的 Xbox 服务帐户。

我们建议新游戏和服务对电脑游戏和 Xbox 游戏使用用户Store ID 身份验证方法。 XSTS 令牌的范围限于玩游戏的用户，在电脑上的某些情况下，可能是正在执行购买交易的帐户。 （有关详细信息，请参阅处理电脑上不匹配的商店帐户情形。）此外，某些 Microsoft Store 服务（如定期和购买服务）不支持 XSTS 令牌。 Microsoft 应用商店未来的服务和开发将使用用户 Store ID，而非 XSTS 令牌。

规划跨平台电子商务解决方案或服务的游戏应使用用户 Store ID，因为无需客户端交互即可续订这些游戏。 服务的 XSTS 身份验证流最多有 30 天的生存期，然后需要再次连接到活动客户端。

以下介绍了如何从前面提到的类型获取适当授权的配置和资源。

通过委派验证 XSTS 令牌进行身份验证

添加以下格式的请求标头 Authorization，使用委派验证 XSTS 令牌来验证服务对服务的调用。

Authorization: XBL3.0 x=<user hash>;<XSTS token>

XSTS 令牌的目标信赖方必须为 https://licensing.xboxlive.com，与旧版 Xbox 清单服务相同。 如果你以前的服务被设置为调用 Xbox 库存，则可以重新使用与此端点相同的令牌。 当生成的签名与指定端点的签名策略相匹配时，也需要签名标头。

有关如何获取、管理、使用委派的身份验证 XSTS 令牌和签名的详细信息，请参阅以下资源。

• 游戏服务示例：一个全面的 web 服务示例，演示了对来自客户端、服务器到服务器身份验证、商务服务等的 XSTS 令牌的验证和处理。 从 GDK 下载网站下载最新版本。 下载最新版本的所有示例。 游戏服务示例位于下载的 .zip 文件中的 samples\Live\GameService 下。
• Xfest 2019 - XSTS 身份验证和服务器到服务器交互变得更轻松：概述与解释了 XSTS 令牌以及“游戏服务示例”将如何帮助你开启“服务到服务身份验证”的工作。 若要下载演示文稿信息，请在存档网站上选择 GDK Track 下载。
• Xbox 服务身份验证和服务到服务调用（NDA 主题）要求授权：更详细地介绍了身份验证、XSTS 令牌以及向 Xbox 服务进行服务到服务调用所需的步骤和调用。

使用委派的身份验证 XSTS 令牌查看和管理产品所需的其他配置

由于委派验证 XSTS 令牌已绑定到合作伙伴中心的业务合作伙伴，因此你想要查看或管理的产品需要链接到你的 XSTS 令牌所绑定到的业务合作伙伴。 为此，需要将项目配置到产品中，并确保在合作伙伴中心游戏的“Xbox 设置”页下选择目标业务合作伙伴。 此产品组绑定到在合作伙伴中心中定义的工作室 ID。 工作室 ID 必须与 XSTS 令牌绑定到的业务合作伙伴具有相同的 ID。

当产品未正确链接到 XSTS 令牌中的业务合作伙伴 ID 时，最常见的症状是，对集合的调用将成功，但结果中没有项。 （有关详细信息，请参阅论坛文章 到集合 LicensePreview 服务的 B2B 调用返回空结果（合作伙伴中心配置的游戏）。）

在合作伙伴中心中正确配置产品和 Web 服务

1. 使用 web 服务的生成证书链接创建业务合作伙伴证书。 （选择开发人员设置>Xbox Live>Web 服务。）选择信赖方所绑定到的 Web 服务行中的链接。

2. 转到业务合作伙伴管理 UI（选择“开发人员设置”>“Xbox Live”>“业务合作伙伴”），然后复制与上面使用的 Web 服务中的合作伙伴 ID 匹配的业务合作伙伴 ID。 （示例业务合作伙伴 ID：12345678-9012-3456-7890-123456789012）

3. 在产品的合作伙伴中心概述页面上，选择新建，然后选择产品组。

4. 将此产品组分配给开发者工作室，或选择“创建新的开发者工作室”（如果尚无）。

5. 所选或创建的开发者工作室的工作室 ID 必须与你在这些说明中从步骤 2 检索到的业务合作伙伴 ID 匹配。 将该值复制到开发者工作室 ID（可选） 文本框。 如果此框中已有值，建议创建新的开发者工作室，而不要更改现有值。 如果值已更改，但已由现有游戏使用，则此更改可能会导致现有服务和企业对企业调用失败。

6. 使用业务合作伙伴的匹配 ID 配置开发者工作室后，返回到创建的产品组。 将游戏和所有产品添加到包含在此产品组中列表中。

7. 选择保存完成产品组的创建。

8. 转到游戏的 Xbox 设置 UI，确保链接的业务合作伙伴与上述步骤中使用的业务合作伙伴相同。

9. 将产品组中的所有项目重新发布到沙盒或开发者环境中的 Microsoft Store。

完成发布过程后，应会看到正确的项正在从服务调用返回。

通过 Microsoft Entra ID 和用户 Store ID 进行身份验证

所有 Microsoft Store 服务 API 都支持通过 Microsoft Entra ID（以前称为 Azure Active Directory）和用户 Store ID 进行身份验证。 若要使用此身份验证类型，你（或你的组织）必须有一个 Microsoft Entra ID 租户，并在该租户下注册一个应用程序 ID。 若要注册应用程序，帐户需要租户下的全局管理员角色。 如果已使用 Microsoft Office 365 或 Microsoft 中的其他业务服务，表示你已经具有可在 Azure 门户中管理的 Microsoft Entra ID 租户。

有关如何获取此身份验证类型所需的用户 Store ID 的指南，请参阅请求用户 Store ID 以进行服务间身份验证。

注意

在电脑上，权利与登录到 Microsoft Store 应用的用户相关联，而不是与当前正在玩游戏的用户相关联。 因此，帐户可能不同，建议电脑游戏查看在电脑上处理不匹配商店帐户场景中的信息。

使用 Entra ID 流调用 Microsoft Store API 时，将在请求的 Authorization 标头中使用 Entra 访问令牌，如下所示。

Authorization: Bearer <Entra ID access token>  

如果在沙盒中工作，则必须将以下声明添加到请求的 JSON 正文来指定具体的沙盒。 如果没有此值，结果的沙盒范围默认为 RETAIL。

示例：

  "sbx": "XDKS.1"

还必须使用从客户端获取的用户 Store ID 将下表中所示的参数添加到请求的 JSON 正文。

参数	类型	说明	必需
identityType	string	指定字符串值 b2b。	是
identityValue	string	表示您要为其将 Consumable（易耗品）报告为已完成的用户身份的 用户 Microsoft Store ID 密钥。	是
localTicketReference	string	已返回响应的请求标识符。 我们建议使用与用户 Store ID 密钥中的 userIdclaim 相同的值。	是

示例：

  "beneficiaries": [
    {
        "identitytype" : "b2b",
        "identityValue" : "eyJ0eXAiOiJ...",
        "localTicketReference" : "testReference"
    }
  ],

有关如何获取、管理、使用用户 Store ID 的身份验证的详细信息，请参阅以下资源。

• Microsoft.StoreServices (GitHub)：源代码和库，用于帮助简化 Microsoft 商店服务的身份验证，和从你自己的后端服务中调用 Microsoft 商店服务的过程。 使用这些服务，可以验证和管理在 Microsoft 商店（包括 Xbox 控制台）内为应用或游戏购买的用户。
• Microsoft.StoreServices 示例 (GitHub)：一个 Web 服务示例，突出显示了如何使用 Microsoft.StoreServices 库来通过自己的后端服务简化验证和调用 Microsoft Store Services 的过程。 此示例还提供了管理易耗品的示例逻辑，并将退货与 Clawback 服务进行协调。
• 请求用户 Store ID 用于服务间身份验证。
• 更新用户 Store ID 密钥
• 从服务中管理产品权利

调用 Microsoft Store API 的关系图

下图描述了使用来自服务的用户 Store ID 调用 Microsoft Store API 的过程。

使用用户 Store ID/Microsoft Entra ID 身份验证查看和管理产品所需的其他配置

将服务设置为使用 Microsoft Entra ID 身份验证和用户 Store ID 的身份验证时，需要在合作伙伴中心中将 Entra 应用程序客户端 ID 添加到游戏的产品集合和购买列表。 你可以设置两个单独的客户端应用 ID，在调用“集合”和“购买”服务时，这些 ID 将能够查看产品及其加载项。 当产品未正确链接到 Entra 应用程序客户端 ID 时，最常见的症状是，可成功调用集合，但结果中不会包含任何项。

通过 Microsoft Entra ID 和用户 Store ID 将产品配置为对服务可见

1. 在游戏的“合作伙伴中心”页面，从左侧面板中选择产品集合和购买。

2. 输入用于对服务进行身份验证的 Entra 应用程序的客户端 ID。

3. 单击保存按钮。

4. 将该产品下的游戏产品和所有加载项重新发布到沙盒或开发人员环境中的 Microsoft Store。

完成发布过程后，应会看到正确的项正在从服务调用返回。

另请参阅

Microsoft Store 服务 API

请求用户 Store ID 用于服务间身份验证。

更新用户 Store ID 密钥