xbl 命令系列為實驗性功能。其 CLI 介面可能會根據意見反應而變更或移除。
xbox xbl 管理 XBOX services 設定 (工作設定和已發佈設定的狀態、設定文件、發佈,以及設定結構描述),以及成就圖像。若要列出設定命令所指定的沙箱,請使用 xbox sandbox list。
這些命令所處理的設定,與 Partner Center 所編輯的設定相同。如需了解每項 XBOX services 功能的作用及設定方式,請參閱 XBOX 開發人員文件中的入口網站設定概觀。
共用行為
賣方和沙箱
除了schema 命令以外,每個命令都採用 --seller-id。若未指定,命令會使用 XBOX_SELLER_ID 或以 xbox context set 儲存的賣方,其次使用您唯一的賣方;如果您有多個賣方,請傳遞 --seller-id。
當您省略 --sandbox-id 時,config status 和 config publish 會從 XBOX_SANDBOX_ID 或已儲存的 sandbox-id 取得它。對於沙箱文件,config download 和 config save 需要在命令列上指定 --sandbox-id。
遊戲目標設定
config list、config status、config publish,以及沙箱範圍的 config download 和 config save,會以 --scid 採用遊戲的服務設定識別碼 (SCID),或以 --title-id 採用其 XBOX 遊戲識別碼,但不能同時採用兩者。兩者皆未指定時,它們會使用 XBOX_TITLE_ID 或已儲存的 title-id;請參閱內容。--scid 會忽略這兩者。
--title-id為十六進位,與game get顯示的格式相同:00000001到7FFFFFFF,可加上選用的0x前置詞。對於其他遊戲識別碼,請傳遞 SCID。- 讀取繫結至另一個遊戲之設定的遊戲時,會使用主要遊戲的 SCID。
- 依繫結遊戲的識別碼執行
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 命令都接受 --output table,以及 json (預設) 和 json-compact。每個命令的選項表格都會列出其表格欄。
錯誤
失敗的要求會以 1 結束,並將 JSON 錯誤寫入 stderr,其中包含status、title、detail,以及服務傳送時的 code。請依據 status 或 code 進行分支處理,而不是依據 detail 的措辭。429 錯誤包含 retryAfterSeconds;請參閱速率限制。
當 XBOX services 驗證拒絕設定時,錯誤會在 validation 底下列出每個訊息:
--validate-only 的 config save 和 config publish 會指出失敗的變更是否可能已經套用:
結束代碼為 3 時,請勿重新提交。stderr 會列印用於檢查的唯讀命令:若為儲存,則為
config download --view draft,用來與您儲存的檔案進行比較;若為發佈,則為 config status。
config
檢查、下載、儲存及發佈單一 SCID 的 XBOX services 設定。沙箱包含工作設定 (由config save 變更) 和已發佈設定 (當 config publish 讓工作設定上線後,玩家和測試帳戶就會看到它)。
config list 和 config status
這兩個命令都會回報最新的工作版本和已發佈版本、每個版本的認可時間,以及工作版本是否有未發佈的變更。已發佈的認可時間是已發佈版本的認可時間,而不是發佈完成的時間。
config list 會傳回陣列,每個沙箱對應一個物件。config status 會傳回單一沙箱的一個物件,並在 lastPublish 底下加入其最近一次發佈;沒有可回報的發佈時則為 null。若為 --sandbox-id ALL,lastPublish 一律為 null,因為 ALL 中的全遊戲設定是透過發佈至 HIDDEN 而上線。
config list 選項
config status 選項
這兩個命令的表格都有
SANDBOX、WORKING、WORKING COMMIT、PUBLISHED、PUBLISHED COMMIT 和 UNPUBLISHED 欄。config status 會加入 PUBLISH STATUS,即最近一次發佈的 status。
config list 和 config status 範例
config download 和 config save
下載、驗證及儲存 XBOX services 設定文件集。文件集屬於沙箱 (預設值,需要 SCID 或遊戲以及 --sandbox-id) 或帳戶 (--type account,不採用 SCID、遊戲或沙箱)。
config download 會將文件集的 ETag 儲存在文件旁,名稱為 <sandbox>.etag,帳戶範圍則為 Account.etag;在 Windows 上,此檔案為隱藏檔案。config save 會讀取 --file 所比對到之第一個檔案旁的 ETag 檔案,並在儲存後重寫它。如果設定在您下載之後有所變更,儲存就會失敗;請傳遞 --force 以覆寫這些變更,或傳遞 --etag 自行提供 ETag。
config save 在儲存之前不會詢問,而且 --confirm 不適用於它。請先搭配 --validate-only 執行它。
config download 選項
config save 選項
當 XBOX services 無法儲存文件時 (搭配
--validate-only 時 CanCommit 為 false,否則 Committed 為 false),命令仍會將結果寫入 stdout、將每個驗證訊息寫入 stderr、保持 ETag 檔案不變,並以 1 結束:
ValidationInfo 會回報 FilesNotChangedCommit,且命令以 0 結束。
config download 和 config save 範例
將最新的草稿沙箱文件下載到 xbox-config:
config publish
將 XBOX services 設定的工作版本發佈至沙箱的已發佈設定。發佈為非同步作業:請使用 config publish 開始發佈,然後對目的地沙箱執行 config status,直到 lastPublish.status 為 Success 或 Failed 為止。
來源選取
--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 合併使用。
診斷
來自 XBOX services 的驗證診斷 (例如首次在未設定禁運的情況下發佈至 RETAIL 時的警告) 會寫入 stderr,每行一則。JSON 輸出會將它們保留在ValidationResult 中。
config publish 會以 1 結束,並在 validation 底下列出每個訊息,如錯誤中所示。
跨沙箱發佈會取代全域遊戲儲存空間檔案
從一個沙箱發佈至另一個沙箱,會讓目的地的全域遊戲儲存空間檔案成為來源檔案的完全複本。只有目的地才有的檔案會被刪除,且無法復原。
複本會採用發佈執行時來源所包含的任何內容。玩家自己的資料不受影響,而相同沙箱內的發佈不會變更全域檔案。若要保留目的地檔案,請在發佈之前將它新增至來源沙箱。
每次跨沙箱發佈都會將此警告寫入 stderr (包括搭配
--validate-only 時),並將它包含在確認問題中:
config publish 選項
config publish 範例
驗證對 SANDBOX1 的發佈,但不發佈:
SourceVersion 作為 --configset 傳遞,以發佈您所驗證的版本,且不顯示提示:
schema
探索並下載 XBOX services 設定文件結構描述。schema list 選項
schema get 選項
schema get 會寫入一個 JSON 物件:
schema download 選項
每個結構描述都會儲存為
<type>_<version>.xsd,其中類型為小寫,而命令會列印儲存的路徑。使用 --dest - 時,它會改為將原始 XSD 寫入 stdout,且 --output 不適用。
schema 範例
典型的設定往返流程
-
尋找您可以存取的沙箱:
-
查看工作設定和已發佈設定的狀態:
-
下載草稿文件集,這也會儲存
SANDBOX1.etag: -
編輯
xbox-config中的文件,然後驗證它們: -
儲存它們:
-
在 SANDBOX1 中發佈它們:
-
檢查發佈,並重複執行直到其狀態為
Success或Failed為止:
