xbox) は、人だけでなく AI エージェントやスクリプトからも実行できるように設計されています。
コマンドは明示的な引数を受け取り、データ コマンドは JSON を書き込み、エラーは 0 以外の終了コードと共に
stderr に出力されます。このページは、エージェントと、エージェントをセットアップするユーザーを対象としています。
サインインの方法、コマンドの操作対象の選択方法、出力の読み取り方法、適切な API の見つけ方、および何かを
変更する前に確認すべき事項について説明します。
何かを変更する前に
サインインしているユーザーは通常、運用環境のタイトルと販売者に対する管理者権限を持っており、サーバー側には 誤った呼び出しを止めるしくみはありません。安全性と破壊的な操作には、 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 への公開で追加される実績を参照してください。- 運用環境の変更が失敗し、その結果が不明な場合は、変更が適用されている可能性があります。再試行する前に、 影響を受ける状態を読み取ってください。 中断された書き込みは結果が不明であることを報告するを参照してください。
- ユーザーから変更を求められない限り、保存されたコンテキストは変更しないでください。
xbox context set、xbox context unset、xbox context profile deleteは、すべてのセッションの既定値を変更します。
サインイン
auth status は、誰もサインインしていない場合、コード 0 で終了して {"signedIn":false} を報告するため、
signedIn で分岐してください。0 以外の終了コードは確認できなかったことを意味し、エラーは stderr に出力されます。
サインインしているユーザーがタイトルに対する Admin 権限を持っていない場合、PlayFab の呼び出しは失敗します。
認証を参照してください。
タイトルまたは販売者を選択する
タイトルまたは販売者は、--playfab-title-id ABC123 などのフラグとして渡してください。フラグがない場合、
コマンドは XBOX_ 環境変数、または xbox context set で保存された値を使用します。どちらが優先されるかについては、
コンテキストを参照してください。保存されている内容を確認するには
xbox context get --output json-compact を実行し、実質的な呼び出しを行う前に、一度ユーザーにタイトルを
確認してください。
出力を読み取る
--data-only と --output json-compact を組み合わせると、ペイロードだけを 1 行で取得できます。
--data-only を使用すると、エラー時の stdout は
空になるため、stdout を解析する前に終了コードを確認してください。
playfab file upload、download、delete は stdout に何も書き込まず、stderr の
メッセージは変更される可能性があるため、終了コードを確認してください。ファイルを参照してください。
ヘルプでは、インターフェイスが変更される可能性のある試験段階 (Experimental) のコマンドにマークが付けられます。
試験段階のコマンドを参照してください。
レート制限
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 仕様
は機械で読み取れる形式です。各ファイルには、操作がパスごとに、リクエストとレスポンスのスキーマ、必須フィールドと共に
一覧表示されています。ファイル名はパスの最初のセグメントではなく PlayFab の API グループに基づいているため、
ファイルの
pathsで操作を検索してください。たとえば、/Catalogと/InventoryはEconomy.swagger.jsonに、/Match、/Lobby、/MultiplayerServerはMultiplayer.swagger.jsonに含まれています。各操作のsecurityフィールドには、 受け入れる資格情報が示されます。SecretKey、EntityToken、SessionTicket、または資格情報を必要としない操作 (プレイヤーのサインイン呼び出しなど) の場合はNoneです。一部の操作では、説明に許可されるエンティティ トークンの種類も 記載されています。 - PlayFab REST API リファレンスでは、 同じ操作が人向けに説明されています。
SessionTicket を必要とする操作や、プレイヤーまたはゲーム サーバーの
エンティティ トークンのみを受け入れる操作は承認されません。呼び出しが失敗した場合、エラー レスポンスには通常、
InvalidParameter や MissingParameter など、問題の内容が示されます。詳細については、
PlayFab API の統合を参照してください。
Windows の Git Bash では、コマンドに MSYS_NO_PATHCONV=1 を設定してください。設定しないと、CLI が受け取る前に
Git Bash が API パスを Windows のパスに変換してしまいます。
Windows の Git Bash から実行するを参照してください。
シークレットをログに含めない
- リクエスト本文にシークレットが含まれる可能性がある場合は、
--bodyではなく--body-fileで渡して、 シェルの履歴やプロセスの一覧に残らないようにしてください。playfab mps certificate uploadとplayfab mps secret uploadは、本文に常にシークレットが含まれるため、--bodyを拒否します。 - シークレットを構成ファイルや環境変数に含めないでください。
ClientId、TenantId、 OAuth スコープは識別子であり、シークレットではありません。 - PlayFab のレスポンスには、プレイヤー、インベントリ、エコノミーのデータが含まれる場合があります。エージェントがログに記録する内容の 編集、保持、アクセス制御は、エージェントの所有者の責任です。
関連項目
- コマンド: コマンドの完全なリファレンス
- 安全性と破壊的な操作: 最初に確認を求める操作と、名前から想像される以上の処理を行う操作
