> ## 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 を書き込み、エラーは 0 以外の終了コードと共に
stderr に出力されます。このページは、エージェントと、エージェントをセットアップするユーザーを対象としています。
サインインの方法、コマンドの操作対象の選択方法、出力の読み取り方法、適切な API の見つけ方、および何かを
変更する前に確認すべき事項について説明します。

## 何かを変更する前に

サインインしているユーザーは通常、運用環境のタイトルと販売者に対する管理者権限を持っており、サーバー側には
誤った呼び出しを止めるしくみはありません。[安全性と破壊的な操作](https://docs.xbox.com/ja-jp/tools/xbox-cli/safety.md)には、
CLI が確認を求める操作と求めない操作が記載されています。それ以外はエージェント側の責任です。

* PlayFab の操作を読み取り専用として扱うのは、名前が `Get`、`List`、または `Search` で始まる場合のみにしてください。
  それ以外のすべての操作、および何かを作成、変更、削除するすべての `xbox` コマンドは、運用環境の変更として扱ってください。
* 運用環境の変更を行う前に、ユーザーにコマンドを示し、何をどのタイトルまたは販売者に対して変更するのかを
  1 文で説明してください。そのターゲットが保存されたコンテキストから取得されるかどうかも含めます。ランタイムが
  確認なしで `xbox` を実行できる場合でも、ユーザーが承認した後にのみ実行してください。承認の対象は、示した呼び出しだけです。
* 運用環境の変更を行うたびに、タイトルまたは販売者をフラグとして渡してください。保存されたコンテキストは
  OS ユーザーのすべてのセッションで共有されるため、ユーザーが承認してから呼び出すまでの間に変更される可能性があります。
* PC 上のすべてのユーザーのサンドボックスを切り替える `xbox pc sandbox set` の前と、Microsoft Store と XBOX アプリを閉じる
  `xbox pc sandbox launch-apps` の前には、確認を求めてください。
* 確認を求める代わりに `--confirm` (または `--yes`) を追加しないでください。CLI には、誰がそれを追加したかを判別できません。
* `xbox xbl config publish` で RETAIL への公開の確認を求める前に、
  `--validate-only` を付けて実行し、一覧表示された実績をユーザーに示してください。その後、JSON 出力の `SourceVersion` を
  `--configset` に設定して公開します。RETAIL の実績は削除できません。
  [RETAIL への公開で追加される実績](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/xbl.md#achievements-a-retail-publish-adds)を参照してください。
* 運用環境の変更が失敗し、その結果が不明な場合は、変更が適用されている可能性があります。再試行する前に、
  影響を受ける状態を読み取ってください。
  [中断された書き込みは結果が不明であることを報告する](https://docs.xbox.com/ja-jp/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` で分岐してください。0 以外の終了コードは確認できなかったことを意味し、エラーは stderr に出力されます。
サインインしているユーザーがタイトルに対する Admin 権限を持っていない場合、PlayFab の呼び出しは失敗します。
[認証](https://docs.xbox.com/ja-jp/tools/xbox-cli/authentication.md)を参照してください。

## タイトルまたは販売者を選択する

タイトルまたは販売者は、`--playfab-title-id ABC123` などのフラグとして渡してください。フラグがない場合、
コマンドは `XBOX_` 環境変数、または `xbox context set` で保存された値を使用します。どちらが優先されるかについては、
[コンテキスト](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/context.md)を参照してください。保存されている内容を確認するには
`xbox context get --output json-compact` を実行し、実質的な呼び出しを行う前に、一度ユーザーにタイトルを
確認してください。

## 出力を読み取る

`--data-only` と `--output json-compact` を組み合わせると、ペイロードだけを 1 行で取得できます。

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

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

失敗した呼び出しは 0 以外のコードで終了し、エラーを stderr に書き込みます。`--data-only` を使用すると、エラー時の stdout は
空になるため、stdout を解析する前に終了コードを確認してください。

`playfab file upload`、`download`、`delete` は stdout に何も書き込まず、stderr の
メッセージは変更される可能性があるため、終了コードを確認してください。[ファイル](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/playfab/file.md#output)を参照してください。

ヘルプでは、インターフェイスが変更される可能性のある**試験段階 (Experimental)** のコマンドにマークが付けられます。
[試験段階のコマンド](https://docs.xbox.com/ja-jp/tools/xbox-cli/cli-command-lifecycle.md)を参照してください。

### レート制限

XBOX サービスが HTTP 429 を返した場合は、待機してから再試行してください。CLI は自動的に再試行しません。
サービスが待機時間を指定している場合、エラーには秒数が示され、構造化されたエラーには
`retryAfterSeconds` としても含まれます。エラー コード `rate_limited` を伴う 429 は、短時間に送信したリクエストが
多すぎることを意味するため、ペースを落としてください。

## 適切な PlayFab API を見つける

`xbox playfab api <api-path>` は、任意の PlayFab API 操作を呼び出します。パスは
`/MultiplayerServer/ListBuildSummariesV2` のような `/<Prefix>/<Operation>` の形式で、リクエスト
本文はその操作の 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/ja-jp/tools/xbox-cli/playfab-api.md)を参照してください。

Windows の Git Bash では、コマンドに `MSYS_NO_PATHCONV=1` を設定してください。設定しないと、CLI が受け取る前に
Git Bash が API パスを Windows のパスに変換してしまいます。
[Windows の Git Bash から実行する](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/playfab/api.md#running-from-git-bash-on-windows)を参照してください。

## シークレットをログに含めない

* リクエスト本文にシークレットが含まれる可能性がある場合は、`--body` ではなく `--body-file` で渡して、
  シェルの履歴やプロセスの一覧に残らないようにしてください。`playfab mps certificate upload` と
  `playfab mps secret upload` は、本文に常にシークレットが含まれるため、`--body` を拒否します。
* シークレットを構成ファイルや環境変数に含めないでください。`ClientId`、`TenantId`、
  OAuth スコープは識別子であり、シークレットではありません。
* PlayFab のレスポンスには、プレイヤー、インベントリ、エコノミーのデータが含まれる場合があります。エージェントがログに記録する内容の
  編集、保持、アクセス制御は、エージェントの所有者の責任です。

## 関連項目

* [コマンド](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands.md): コマンドの完全なリファレンス
* [安全性と破壊的な操作](https://docs.xbox.com/ja-jp/tools/xbox-cli/safety.md): 最初に確認を求める操作と、名前から想像される以上の処理を行う操作


## Related topics

- [XBOX CLI](https://docs.xbox.com/ja-jp/tools/xbox-cli/index.md)
- [安全性と破壊的な操作](https://docs.xbox.com/ja-jp/tools/xbox-cli/safety.md)
- [GDK で AI コーディング エージェントを使用する](https://docs.xbox.com/ja-jp/build/gdk-and-engines/guides/use-ai-coding-agents-with-the-gdk.md)
- [XBOX 開発キットを管理する DevKit Agent](https://docs.xbox.com/ja-jp/tools/tools-console/devkitagent/devkitagent-overview.md)
- [PlayFab Game Server SDK (GSDK) とゲーム サーバーの統合](https://docs.xbox.com/ja-jp/services/playfab/multiplayer/servers/integrating-game-servers-with-gsdk.md)
