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

# PlayFab API 集成

> 使用你的 Microsoft Entra ID 开发人员凭据(而不是游戏机密密钥)从终端查找和调用 PlayFab API。

XBOX CLI 可以使用你的 Microsoft Entra ID 开发人员凭据,调用任何接受游戏机密密钥或游戏实体令牌的 PlayFab API。仅接受玩家或游戏服务器实体令牌的 API 无法通过这种方式获得授权。

你需要对 PlayFab 游戏拥有 **Admin** 权限。请参阅
[PlayFab 身份验证的工作原理](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md#how-playfab-authentication-works)。

## 设置

登录,将你的 PlayFab 游戏 ID 保存为默认值,然后发出只读请求。
请将 `ABC123` 替换为你的游戏 ID。

```bash theme={null}
xbox auth login
xbox context set playfab-title-id ABC123
xbox playfab api /Admin/GetTitleData
```

若要为单个命令使用其他游戏,请传递 `--playfab-title-id`。请参阅
[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。

## 查找 API

PlayFab 记录了每个操作、其请求和响应架构、哪些字段是必填字段,以及它接受哪些凭据:

* [PlayFab REST API 参考](https://learn.microsoft.com/rest/api/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`。某些操作还会在其说明中列出允许的实体令牌类型。

API 路径为 `/<Prefix>/<Operation>`,例如 `/Admin/GetTitleData`,请求正文是该操作的 JSON 请求对象。

## 示例

这些示例使用 [`playfab api`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/api) 调用 API,该页面提供了完整的选项参考。`Delete*` 和 `Shutdown*` 操作在终端中会先询问,在其他环境中则需要
`--confirm`;请参阅[安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)。

### 获取游戏数据

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/GetTitleData
```

```json theme={null}
{
  "code": 200,
  "status": "OK",
  "data": {
    "Data": {
      "SettingA": "the value",
      "SettingB": "another value"
    }
  }
}
```

### 获取一个游戏数据键

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

### 设置游戏数据

使用 `--body` 以内联方式传递请求正文:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/SetTitleData --body '{ "Key": "MyKey", "Value": "my-value" }'
```

```json theme={null}
{
  "code": 200,
  "status": "OK",
  "data": {}
}
```

或者使用 `--body-file` 从文件中读取请求正文,此处以 PowerShell 为例:

```powershell theme={null}
'{ "Key": "MyKey", "Value": "my-value" }' > data.json
xbox --playfab-title-id ABC123 playfab api /Admin/SetTitleData --body-file data.json
```

### 仅获取数据并输出为单行

`--data-only` 会去掉响应信封,`--output json-compact` 会写入单行 JSON,以便通过管道传输:

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

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

## 错误响应

失败的调用会以代码 `1` 退出:

* 当 PlayFab 返回错误时,命令会将 PlayFab 的错误 JSON 写入 stderr,格式由 `--output` 决定。
* 其他失败(例如网络错误)会将纯文本消息写入 stderr。
* 使用 `--data-only` 时,出错时 stdout 为空。


## Related topics

- [C# PlayFab SDK](https://docs.xbox.com/zh-CN/services/playfab/sdks/c-sharp/index.md)
- [适用于 XBOX 服务游戏的 PlayFab 集成](https://docs.xbox.com/zh-CN/services/xbox-services/playfab-integration.md)
- [PlayFab REST API](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/overview.md)
- [将 PlayFab GSDK 集成到 Unity 中](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/servers/mps-unity.md)
- [PlayFab 统一 SDK](https://docs.xbox.com/zh-CN/services/playfab/sdks/unified-sdk/overview.md)
