跳轉到主要內容
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 時才會這麼做。
這些命令會儲存遊戲識別碼,然後使用它在 XDKS.1 中讀取、下載及驗證該遊戲的設定。最後一個命令則改用 --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:
編輯文件之後,驗證所有文件,或只驗證您變更的兩個文件:
附上訊息儲存它們:
下載某個文件在已發佈版本 7 中的內容:
下載帳戶的草稿文件:

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 的發佈,但不發佈:
發佈 SANDBOX1 的最新工作設定,使其在 SANDBOX1 中上線:
將 SANDBOX1 的最新工作版本發佈至 SANDBOX2。這也會以 SANDBOX1 的全域遊戲儲存空間檔案取代 SANDBOX2 的全域遊戲儲存空間檔案:
將 SANDBOX1 的工作版本 42 發佈至 SANDBOX2:
驗證從 CERT 到 RETAIL 的發佈,這會列出它新增的成就:
然後將輸出的 SourceVersion 作為 --configset 傳遞,以發佈您所驗證的版本,且不顯示提示:
即使沒有任何變更,仍再次發佈 SANDBOX1:
檢查對 SANDBOX2 的發佈:

schema

探索並下載 XBOX services 設定文件結構描述。

schema list 選項

schema get 選項

schema get 會寫入一個 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日