> ## 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.

# API

> 通过路径直接调用任何 PlayFab API 终结点,并使用 JSON 请求正文。

`playfab api` 通过路径调用任何 PlayFab API 终结点,发送你传递的请求正文,并以 JSON 形式写入 PlayFab 的响应。若要查找操作及其请求正文,请参阅
[查找 API](https://docs.xbox.com/zh-CN/tools/xbox-cli/playfab-api.md#finding-an-api)。

```text theme={null}
xbox playfab api <api-path> [flags]
```

该命令需要 PlayFab 游戏,但工作室 API (`/Studio/*`) 除外,因为它们不限定于某个游戏。请参阅[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。

该命令更改的内容取决于路径。名称以 `Get`、
`List` 或 `Search` 开头的操作只执行读取。`Delete*` 和 `Shutdown*` 操作在终端中会先询问,在其他环境中则需要 `--confirm` (`--yes`, `-y`)。请参阅
[安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)。

## 参数和选项

| 参数/选项 | 必需 | 说明 |
| - | - | - |
| `<api-path>` | 是 | PlayFab API 路径 `/<Prefix>/<Operation>`,例如 `/Admin/GetTitleData` 或 `/Catalog/SearchItems`。它必须以 `/` 开头。在 Git Bash 中,请参阅[在 Windows 上从 Git Bash 运行](#running-from-git-bash-on-windows)。 |
| `--body <body>` | 否 | 操作的 JSON 请求对象,以内联方式提供。当既未传递 `--body` 也未传递 `--body-file` 时,默认为 `{}`。 |
| `--body-file <body-file>` | 否 | 包含 JSON 请求对象的文件的路径,或者使用 `-` 从 stdin 读取。 |
| `--data-only` | 否 | 仅写入 PlayFab 响应的 `data` 字段。 |
| `--output`, `-o` | 否 | `json`(默认)或 `json-compact`。 |
| `--verbose` | 否 | 将诊断信息写入 stderr,不包括请求正文。 |

`--body` 和 `--body-file` 不能结合使用。CLI 会按你传递的原样发送正文,而不对其进行验证。

## 示例

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Catalog/GetCatalogConfig
xbox --playfab-title-id ABC123 playfab api /Match/ListMatchmakingQueues --data-only --output json-compact
xbox --playfab-title-id ABC123 playfab api /Catalog/SearchItems --body-file search.json
xbox --playfab-title-id ABC123 playfab api /Admin/GetTitleData --body '{"Keys":["MyKey"]}' --data-only --output json-compact
```

### 从 stdin 读取请求正文

```bash theme={null}
printf '%s' '{"Keys":["MyKey"]}' |
  xbox --playfab-title-id ABC123 playfab api /Admin/GetTitleData --body-file -
```

stdin 提供一个请求正文,读取到输入结束为止,而不是每行一个请求。
使用 `--body-file -` 时,即使在终端中,`Delete*` 和 `Shutdown*` 操作也需要 `--confirm`,因为 stdin 无法响应提示。

## 在 Windows 上从 Git Bash 运行

与其他 MSYS shell 一样,Git Bash 在启动 Windows 程序之前,会将以 `/` 开头的参数转换为 Windows
路径。CLI 会拒绝转换后的路径,并说明如何修复:

```console theme={null}
$ xbox playfab api /Catalog/GetCatalogConfig
The API path must start with '/', such as /Admin/GetTitleData; got 'C:/Program Files/Git/Catalog/GetCatalogConfig'.
That looks like /Catalog/GetCatalogConfig after Git Bash converted it to a Windows path. Turn the conversion off for the command, for example:
  MSYS_NO_PATHCONV=1 xbox playfab api /Catalog/GetCatalogConfig
```

为单个命令设置 `MSYS_NO_PATHCONV=1`:

```bash theme={null}
MSYS_NO_PATHCONV=1 xbox --playfab-title-id ABC123 playfab api /Catalog/GetCatalogConfig
```

或者为会话的其余部分导出它:

```bash theme={null}
export MSYS_NO_PATHCONV=1
```

关闭转换后,Git Bash 也不会转换其他路径,因此请向
`--body-file` 传递相对路径或 Windows 路径(例如 `C:/requests/search.json`),而不是
`/c/requests/search.json`。

## 输出

PlayFab 的响应,位于其 `{code,status,data}` 信封中;请参阅
[响应信封](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab.md#response-envelope)。当调用失败时,该命令会将错误写入 stderr 并以代码 `1` 退出;请参阅
[错误响应](https://docs.xbox.com/zh-CN/tools/xbox-cli/playfab-api.md#error-responses)。

`playfab api` 不接受 `--output table`。


## Related topics

- [api_operation](https://docs.xbox.com/zh-CN/services/playfab/api-references/events/Segmentation/api-operation.md)
- [API 策略](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/api-policy.md)
- [Experimentation API](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/game-configuration/experiments/experimentation-apis.md)
- [光照 API 参考（API 内容）](https://docs.xbox.com/zh-CN/reference/lighting/gc-reference-lighting-toc.md)
- [其他 XTF API（API 内容）](https://docs.xbox.com/zh-CN/reference/tools/xtf/xtfapi/atoc-xtfapi.md)
