メインコンテンツへスキップ
xbl コマンド ファミリーは試験段階 (Experimental) です。CLI インターフェイスは、フィードバックに基づいて変更または 削除される可能性があります。 xbox xbl は、XBOX サービスの構成 (作業中および公開済みの構成の状態、構成ドキュメント、公開、 構成スキーマ) と、実績の画像を管理します。構成コマンドの対象となるサンドボックスを一覧表示するには、 xbox sandbox list を使用します。 これらのコマンドは、パートナー センターで編集するものと同じ構成を扱います。XBOX サービスの各機能の 役割と構成方法については、XBOX 開発者向けドキュメントの ポータル構成の概要 を参照してください。

共通の動作

販売者とサンドボックス

schema コマンドを除くすべてのコマンドは --seller-id を受け取ります。指定しない場合、コマンドは XBOX_SELLER_ID または xbox context set で保存された販売者を使用し、それもない場合は唯一の 販売者を使用します。販売者が複数ある場合は、--seller-id を渡してください。 config status と config publish は、--sandbox-id を省略した場合、XBOX_SANDBOX_ID または保存された sandbox-id から取得します。config download と config save でサンドボックスのドキュメントを扱う場合は、 コマンド ラインで --sandbox-id を指定する必要があります。

タイトルの指定

config list、config status、config publish、およびサンドボックス スコープの config download と config save は、タイトルのサービス構成識別子 (SCID) を --scid で、またはタイトルの XBOX タイトル ID を --title-id で受け取ります。両方を指定することはできません。どちらも指定しない場合は、XBOX_TITLE_ID または 保存された title-id を使用します。コンテキストを参照してください。--scid を指定すると、この両方が無視されます。
  • --title-id は、game get が表示するとおりの 16 進数で、00000001 から 7FFFFFFF までの値です。0x プレフィックスは省略可能です。それ以外のタイトル ID の場合は、SCID を渡してください。
  • 別のタイトルの構成にバインドされているタイトルを読み取る場合は、プライマリ タイトルの SCID が使用されます。
  • バインドされたタイトルの ID による config save と config publish は、--validate-only を指定した場合でも 拒否されます (bound_title_requires_scid)。エラーにはプライマリ タイトルと SCID が示されるため、その --scid を指定して再実行してください。
  • 他のタイトルがバインドされている構成に --title-id で保存または公開すると、 それらすべてのタイトルの構成が変更されます。ターミナルでは、CLI はバインドされているタイトルを一覧表示して最初に確認を求めます。 ターミナルがない場合は失敗します。--allow-shared-configuration を指定すると、確認はスキップされます。--scid による 書き込みでは確認は求められません。
  • config save と config publish は、使用した販売者と SCID を stderr に書き込みます。読み取り コマンドは、--verbose を指定した場合にこれらを書き込みます。
次のコマンドは、タイトル ID を保存し、その ID を使用して XDKS.1 のタイトルの構成を読み取り、ダウンロードし、 検証します。最後のコマンドでは、代わりに --title-id でタイトルを指定しています。

出力

すべての xbl コマンドは、json (既定) と json-compact に加えて --output table を受け付けます。 各コマンドのオプションの表に、テーブルの列が記載されています。

エラー

リクエストが失敗すると、終了コード 1 で終了し、status、title、detail、および code (サービスが送信した場合) を含む JSON エラーを stderr に書き込みます。処理の分岐には、detail の文言ではなく status または code を使用してください。 429 エラーには retryAfterSeconds が含まれます。 レート制限を参照してください。 XBOX サービスの検証で構成が拒否された場合、エラーには validation の下に各メッセージが一覧表示されます。
--validate-only を指定しない config save と config publish は、失敗した変更が適用された可能性があるかどうかを 示します。 終了コード 3 の場合は、再送信しないでください。stderr には、確認用の読み取り専用コマンドが出力されます。保存の場合は、 保存したファイルと比較するための config download --view draft、公開の場合は config status です。

config

1 つの SCID について、XBOX サービスの構成を調べ、ダウンロードし、保存し、公開します。サンドボックスには、 config save で変更する作業中の構成と、config publish で作業中の構成をライブにした後にプレイヤーとテスト アカウントに 表示される公開済みの構成があります。

config list と config status

どちらのコマンドも、最新の作業中のバージョンと公開済みのバージョン、各バージョンのコミット 時刻、および作業中のバージョンに未公開の変更があるかどうかを報告します。公開済みのコミット時刻は、 公開済みバージョンのコミット時刻であり、公開が完了した時刻ではありません。 config list は、サンドボックスごとに 1 つのオブジェクトを含む配列を返します。config status は、1 つのサンドボックスについて 1 つのオブジェクトを返し、最後の公開を lastPublish の下に追加します。報告する公開がない場合は null になります。 --sandbox-id ALL の場合、ALL のタイトル全体の構成は HIDDEN への公開によってライブになるため、 lastPublish は常に null です。

