> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 X-token 或 OAuth 2.0 请求 User Store ID

> 在你的服务上使用 OAuth 2.0 或 XBOX X-token (XSTS) 生成 User Store ID，无需通过游戏客户端交换身份验证令牌。

本文介绍你的服务如何直接生成 User Store ID，而无需通过游戏客户端交换访问令牌和密钥。此方法适用于：

* 流程中没有游戏客户端参与的体验
* 将用户的 XBOX 账号与你自己的服务上的用户账号关联
* 已经使用 XBOX 安全令牌 (XSTS 或 X-token) 进行客户端到服务和服务到服务调用身份验证的游戏和服务

有关一般的 User Store ID 信息，请参阅[为服务到服务身份验证请求 User Store ID](/publishing/xstore-commerce/xstore-requesting-userstoreid)。

## X-token 要求

此过程需要使用委派身份验证 X-token 来标识 User Store ID 所代表的用户。

有关委派身份验证 X-token 及其创建方法的更多信息，请参阅“Title service calls to XBOX services”文档。

## 使用 OAuth 2.0 生成 User Store ID 的要求

如果你的服务使用 OAuth 让用户使用其 Microsoft 账户 (MSA) 登录，则需要：

* 用户必须有绑定到其 Microsoft 账户的 XBOX 身份，因为 OAuth 凭据需要被交换为 X-token。
* 你请求的 OAuth 范围必须同时包含 `xboxlive.signin` 和 `xboxlive.offline_access`，以确保此流程获得适当的用户同意并能获取所需的 X-token。

有关在你的服务上使用 OAuth 进行 XBOX 服务登录的更多信息，请参阅“XBOX services sign-in for title websites”文档。

## 使用 OAuth 2.0 凭据时的步骤

使用 OAuth 时，你获取用户同意并将 OAuth 凭据针对你的依赖方交换为 X-token。之后，继续按照[使用 X-Token 时的步骤](#steps-when-using-x-tokens)进行。

将 OAuth 凭据交换为 X-token 的概要流程：

1. 获取 OAuth 2.0 授权码
2. 用授权码交换 RPS 令牌（也称为 Microsoft 账户访问令牌）
3. 用 RPS 令牌交换 XBOX 用户令牌
4. 针对你自己的依赖方用 XBOX 用户令牌交换 X-Token
5. 在[使用 X-Token 时的步骤](#steps-when-using-x-tokens)中使用该 X-token。

有关完整实现细节，请参阅“XBOX services sign-in for title websites”文档。

## 使用 X-Token 时的步骤

在获得为你的依赖方标识用户的 X-token 后，使用其 `DelegationToken` 声明创建委派身份验证 X-token。初始 X-token 可以来自游戏客户端或 OAuth 2.0 流程。

创建委派身份验证 X-token 的概要流程：

1. 从用户的 X-token 中提取 DelegationToken 声明 (`dlt`)。
2. 使用你的 Business Partner 证书从 XSAS 服务获取 Service Token。
3. 将 DelegationToken、Service Token 和目标依赖方（见表格）交换为委派身份验证 X-token。

有关如何创建委派身份验证 X-token 的完整实现细节，请参阅“Title service calls to XBOX services”文档。

在步骤 3 中，你使用的依赖方取决于你要为用户生成的是 User Collections ID 还是 User Purchase ID：

| User Store ID 类型                          | 委派身份验证 X-token 依赖方              | 创建 User Store ID 的 URI                                            |
| ----------------------------------------- | ------------------------------- | ----------------------------------------------------------------- |
| User Collections ID (`UserCollectionsId`) | `http://licensing.xboxlive.com` | `https://collections.mp.microsoft.com/v7.0/beneficiaries/me/keys` |
| User Purchase ID (`UserPurchaseId`)       | `http://mp.microsoft.com/`      | `https://purchase.mp.microsoft.com/v7.0/users/me/keys`            |

## 请求

获得委派身份验证 X-token 后，使用与你要调用的服务对应的 URI 请求 User Store ID。

### 请求语法

| 方法     | 请求 URI                                                    |
| ------ | --------------------------------------------------------- |
| `POST` | `collections.mp.microsoft.com/v7.0/beneficiaries/me/keys` |
| `POST` | `purchase.mp.microsoft.com/v7.0/users/me/keys`            |

### 请求头

| 头                | 类型       | 说明                                                   |
| ---------------- | -------- | ---------------------------------------------------- |
| `Authorization`  | `string` | 必需。委派身份验证 X-token，格式为 `XBL3.0 x=[User Hash];[Token]` |
| `Host`           | `string` | 必须与被调用 URI 的 Host 匹配                                 |
| `Content-Length` | `number` | 请求正文的长度。                                             |
| `Content-Type`   | `string` | 指定请求和响应类型。目前唯一支持的值是 `application/json`。              |

### 请求正文

| 参数                | 类型       | 说明                                                                                                                                                                                                           | 是否必需 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| `serviceTicket`   | `string` | 根据你要调用的 URI，为你的服务的 Collections 访问令牌或 Purchase 访问令牌。有关创建这些访问令牌的信息，请参阅[了解不同的令牌与受众 URI](/publishing/xstore-commerce/xstore-requesting-userstoreid#understanding-the-different-access-tokens-and-audience-uris)。 | 是    |
| `publisherUserId` | `string` | 可选值，用于将你自己跟踪的信息盖章到 User Store ID 中。                                                                                                                                                                          | 否    |

### 请求示例

```html theme={null}
POST https://collections.mp.microsoft.com/v7.0/beneficiaries/me/keys HTTP/1.1
Authorization: XBL3.0 x=13178812777611882182;eyJ...
Content-Length: 1352
Content-Type: application/json;
Host: collections.mp.microsoft.com
 
{
    "serviceTicket": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
    "publisherUserId": "CustomPublisherUserId"
}
```

## 响应

### 响应正文

| 参数    | 类型       | 说明                                                 | 是否必需 |
| ----- | -------- | -------------------------------------------------- | ---- |
| `key` | `string` | 可用于与 Microsoft Store 服务进行服务到服务身份验证的 User Store ID。 | 是    |

### 响应示例

```html theme={null}
HTTP/1.1 200 OK
Date: Wed, 23 Mar 2022 23:06:25 GMT
Content-Type: application/json; 
Content-Length: 1716
MS-CorrelationId: dd5be303-f9a0-408a-bd01-e8c63afa721a
MS-RequestId: 0b9c8e5e-dfdd-4cf8-bfbe-93a5be3a7f48
MS-CV: rqFUH3gA+UOmTyXe.0

{"key":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjY..."}
```

## 另请参阅

[从你的服务管理产品](/publishing/xstore-commerce/xstore-authenticating-service)

[使用 Microsoft Store API 对你的服务进行身份验证](/publishing/xstore-commerce/xstore-authenticating-service)

Title service calls to XBOX services

XBOX services sign-in for title websites

[续订 User Store ID 密钥](/publishing/xstore-commerce/xstore-renew-userstoreid)

[Microsoft.StoreServices 库](https://github.com/microsoft/Microsoft-Store-Services)

[Microsoft.StoreServices 示例](https://github.com/microsoft/Microsoft-Store-Services-Sample)