> ## 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-TW/services/xbox-services/player-data/index.md)
- [PlayFab 玩家進度文件](https://docs.xbox.com/zh-TW/services/playfab/player-progression/index.md)
- [使用 PlayFab 進行進度管理](https://docs.xbox.com/zh-TW/services/playfab/player-progression/player-progression-overview.md)
- [概觀](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/live-xbl-overview.md)
- [概觀 - Winter Starfall](https://docs.xbox.com/zh-TW/services/playfab/demo-game/overview.md)
