> ## 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-TW/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-TW/services/playfab/live-service-management/game-configuration/titledata/index.md)
- [概觀 - Winter Starfall](https://docs.xbox.com/zh-TW/services/playfab/demo-game/overview.md)
- [取得遊戲資料](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/client/title-wide-data-management/get-title-data.md)
- [設定遊戲資料](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/server/title-wide-data-management/set-title-data.md)
- [遊戲資料快速入門](https://docs.xbox.com/zh-TW/services/playfab/live-service-management/game-configuration/titledata/quickstart.md)