config list のオプション

config status のオプション

どちらのコマンドのテーブルにも、SANDBOX、WORKING、WORKING COMMIT、 PUBLISHED、PUBLISHED COMMIT、UNPUBLISHED の列があります。config status では、最後の公開の status である PUBLISH STATUS が追加されます。

config list と config status の例

config download と config save

XBOX サービスの構成ドキュメント セットをダウンロード、検証、保存します。ドキュメント セットは、 サンドボックス (既定。SCID またはタイトルと --sandbox-id が必要) またはアカウント (--type account。SCID、タイトル、サンドボックスは指定しません) に属します。 config download は、ドキュメント セットの ETag をドキュメントと同じ場所に <sandbox>.etag として保存します。 アカウント スコープの場合は Account.etag です。Windows では、このファイルは非表示になります。config save は、 --file で最初に一致したファイルと同じ場所にある ETag ファイルを読み取り、保存後に書き換えます。 ダウンロード後に構成が変更されていた場合、保存は失敗します。それらの変更を上書きして保存するには --force を渡し、 ETag を自分で指定するには --etag を渡します。 config save は保存する前に確認を求めません。また、--confirm は config save には適用されません。最初に --validate-only を指定して実行してください。

config download のオプション

config save のオプション

XBOX サービスがドキュメントを保存できない場合 (--validate-only では CanCommit が false、 それ以外では Committed が false)、コマンドは結果を stdout に書き込み、各検証メッセージを stderr に書き込み、 ETag ファイルを変更せずに、終了コード 1 で終了します。
ドキュメントが最新の作業中のドキュメントと一致する場合は、失敗にはなりません。何も保存されず、 ValidationInfo は FilesNotChangedCommit を報告し、コマンドは終了コード 0 で終了します。

config download と config save の例

最新の下書きのサンドボックス ドキュメントを xbox-config にダウンロードします。
ドキュメントを編集した後、すべてのドキュメント、または変更した 2 つのドキュメントのみを検証します。
メッセージを付けて保存します。
公開済みバージョン 7 の時点のドキュメントを 1 つダウンロードします。
アカウントの下書きドキュメントをダウンロードします。

config publish

XBOX サービスの構成の作業中のバージョンを、サンドボックスの公開済みの構成に公開します。 公開は非同期です。config publish で公開を開始し、 lastPublish.status が Success または Failed になるまで、公開先のサンドボックスに対して config status を実行します。

ソースの選択

--sandbox-id は公開先です。ソースはソース サンドボックスの作業中のバージョンで、 既定では公開先と同じサンドボックスです。 ソース サンドボックスに未公開の変更がある場合、その最新の作業中のバージョンは、そのサンドボックスでライブになっているものとは異なります。 その場合、--configset を指定しないサンドボックス間の公開では警告が表示され、ライブになっているバージョンが 示されます。
ソースでライブになっているものをそのまま昇格するには、最初に --validate-only を指定して実行し、提案された --configset を追加します。JSON 出力では、SourceVersion は使用された作業中のバージョン、 sourceHasUnpublishedChanges はそのバージョンがソースでライブになっているものと異なるかどうか、 sourceLiveVersion はソースでライブになっているバージョン (見つかった場合) を示します。 タイトル全体の公開 (--sandbox-id HIDDEN) では、常に ALL の最新の作業中の構成が公開されるため、 --source-sandbox-id や --configset は指定しません。どのバージョンがライブになるかを確認するには、 最初に config status --sandbox-id ALL を実行して workingVersion を確認します。

確認

config publish は、次の場合に公開する前に確認を求めます。 ターミナルでは、公開の内容を説明して確認を求めます。ターミナルがない場合は、処理を拒否して終了コード 1 で終了します。 --confirm (--yes、-y) を指定すると確認はスキップされ、--validate-only では確認は求められません。 安全性と破壊的な操作を参照してください。 RETAIL への公開について確認を求める前に、公開を検証し、 追加される実績を一覧表示します。「はい」と答えると、検証した作業中のバージョンが 公開されるため、ライブになるのは一覧表示された内容です。
この検証が失敗した場合は、何も公開されず、確認も求められません。そのため、ターミナルで、他のタイトルがバインドされている構成に --title-id によって RETAIL への公開を行うには、--allow-shared-configuration が必要です。--confirm を指定した場合は一覧が表示されないため、 一覧を確認するには最初に --validate-only を実行してください。

