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

# API

> 依路徑直接呼叫任何 PlayFab API 端點，並附上 JSON 要求本文。

`playfab api` 會依路徑呼叫任何 PlayFab API 端點、傳送您傳遞的要求本文，並以 JSON 寫入 PlayFab 的回應。若要尋找作業及其要求本文，請參閱[尋找 API](https://docs.xbox.com/zh-TW/tools/xbox-cli/playfab-api.md#finding-an-api)。

```text theme={null}
xbox playfab api <api-path> [flags]
```

此命令需要 PlayFab 遊戲，但工作室 API (`/Studio/*`) 除外，因為這些 API 的範圍不限於單一遊戲。請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。

命令所變更的內容取決於路徑。名稱以 `Get`、`List` 或 `Search` 開頭的作業只會讀取。`Delete*` 和 `Shutdown*` 作業會在終端機中先詢問，在其他環境中則需要 `--confirm` (`--yes`、`-y`)。請參閱[安全性和破壞性作業](https://docs.xbox.com/zh-TW/tools/xbox-cli/safety.md)。

## 引數和選項

| 引數 / 選項 | 必要 | 描述 |
| - | - | - |
| `<api-path>` | 是 | PlayFab API 路徑 `/<Prefix>/<Operation>`，例如 `/Admin/GetTitleData` 或 `/Catalog/SearchItems`。必須以 `/` 開頭。在 Git Bash 中，請參閱[在 Windows 上從 Git Bash 執行](#running-from-git-bash-on-windows)。 |
| `--body <body>` | 否 | 作業的 JSON 要求物件 (內嵌)。未傳遞 `--body` 或 `--body-file` 時，預設為 `{}`。 |
| `--body-file <body-file>` | 否 | 保存 JSON 要求物件之檔案的路徑，或以 `-` 從 stdin 讀取。 |
| `--data-only` | 否 | 只寫入 PlayFab 回應的 `data` 欄位。 |
| `--output`、`-o` | 否 | `json` (預設) 或 `json-compact`。 |
| `--verbose` | 否 | 將診斷資訊寫入 stderr，不含要求本文。 |

`--body` 和 `--body-file` 無法合併使用。CLI 會按照您傳遞的內容傳送本文，而不進行驗證。

## 範例

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Catalog/GetCatalogConfig
xbox --playfab-title-id ABC123 playfab api /Match/ListMatchmakingQueues --data-only --output json-compact
xbox --playfab-title-id ABC123 playfab api /Catalog/SearchItems --body-file search.json
xbox --playfab-title-id ABC123 playfab api /Admin/GetTitleData --body '{"Keys":["MyKey"]}' --data-only --output json-compact
```

### 從 stdin 讀取要求本文

```bash theme={null}
printf '%s' '{"Keys":["MyKey"]}' |
  xbox --playfab-title-id ABC123 playfab api /Admin/GetTitleData --body-file -
```

stdin 提供一個要求本文，會讀取到輸入結尾為止，而不是每行一個要求。使用 `--body-file -` 時，即使在終端機中，`Delete*` 和 `Shutdown*` 作業也需要 `--confirm`，因為 stdin 無法回應提示。

## 在 Windows 上從 Git Bash 執行

Git Bash 與其他 MSYS 殼層一樣，會在啟動 Windows 程式之前，將以 `/` 開頭的引數轉換為 Windows 路徑。CLI 會拒絕轉換後的路徑，並說明如何修正：

```console theme={null}
$ xbox playfab api /Catalog/GetCatalogConfig
The API path must start with '/', such as /Admin/GetTitleData; got 'C:/Program Files/Git/Catalog/GetCatalogConfig'.
That looks like /Catalog/GetCatalogConfig after Git Bash converted it to a Windows path. Turn the conversion off for the command, for example:
  MSYS_NO_PATHCONV=1 xbox playfab api /Catalog/GetCatalogConfig
```

為單一命令設定 `MSYS_NO_PATHCONV=1`：

```bash theme={null}
MSYS_NO_PATHCONV=1 xbox --playfab-title-id ABC123 playfab api /Catalog/GetCatalogConfig
```

或將其匯出，套用於工作階段的其餘部分：

```bash theme={null}
export MSYS_NO_PATHCONV=1
```

關閉轉換後，Git Bash 也不會轉換其他路徑，因此請將相對路徑或 Windows 路徑 (例如 `C:/requests/search.json`，而非 `/c/requests/search.json`) 傳遞給 `--body-file`。

## 輸出

PlayFab 的回應，包裝在其 `{code,status,data}` 信封中；請參閱[回應信封](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab.md#response-envelope)。呼叫失敗時，命令會將錯誤寫入 stderr，並以代碼 `1` 結束；請參閱[錯誤回應](https://docs.xbox.com/zh-TW/tools/xbox-cli/playfab-api.md#error-responses)。

`playfab api` 不接受 `--output table`。


## Related topics

- [api_operation](https://docs.xbox.com/zh-TW/services/playfab/api-references/events/Segmentation/api-operation.md)
- [API 原則](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/api-policy.md)
- [實驗 API](https://docs.xbox.com/zh-TW/services/playfab/live-service-management/game-configuration/experiments/experimentation-apis.md)
- [其他 XTF API (API 內容)](https://docs.xbox.com/zh-TW/reference/tools/xtf/xtfapi/atoc-xtfapi.md)
- [照明 API 參考 (API 內容)](https://docs.xbox.com/zh-TW/reference/lighting/gc-reference-lighting-toc.md)
