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

# 從代理程式使用 XBOX CLI

> AI 代理程式如何執行 XBOX CLI，從登入和選擇目標，到讀取輸出，以及在變更任何內容之前取得核准。

XBOX CLI (`xbox`) 的設計是既可由人員執行，也可由 AI 代理程式和指令碼執行。它的命令採用明確的引數，資料命令會寫入 JSON，而錯誤會以非零結束代碼輸出至 stderr。此頁面適用於代理程式以及設定代理程式的人員：說明如何登入、選擇命令作用的對象、讀取其輸出、找到正確的 API，以及在變更任何內容之前應詢問的事項。

## 變更任何內容之前

登入的使用者通常對生產遊戲和賣方具有系統管理員權限，而伺服器端沒有任何機制可阻止錯誤的呼叫。[安全性和破壞性作業](https://docs.xbox.com/zh-TW/tools/xbox-cli/safety.md)列出了 CLI 會詢問和不會詢問的事項。其餘部分則由您負責：

* 只有名稱以 `Get`、`List` 或 `Search` 開頭的 PlayFab 作業，才視為唯讀。將其他所有作業，以及每個會建立、變更或刪除內容的 `xbox` 命令，都視為生產變更。
* 在進行生產變更之前，請向使用者顯示命令，並以一句話說明它會變更什麼，以及在哪個遊戲或賣方上變更，包括該目標是否來自已儲存的內容。只有在使用者同意之後才執行，即使您的執行階段不需詢問就會執行 `xbox` 也一樣。同意只涵蓋您所顯示的呼叫。
* 在每次生產變更時，都以旗標傳遞遊戲或賣方。已儲存的內容由作業系統使用者的每個工作階段共用，因此可能在使用者同意與您呼叫之間發生變更。
* 在執行 `xbox pc sandbox set` (會為 PC 上的每個人切換沙箱) 之前，以及在執行 `xbox pc sandbox launch-apps` (會關閉 Microsoft Store 和 XBOX 應用程式) 之前，請先詢問。
* 不要以新增 `--confirm` (或 `--yes`) 來取代詢問。CLI 無法分辨是誰新增的。
* 在要求使用 `xbox xbl config publish` 發佈至 RETAIL 之前，請先以 `--validate-only` 執行它，並向使用者顯示它列出的成就。然後將 `--configset` 設定為其 JSON 輸出中的 `SourceVersion` 來進行發佈。RETAIL 中的成就無法移除；請參閱 [RETAIL 發佈所新增的成就](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/xbl.md#achievements-a-retail-publish-adds)。
* 如果生產變更失敗且其結果不明，該變更可能已經套用。請在重試之前讀取受影響的狀態；請參閱[中斷的寫入會回報其結果不明](https://docs.xbox.com/zh-TW/tools/xbox-cli/safety.md#an-interrupted-write-reports-that-its-outcome-is-unknown)。
* 除非使用者要求您變更，否則請勿變更已儲存的內容。`xbox context set`、`xbox context unset` 和 `xbox context profile delete` 會變更每個工作階段的預設值。

## 登入

```bash theme={null}
xbox auth login                          # once, in the system browser
xbox auth status --output json-compact   # {"signedIn":true,"username":"...",...}
```

沒有人登入時，`auth status` 會以代碼 0 結束並回報 `{"signedIn":false}`，因此請依據 `signedIn` 進行分支。非零的結束代碼表示它無法檢查，而錯誤會在 stderr 上。除非登入的使用者在遊戲上具有 Admin 權限，否則 PlayFab 呼叫會失敗。請參閱[驗證](https://docs.xbox.com/zh-TW/tools/xbox-cli/authentication.md)。

## 選擇遊戲或賣方

以旗標傳遞遊戲或賣方，例如 `--playfab-title-id ABC123`。若未指定，命令會使用 `XBOX_` 環境變數或以 `xbox context set` 儲存的值；如需了解哪一個優先，請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。執行 `xbox context get --output json-compact` 以查看已儲存的內容，並在呼叫任何實質作業之前，先與使用者確認一次遊戲。

## 讀取輸出

結合 `--data-only` 和 `--output json-compact`，即可在單一行上只取得承載：

```bash theme={null}
xbox --playfab-title-id ABC123 --data-only --output json-compact playfab api /Admin/GetTitleData
```

```json theme={null}
{"Data":{"MyKey":"my-value"}}
```

失敗的呼叫會以非零代碼結束，並將其錯誤寫入 stderr。使用 `--data-only` 時，發生錯誤時 stdout 會是空的，因此請在剖析 stdout 之前先檢查結束代碼。

`playfab file upload`、`download` 和 `delete` 不會寫入任何內容至 stdout，而且其 stderr 訊息可能會變更，因此請檢查其結束代碼。請參閱[檔案](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/file.md#output)。

說明會標示**實驗性**命令，其介面可能會變更。請參閱[實驗性命令](https://docs.xbox.com/zh-TW/tools/xbox-cli/cli-command-lifecycle.md)。

### 速率限制

當 XBOX 服務回應 HTTP 429 時，請等候後再重試；CLI 不會為您重試。當服務指定等候時間時，錯誤會指出秒數，而結構化錯誤也會以 `retryAfterSeconds` 攜帶此值。錯誤碼為 `rate_limited` 的 429 表示您在短時間內傳送了太多要求，因此請放慢速度。

## 尋找正確的 PlayFab API

`xbox playfab api <api-path>` 可呼叫任何 PlayFab API 作業。路徑為 `/<Prefix>/<Operation>`，例如 `/MultiplayerServer/ListBuildSummariesV2`，而要求本文是該作業的 JSON 要求物件。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`。有些作業也會在其描述中列出允許的實體權杖類型。
* [PlayFab REST API 參考](https://learn.microsoft.com/rest/api/playfab/)以適合人員閱讀的方式涵蓋相同的作業。

CLI 會使用使用者的 Microsoft Entra ID 認證進行呼叫，而不是使用遊戲祕密金鑰或遊戲實體權杖，因此需要玩家 `SessionTicket`，或只接受玩家或遊戲伺服器實體權杖的作業，都不會獲得授權。呼叫失敗時，其錯誤回應通常會指出問題所在，例如 `InvalidParameter` 或 `MissingParameter`。如需詳細資訊，請參閱 [PlayFab API 整合](https://docs.xbox.com/zh-TW/tools/xbox-cli/playfab-api.md)。

在 Windows 上的 Git Bash 中，請為命令設定 `MSYS_NO_PATHCONV=1`，否則 Git Bash 會在 CLI 收到 API 路徑之前將其轉換為 Windows 路徑。請參閱[從 Windows 上的 Git Bash 執行](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/api.md#running-from-git-bash-on-windows)。

## 避免祕密出現在記錄中

* 當要求本文可能包含祕密時，請使用 `--body-file` 而不是 `--body` 傳遞它，讓它不會出現在殼層歷程記錄和處理序清單中。`playfab mps certificate upload` 和 `playfab mps secret upload` 會拒絕 `--body`，因為它們的本文一定包含祕密。
* 不要將祕密放在組態檔和環境變數中。`ClientId`、`TenantId` 和 OAuth 範圍是識別碼，而不是祕密。
* PlayFab 回應可能包含玩家、庫存或經濟系統資料。對代理程式所記錄的任何內容進行修訂、保留和存取控制，由代理程式的擁有者負責。

## 另請參閱

* [命令](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands.md)：完整的命令參考
* [安全性和破壞性作業](https://docs.xbox.com/zh-TW/tools/xbox-cli/safety.md)：哪些作業會先詢問，以及哪些作業的影響超出其名稱所示


## Related topics

- [XBOX CLI](https://docs.xbox.com/zh-TW/tools/xbox-cli/index.md)
- [安全性和破壞性作業](https://docs.xbox.com/zh-TW/tools/xbox-cli/safety.md)
- [搭配 GDK 使用 AI 程式碼撰寫代理程式](https://docs.xbox.com/zh-TW/build/gdk-and-engines/guides/use-ai-coding-agents-with-the-gdk.md)
- [稽核記錄](https://docs.xbox.com/zh-TW/tools/xbox-cli/audit-log.md)
- [命令](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands.md)