RETAIL への公開で追加される実績

実績が RETAIL でライブになると、その実績は削除できず、ロック解除のルールとゲーマースコアも変更できなくなります。 そのため、RETAIL への公開では、RETAIL にまだ存在せず、公開によって追加される実績 ID が示されます。
  • --validate-only を指定した場合、一覧は stderr に出力され、JSON 出力では achievementChanges.added に含まれます。
  • --validate-only を指定せずにターミナルで実行した場合、確認に示すように、 一覧は確認の前に表示されます。
実績を追加しない公開では、その旨が表示されます。その他のサンドボックスでは、実績は一覧表示されません。

再公開

config publish は変更のみを公開します。公開先の前回の公開が成功してから何も変更されていない場合、 公開は開始されず、結果の Status は AlreadyPublished になります。公開が失敗した後に config publish を再度実行すると、公開が再試行されます。 XBOX が製品の RETAIL をロックすることがあり、その場合、RETAIL から RETAIL への公開は retail_locked で失敗します。それでも公開するには、--republish を追加します。これにより、選択された 構成 (既定では RETAIL の最新の作業中の構成) が RETAIL に強制的に適用されます。CERT などの別のサンドボックスから RETAIL に公開してもロックは解除されますが、RETAIL の作業中のドキュメントがそのサンドボックスのドキュメントに置き換えられます。 --republish は、何も変更されていない場合でも完全な公開を行います。--validate-only と組み合わせることは できません。

診断

公表解禁を設定せずに RETAIL に初めて公開する場合の警告など、XBOX サービスからの検証診断は、 1 行に 1 つずつ stderr に出力されます。JSON 出力では、これらは ValidationResult に保持されます。
検証が失敗すると、config publish は終了コード 1 で終了し、エラーに示すように、 validation の下に各メッセージを一覧表示します。

サンドボックス間の公開によるグローバル タイトル ストレージ ファイルの置き換え

あるサンドボックスから別のサンドボックスに公開すると、公開先のグローバル タイトル ストレージ ファイルは ソースのファイルの完全なコピーになります。公開先にのみ存在するファイルは削除され、復元 できません。
グローバル ファイルとは、ニュース フィードやマップなど、ゲームのすべてのプレイヤーが読み取るファイルです。 コピーには、公開の実行時点でソースに存在するものがすべて使用されます。プレイヤー自身のデータには 影響せず、同じサンドボックス内での公開ではグローバル ファイルは変更されません。公開先のファイルを保持するには、 公開する前にそのファイルをソース サンドボックスに追加してください。 サンドボックス間の公開では、--validate-only を指定した場合も含め、常にこの警告が stderr に書き込まれ、 確認の質問にも含まれます。

config publish のオプション

config publish の例

公開せずに、SANDBOX1 への公開を検証します。
SANDBOX1 の最新の作業中の構成を公開し、SANDBOX1 でライブにします。
SANDBOX1 の最新の作業中のバージョンを SANDBOX2 に公開します。これにより、SANDBOX2 のグローバル タイトル ストレージ ファイルも SANDBOX1 のファイルに置き換えられます。
SANDBOX1 の作業中のバージョン 42 を SANDBOX2 に公開します。
CERT から RETAIL への公開を検証し、追加される実績を一覧表示します。
次に、出力の SourceVersion を --configset として渡し、検証したバージョンを プロンプトなしで公開します。
何も変更されていなくても、SANDBOX1 を再度公開します。
SANDBOX2 への公開を確認します。

schema

XBOX サービスの構成ドキュメントのスキーマを検出し、ダウンロードします。

schema list のオプション

schema get のオプション

schema get は 1 つの JSON オブジェクトを書き込みます。

schema download のオプション

各スキーマは、種類を小文字にした <type>_<version>.xsd として保存され、コマンドは 保存されたパスを表示します。--dest - を指定した場合は、代わりに未加工の XSD を stdout に書き込み、 --output は適用されません。

schema の例


構成の一般的なラウンド トリップ

  1. アクセスできるサンドボックスを確認します。
  2. 作業中および公開済みの構成の状態を確認します。
  3. 下書きのドキュメント セットをダウンロードします。これにより、SANDBOX1.etag も保存されます。
  4. xbox-config 内のドキュメントを編集してから、検証します。
  5. ドキュメントを保存します。
  6. SANDBOX1 でドキュメントを公開します。
  7. 公開を確認し、状態が Success または Failed になるまで繰り返します。
最終更新日 2026年11月19日