> ## 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-TW/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-TW/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-TW/tools/xbox-cli/commands/playfab/api) 呼叫 API，該頁面有完整的選項參考。`Delete*` 和 `Shutdown*` 作業在終端機中會先詢問，在其他環境中則需要 `--confirm`；請參閱[安全性和破壞性作業](https://docs.xbox.com/zh-TW/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-TW/services/playfab/sdks/c-sharp/index.md)
- [PlayFab Multiplayer Unity SDK](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/lobby/unity-multiplayer-api-reference/index.md)
- [XBOX 服務遊戲的 PlayFab 整合](https://docs.xbox.com/zh-TW/services/xbox-services/playfab-integration.md)
- [將 PlayFab GSDK 整合至 Unity](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/servers/mps-unity.md)
- [PlayFab REST API](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/overview.md)
