> ## 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 player-data get` | 读取玩家的部分或全部键。 |
| `playfab player-data set` | 设置一个或多个键。 |
| `playfab player-data delete` | 删除一个或多个键。 |

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

## 选项

每个 `player-data` 命令都接受以下选项:

| 选项 | 必需 | 说明 |
| - | - | - |
| `--playfab-id` | 是 | 玩家的 PlayFab ID(主玩家帐户 ID)。 |
| `--visibility` | 否 | 数据层级:`client`(默认)、`read-only` 或 `internal`。 |
| `--publisher` | 否 | 使用玩家的发行商数据,而不是其游戏数据。 |

| 命令 | 选项 |
| - | - |
| `player-data get` | 使用 `--key` 指定一个键,或使用 `--keys` 指定以逗号分隔的键;两者都省略则获取每个键。将 `--value-only` 与 `--key` 一起使用可输出纯值。`--if-changed-from-version` 仅在数据版本不同时才返回数据;它不能与 `--value-only` 结合使用。 |
| `player-data set` | 使用 `--key` 和 `--value`,或者使用 `--data` 并提供由键和值组成的 JSON 对象。对象值和数组值会存储为 JSON 字符串。`--permission` 是必需的,但与 `--visibility internal` 一起使用时除外,此时它无效;请参阅[权限](#permission)。 |
| `player-data delete` | `--keys`(必需),要删除的以逗号分隔的键。 |

## PlayFab API 路径

`--visibility` 和 `--publisher` 决定所使用的 API:

| 范围和可见性 | `get` API | `set` 和 `delete` API |
| - | - | - |
| 游戏,`client` | `/Admin/GetUserData` | `/Admin/UpdateUserData` |
| 游戏,`read-only` | `/Admin/GetUserReadOnlyData` | `/Admin/UpdateUserReadOnlyData` |
| 游戏,`internal` | `/Admin/GetUserInternalData` | `/Admin/UpdateUserInternalData` |
| 发行商,`client` | `/Admin/GetUserPublisherData` | `/Admin/UpdateUserPublisherData` |
| 发行商,`read-only` | `/Admin/GetUserPublisherReadOnlyData` | `/Admin/UpdateUserPublisherReadOnlyData` |
| 发行商,`internal` | `/Admin/GetUserPublisherInternalData` | `/Admin/UpdateUserPublisherInternalData` |

## 权限

`client` 或 `read-only` 键要么为 `Private`(仅玩家本人可读),要么为
`Public`(其他玩家也可读)。PlayFab 会为 `set` 写入的每个键赋予你传递的权限,替换其原有权限,因此对于这些层级,`set` 需要 `--permission`。该权限适用于 `--data` 中的每个键;若要为不同的键赋予不同的权限,请在不同的命令中设置它们。

## 示例

输出玩家的 `level` 键的值:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab player-data get --playfab-id PLAYER123 --key level --value-only
```

在玩家的只读数据中设置 `level`,以便其他玩家也可以读取它:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab player-data set --playfab-id PLAYER123 --visibility read-only --key level --value 5 --permission Public
```

在玩家的内部数据中设置 `rating`:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab player-data set --playfab-id PLAYER123 --visibility internal --key rating --value 1500
```

删除玩家的 `level` 和 `legacyFlag` 键:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab player-data delete --playfab-id PLAYER123 --keys level,legacyFlag
```


## Related topics

- [玩家数据](https://docs.xbox.com/zh-CN/services/xbox-services/player-data/index.md)
- [PlayFab 玩家进程文档](https://docs.xbox.com/zh-CN/services/playfab/player-progression/index.md)
- [使用 PlayFab 进行玩家进程管理](https://docs.xbox.com/zh-CN/services/playfab/player-progression/player-progression-overview.md)
- [概述](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/live-xbl-overview.md)
- [丰富在线状态附录](https://docs.xbox.com/zh-CN/services/xbox-services/community/presence/concepts/live-presence-apx.md)
