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を指定した場合にこれらを書き込みます。
--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 にダウンロードします。
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 への公開を検証します。
SourceVersion を --configset として渡し、検証したバージョンを
プロンプトなしで公開します。
schema
XBOX サービスの構成ドキュメントのスキーマを検出し、ダウンロードします。schema list のオプション
schema get のオプション
schema get は 1 つの JSON オブジェクトを書き込みます。
schema download のオプション
各スキーマは、種類を小文字にした
<type>_<version>.xsd として保存され、コマンドは
保存されたパスを表示します。--dest - を指定した場合は、代わりに未加工の XSD を stdout に書き込み、
--output は適用されません。
schema の例
構成の一般的なラウンド トリップ
-
アクセスできるサンドボックスを確認します。
-
作業中および公開済みの構成の状態を確認します。
-
下書きのドキュメント セットをダウンロードします。これにより、
SANDBOX1.etagも保存されます。 -
xbox-config内のドキュメントを編集してから、検証します。 -
ドキュメントを保存します。
-
SANDBOX1 でドキュメントを公開します。
-
公開を確認し、状態が
SuccessまたはFailedになるまで繰り返します。
