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

# 游戏数据

> 读取、设置和删除游戏范围的键/值数据(客户端可读数据或内部数据)。

管理游戏范围的键/值数据。命令以客户端可读的游戏数据(玩家的游戏客户端会读取这些数据)为目标,除非你添加 `--internal` 以将仅限服务器的内部游戏数据作为目标。你需要对该游戏拥有 **Admin** 权限;请参阅
[PlayFab 身份验证的工作原理](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md#how-playfab-authentication-works)。

| 命令 | PlayFab API 路径 | 说明 |
| - | - | - |
| `playfab title-data get` | `/Admin/GetTitleData` 或 `/Admin/GetTitleInternalData` | 读取一个键、多个键或所有键。 |
| `playfab title-data set` | `/Admin/SetTitleData` 或 `/Admin/SetTitleInternalData` | 设置一个或多个键。 |
| `playfab title-data delete` | `/Admin/SetTitleData` 或 `/Admin/SetTitleInternalData`,使用 `null` 值 | 删除一个或多个键。 |

`title-data` 命令不接受 `--output table`。

## `playfab title-data get`

```text theme={null}
xbox --playfab-title-id ABC123 playfab title-data get [key] [flags]
```

| 参数/选项 | 说明 |
| - | - |
| `[key]` | 要读取的一个键。与 `--key` 相同;请传递其中之一。空白键会被拒绝,而不会被视为所有键。 |
| `--key <key>` | 要读取的一个键。 |
| `--keys <a,b,c>` | 要读取的以逗号分隔的键。不能与单个键结合使用。 |
| `--internal` | 读取内部游戏数据,而不是客户端可读的游戏数据。 |

省略键和 `--keys` 可读取每个键。

针对一个键的 `get` 会输出该键的纯值。若要改为获取 JSON,请传递 `--output` 以获取完整信封,或传递 `--data-only` 以获取其 `data`。读取多个键或所有键时始终返回 JSON。

```bash theme={null}
xbox --playfab-title-id ABC123 playfab title-data get MyKey
```

```text theme={null}
my-value
```

当该键不存在时,`get` 会将 `Key 'MyKey' was not found.` 写入 stderr,并以代码 `1` 退出。

```bash theme={null}
xbox --playfab-title-id ABC123 playfab title-data get MyKey --internal
xbox --playfab-title-id ABC123 playfab title-data get MyKey --output json
xbox --playfab-title-id ABC123 playfab title-data get --keys MyKey,OtherKey
xbox --playfab-title-id ABC123 playfab title-data get
```

## `playfab title-data set`

| 选项 | 说明 |
| - | - |
| `--key <key>` | 要设置的键。与 `--value` 一起使用。 |
| `--value <value>` | `--key` 的值,按原样存储。 |
| `--data <data>` | 由键/值对组成的 JSON 对象,用于一次设置多个键。不能与 `--key` 和 `--value` 结合使用。 |
| `--internal` | 写入内部游戏数据,而不是客户端可读的游戏数据。 |

设置一个键:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab title-data set --key MyKey --value my-value
```

或者一次设置多个键:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab title-data set --data '{"MyKey":"my-value","OtherKey":"2"}'
```

成功后,`set` 会写入它设置的键,例如 `{"applied":["MyKey","OtherKey"]}`。

## `playfab title-data delete`

| 选项 | 必需 | 说明 |
| - | - | - |
| `--keys <a,b,c>` | 是 | 要删除的以逗号分隔的键。 |
| `--internal` | 否 | 删除内部游戏数据,而不是客户端可读的游戏数据。 |

```bash theme={null}
xbox --playfab-title-id ABC123 playfab title-data delete --keys MyKey,OldKey
```

成功后,`delete` 会写入它删除的键,例如 `{"applied":["MyKey","OldKey"]}`。

## 多键写入中途停止时

`set` 和 `delete` 按顺序一次写入一个键,并在第一个未成功的键处停止。该键之前的键已写入;该键之后的键未尝试。该命令会以代码 `1` 退出,并将摘要写入 stderr:

| 字段 | 含义 |
| - | - |
| `applied` | 已写入的键。 |
| `failed` | PlayFab 拒绝的键及其错误。该键未写入。 |
| `unknown` | 其请求可能已到达 PlayFab 但未获得明确答复的键,例如在超时、按下 Ctrl+C 或出现 HTTP 5xx 错误之后。该键可能已写入,因此请在再次运行命令之前使用 `title-data get` 进行检查。 |
| `notSent` | 其请求从未发出的键,例如登录失败时。该键未写入。 |

```json theme={null}
{
  "applied": ["MyKey"],
  "unknown": {
    "key": "OtherKey",
    "error": "The operation was canceled.",
    "outcomeUnknown": "/Admin/SetTitleData may have reached PlayFab, but the request was canceled, so its outcome is unknown. Check whether it was applied before retrying."
  }
}
```


## Related topics

- [游戏数据](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/game-configuration/titledata/index.md)
- [什么是 PlayFab？](https://docs.xbox.com/zh-CN/services/playfab/get-started/what-is-playfab.md)
- [获取游戏数据](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/server/title-wide-data-management/get-title-data.md)
- [设置游戏数据](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/server/title-wide-data-management/set-title-data.md)
- [游戏数据快速入门](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/game-configuration/titledata/quickstart.md)
