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

# 通过代理使用 XBOX CLI

> AI 代理如何运行 XBOX CLI,包括登录、选择目标、读取输出,以及在更改任何内容之前获得批准。

XBOX CLI (`xbox`) 既可供人员运行,也专为 AI 代理和脚本运行而构建。其命令采用显式参数,其数据命令写入 JSON,其错误会以非零退出代码输出到 stderr。本页面向代理以及设置代理的人员:介绍如何登录、选择命令的操作对象、读取其输出、找到正确的 API,以及在更改任何内容之前应询问哪些内容。

## 在更改任何内容之前

已登录的用户通常对生产游戏和卖家拥有管理员权限,而服务器端没有任何机制可以阻止错误的调用。[安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)列出了 CLI 会询问和不会询问的内容。其余部分由你负责:

* 仅当 PlayFab 操作的名称以 `Get`、`List` 或 `Search` 开头时,才将其视为只读操作。将其他所有操作以及每个创建、更改或删除内容的 `xbox` 命令视为生产更改。
* 在进行生产更改之前,向用户显示命令,并用一句话说明它会更改什么以及针对哪个游戏或卖家,包括该目标是否来自已保存的上下文。只有在用户同意后才能运行,即使你的运行时无需询问即可运行 `xbox` 也是如此。用户的同意仅涵盖你显示的调用。
* 每次进行生产更改时,都将游戏或卖家作为标志传递。已保存的上下文由操作系统用户的每个会话共享,因此在用户同意和你进行调用之间,它可能会发生变化。
* 在运行 `xbox pc sandbox set`(它会为电脑上的所有人切换沙盒)之前,以及在运行 `xbox pc sandbox launch-apps`(它会关闭 Microsoft Store 和 XBOX 应用)之前,请先询问。
* 请勿添加 `--confirm`(或 `--yes`)来代替询问。CLI 无法分辨是谁添加的。
* 在请求使用 `xbox xbl config publish` 发布到 RETAIL 之前,请使用 `--validate-only` 运行它,并向用户显示它列出的成就。然后将 `--configset` 设置为其 JSON 输出中的 `SourceVersion` 进行发布。RETAIL 中的成就无法删除;请参阅
  [RETAIL 发布添加的成就](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/xbl.md#achievements-a-retail-publish-adds)。
* 如果生产更改失败且其结果未知,则该更改可能已被应用。在重试之前,请读取受影响的状态;请参阅
  [中断的写入会报告其结果未知](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md#an-interrupted-write-reports-that-its-outcome-is-unknown)。
* 除非用户要求你更改,否则请勿改动已保存的上下文。`xbox context set`、
  `xbox context unset` 和 `xbox context profile delete` 会更改每个会话的默认值。

## 登录

```bash theme={null}
xbox auth login                          # once, in the system browser
xbox auth status --output json-compact   # {"signedIn":true,"username":"...",...}
```

当没有人登录时,`auth status` 会以代码 0 退出并报告 `{"signedIn":false}`,因此请根据 `signedIn` 进行分支。非零退出代码表示它无法检查,错误会输出到 stderr。
除非已登录的用户对该游戏拥有 Admin 权限,否则 PlayFab 调用会失败。请参阅
[身份验证](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md)。

## 选择游戏或卖家

将游戏或卖家作为标志传递,例如 `--playfab-title-id ABC123`。如果未传递,命令会使用 `XBOX_` 环境变量或通过 `xbox context set` 保存的值;有关哪个值优先,请参阅
[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。运行 `xbox context get --output json-compact` 可查看已保存的内容,并且在调用任何实质性操作之前,先与用户确认一次游戏。

## 读取输出

结合使用 `--data-only` 和 `--output json-compact`,可以在单行中仅获取有效负载:

```bash theme={null}
xbox --playfab-title-id ABC123 --data-only --output json-compact playfab api /Admin/GetTitleData
```

```json theme={null}
{"Data":{"MyKey":"my-value"}}
```

失败的调用会以非零代码退出,并将其错误写入 stderr。使用 `--data-only` 时,出错时 stdout 为空,因此请在分析 stdout 之前检查退出代码。

`playfab file upload`、`download` 和 `delete` 不会向 stdout 写入任何内容,并且其 stderr 消息可能会更改,因此请检查它们的退出代码。请参阅[文件](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/file.md#output)。

帮助会标记**实验性**命令,其接口可能会更改。请参阅
[实验性命令](https://docs.xbox.com/zh-CN/tools/xbox-cli/cli-command-lifecycle.md)。

### 速率限制

当 XBOX 服务返回 HTTP 429 时,请等待一段时间后再重试;CLI 不会替你重试。当服务指定了等待时间时,错误会说明需要等待多少秒,结构化错误也会以 `retryAfterSeconds` 的形式携带该值。错误代码为 `rate_limited` 的 429 表示你在短时间内发送了过多请求,因此请降低速度。

## 查找正确的 PlayFab API

`xbox playfab api <api-path>` 可调用任何 PlayFab API 操作。路径为
`/<Prefix>/<Operation>`,例如 `/MultiplayerServer/ListBuildSummariesV2`,请求正文是该操作的 JSON 请求对象。PlayFab 记录了这两者:

* [PlayFab Swagger 规范](https://github.com/PlayFab/API_Specs/tree/master/Swagger/PlayFab)
  是机器可读的。每个文件按路径列出其操作,以及操作的请求和响应架构和必填字段。这些文件以 PlayFab 的 API 组命名,而不是以路径的第一段命名,因此请在文件的 `paths` 中搜索该操作:`/Catalog`
  和 `/Inventory` 位于 `Economy.swagger.json` 中,`/Match`、`/Lobby` 和
  `/MultiplayerServer` 位于 `Multiplayer.swagger.json` 中。每个操作的 `security` 字段指明其接受的凭据:`SecretKey`、`EntityToken`、`SessionTicket`,或者对于无需凭据的操作(例如玩家登录调用)为 `None`。某些操作还会在其说明中列出允许的实体令牌类型。
* [PlayFab REST API 参考](https://learn.microsoft.com/rest/api/playfab/)面向人员介绍了相同的操作。

CLI 使用用户的 Microsoft Entra ID 凭据进行调用,而不是使用游戏机密密钥或游戏实体令牌,因此需要玩家 `SessionTicket` 的操作,或仅接受玩家或游戏服务器实体令牌的操作,都不会获得授权。调用失败时,其错误响应通常会指明问题所在,例如
`InvalidParameter` 或 `MissingParameter`。有关详细信息,请参阅 [PlayFab API 集成](https://docs.xbox.com/zh-CN/tools/xbox-cli/playfab-api.md)。

在 Windows 上的 Git Bash 中,请为该命令设置 `MSYS_NO_PATHCONV=1`,否则 Git Bash 会在 CLI 收到 API 路径之前将其转换为 Windows 路径。请参阅
[在 Windows 上从 Git Bash 运行](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/api.md#running-from-git-bash-on-windows)。

## 避免机密出现在日志中

* 当请求正文可能包含机密时,请使用 `--body-file` 而不是 `--body` 传递它,使其不会出现在 shell 历史记录和进程列表中。`playfab mps certificate upload` 和
  `playfab mps secret upload` 会拒绝 `--body`,因为它们的正文始终包含机密。
* 不要将机密放在配置文件和环境变量中。`ClientId`、`TenantId`
  和 OAuth 作用域是标识符,而不是机密。
* PlayFab 响应可能包含玩家、物品清单或经济系统数据。对代理记录的任何内容进行编辑、保留和访问控制,由代理的所有者负责。

## 另请参阅

* [命令](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands.md):完整的命令参考
* [安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md):哪些操作会先询问,以及哪些操作执行的内容超出其名称所示


## Related topics

- [XBOX CLI](https://docs.xbox.com/zh-CN/tools/xbox-cli/index.md)
- [安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)
- [使用 Fiddler 检查 Web 服务调用](https://docs.xbox.com/zh-CN/tools/tools-services/live-fiddler-inspect-web-calls.md)
- [XBOX 上的 Web 请求与 HTTP 堆栈](https://docs.xbox.com/zh-CN/build/console-features/networking/web-requests/index.md)
- [XBOX 开发套件上的 Fiddler](https://docs.xbox.com/zh-CN/build/console-features/networking/tools/fiddler-setup-networking.md)
