> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XBOX services 設定

> 管理 XBOX services 設定，包括其狀態、文件、發佈、結構描述和成就圖像。

`xbl` 命令系列為實驗性功能。其 CLI 介面可能會根據意見反應而變更或移除。

`xbox xbl` 管理 XBOX services 設定 (工作設定和已發佈設定的狀態、設定文件、發佈，以及設定結構描述)，以及成就圖像。若要列出設定命令所指定的沙箱，請使用 [`xbox sandbox list`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/sandbox)。

這些命令所處理的設定，與 Partner Center 所編輯的設定相同。如需了解每項 XBOX services 功能的作用及設定方式，請參閱 XBOX 開發人員文件中的[入口網站設定概觀](https://devdocs.xbox.com/services/xbox-services/fundamentals/portal-config/live-portal-config-overview)。

| 群組 | 命令 | 用途 |
| - | - | - |
| `config` | `list`、`status`、`download`、`save`、`publish` | 檢查工作設定和已發佈設定的狀態、下載及儲存設定文件，以及將設定發佈至沙箱。 |
| `schema` | `list`、`get`、`download` | 列出設定結構描述類型和版本、取得某個版本，或下載 XSD。 |
| [`achievement-image`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/xbl/achievement-image) | `upload`、`get`、`list`、`download` | 註冊、檢查或下載成就圖像。 |

## 共用行為

### 賣方和沙箱

除了 `schema` 命令以外，每個命令都採用 `--seller-id`。若未指定，命令會使用 `XBOX_SELLER_ID` 或以 [`xbox context set`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context) 儲存的賣方，其次使用您唯一的賣方；如果您有多個賣方，請傳遞 `--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`；請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。`--scid` 會忽略這兩者。

* `--title-id` 為十六進位，與 [`game get`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/game) 顯示的格式相同：`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` 指定遊戲：

```powershell theme={null}
xbox context set title-id 1234ABCD
xbox xbl config list --output table
xbox xbl config status --sandbox-id XDKS.1
xbox xbl config download --sandbox-id XDKS.1 --view draft --dest .\xbox-config
xbox xbl config save --sandbox-id XDKS.1 --file ".\xbox-config\*.xml" --validate-only
xbox xbl config status --title-id 1234ABCD --sandbox-id XDKS.1
```

### 輸出

每個 `xbl` 命令都接受 `--output table`，以及 `json` (預設) 和 `json-compact`。每個命令的選項表格都會列出其表格欄。

### 錯誤

失敗的要求會以 1 結束，並將 JSON 錯誤寫入 stderr，其中包含 `status`、`title`、`detail`，以及服務傳送時的 `code`。請依據 `status` 或 `code` 進行分支處理，而不是依據 `detail` 的措辭。429 錯誤包含 `retryAfterSeconds`；請參閱[速率限制](https://docs.xbox.com/zh-TW/tools/xbox-cli/cli-for-agents.md#rate-limits)。

當 XBOX services 驗證拒絕設定時，錯誤會在 `validation` 底下列出每個訊息：

```json theme={null}
{
  "status": 409,
  "title": "Validation failed.",
  "detail": "The configuration failed XBOX services validation. See validation for each message. MS-CV: ...",
  "code": "validation_failed",
  "validation": [
    {
      "severity": "Error",
      "documentName": "achievements2017.xml",
      "message": "XblLimited products do not support achievements or stats2013/stats2015 configuration. Please remove the unsupported configuration. Document failing validation: achievements2017.xml."
    }
  ]
}
```

未搭配 `--validate-only` 的 `config save` 和 `config publish` 會指出失敗的變更是否可能已經套用：

| 結束代碼 | 意義 |
| - | - |
| 1 | 未變更任何項目：要求在傳送之前已停止或失敗，或因 `408` 以外的 `4xx` 而遭到拒絕。 |
| 3 | 結果不明：要求傳送後發生 Ctrl+C、逾時或連線中斷、任何其他錯誤狀態，或 CLI 無法讀取的成功回應。 |

結束代碼為 3 時，請勿重新提交。stderr 會列印用於檢查的唯讀命令：若為儲存，則為 `config download --view draft`，用來與您儲存的檔案進行比較；若為發佈，則為 `config status`。

***

## config

檢查、下載、儲存及發佈單一 SCID 的 XBOX services 設定。沙箱包含工作設定 (由 `config save` 變更) 和已發佈設定 (當 `config publish` 讓工作設定上線後，玩家和測試帳戶就會看到它)。

| 命令 | 描述 |
| - | - |
| `config list` | 列出所有可存取沙箱中的工作設定和已發佈設定狀態。 |
| `config status` | 取得一個沙箱的工作設定和已發佈設定狀態，以及其最近一次發佈。 |
| `config download` | 下載並解壓縮文件集。 |
| `config save` | 驗證或儲存工作文件集。 |
| `config publish` | 驗證或開始發佈一個設定集。 |

### `config list` 和 `config status`

這兩個命令都會回報最新的工作版本和已發佈版本、每個版本的認可時間，以及工作版本是否有未發佈的變更。已發佈的認可時間是已發佈版本的認可時間，而不是發佈完成的時間。

`config list` 會傳回陣列，每個沙箱對應一個物件。`config status` 會傳回單一沙箱的一個物件，並在 `lastPublish` 底下加入其最近一次發佈；沒有可回報的發佈時則為 `null`。若為 `--sandbox-id ALL`，`lastPublish` 一律為 `null`，因為 `ALL` 中的全遊戲設定是透過發佈至 `HIDDEN` 而上線。

| `lastPublish` 欄位 | 描述 |
| - | - |
| `status` | `Running`、`Success` 或 `Failed`。服務未回報時為 `null`。 |
| `jobId` | 發佈作業的 ID。 |
| `message` | 服務關於此發佈的訊息，或 `null`。 |

```json theme={null}
{
  "sandbox": "SANDBOX1",
  "hasWorkingConfiguration": true,
  "workingVersion": 9,
  "workingCommitTime": "2026-10-29T21:40:12+00:00",
  "hasPublishedConfiguration": true,
  "publishedVersion": 9,
  "publishedCommitTime": "2026-10-29T21:40:12+00:00",
  "hasUnpublishedChanges": false,
  "lastPublish": {
    "status": "Success",
    "jobId": "11111111-2222-3333-4444-555555555555",
    "message": null
  }
}
```

#### `config list` 選項

| 選項 | 必要 | 描述 |
| - | - | - |
| `--scid <guid>` | 或遊戲 | 遊戲設定的 SCID。 |
| `--title-id <hex-id>` | 或 SCID | XBOX 遊戲識別碼。請參閱[遊戲目標設定](#title-targeting)。 |
| `--seller-id <id>` | 否 | Partner Center 賣方 ID。 |
| `--output <format>` | 否 | `json` (預設)、`json-compact` 或 `table`。 |

#### `config status` 選項

| 選項 | 必要 | 描述 |
| - | - | - |
| `--scid <guid>` | 或遊戲 | 遊戲設定的 SCID。 |
| `--title-id <hex-id>` | 或 SCID | XBOX 遊戲識別碼。請參閱[遊戲目標設定](#title-targeting)。 |
| `--sandbox-id <id>` | 是 | 區分大小寫的沙箱 ID。預設為 `XBOX_SANDBOX_ID`，其次為已儲存的沙箱 ID。 |
| `--seller-id <id>` | 否 | Partner Center 賣方 ID。 |
| `--output <format>` | 否 | `json` (預設)、`json-compact` 或 `table`。 |

這兩個命令的表格都有 `SANDBOX`、`WORKING`、`WORKING COMMIT`、`PUBLISHED`、`PUBLISHED COMMIT` 和 `UNPUBLISHED` 欄。`config status` 會加入 `PUBLISH STATUS`，即最近一次發佈的 `status`。

#### `config list` 和 `config status` 範例

```bash theme={null}
# Every accessible sandbox for one title
xbox xbl config list \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --output table

# One sandbox, single JSON object
xbox xbl config status \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1

# Compact output for scripting
xbox xbl config status \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --output json-compact
```

### `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` 選項

| 選項 | 必要 | 描述 |
| - | - | - |
| `--view <draft\|published>` | 是 | `draft` 是 `config save` 所變更的工作設定，`published` 是玩家和測試帳戶看到的線上設定。Partner Center 使用相同的兩個名稱。 |
| `--dest <directory>` | 是 | 儲存文件和 ETag 檔案的目錄。 |
| `--type <sandbox\|account>` | 否 | 文件範圍。預設為 `sandbox`。 |
| `--scid <guid>` | `sandbox` 時為「或遊戲」 | 遊戲設定的 SCID。 |
| `--title-id <hex-id>` | `sandbox` 時為「或 SCID」 | XBOX 遊戲識別碼。請參閱[遊戲目標設定](#title-targeting)。 |
| `--sandbox-id <id>` | `sandbox` 時必要 | 區分大小寫的沙箱 ID。 |
| `--version <number>` | 否 | 正數的歷史文件集版本。預設為最新版本。 |
| `--document <filename>` | 否 | 要下載的文件檔名。重複指定以下載更多文件。預設為所有文件。 |
| `--seller-id <id>` | 否 | Partner Center 賣方 ID。 |
| `--output <format>` | 否 | `json` (預設)、`json-compact`，或包含 `TYPE`、`SANDBOX`、`VIEW`、`VERSION`、`FILES` 和 `DESTINATION` 欄的 `table`。 |

#### `config save` 選項

| 選項 | 必要 | 描述 |
| - | - | - |
| `--file <path-or-glob>` | 是 | 本機檔案或加上引號的檔名 glob。重複 `--file` 以指定更多檔案，每次一個路徑或模式：`--file a.xml --file b.xml`。每個檔案的名稱就是其文件名稱。未比對到任何檔案的值會導致命令失敗。 |
| `--type <sandbox\|account>` | 否 | 文件範圍。預設為 `sandbox`。 |
| `--scid <guid>` | `sandbox` 時為「或遊戲」 | 遊戲設定的 SCID。 |
| `--title-id <hex-id>` | `sandbox` 時為「或 SCID」 | XBOX 遊戲識別碼。請參閱[遊戲目標設定](#title-targeting)。 |
| `--sandbox-id <id>` | `sandbox` 時必要 | 區分大小寫的沙箱 ID。 |
| `--validate-only` | 否 | 驗證但不儲存。 |
| `--allow-shared-configuration` | 否 | 依 `--title-id` 儲存至其他遊戲所繫結的設定，而不詢問。請參閱[遊戲目標設定](#title-targeting)。 |
| `--etag <value>` | 否 | 儲存時所依據的 ETag。預設為已儲存的 ETag 檔案。 |
| `--force` | 否 | 覆寫自已儲存的 ETag 之後所做的變更。 |
| `--message <text>` | 否 | 儲存訊息。 |
| `--seller-id <id>` | 否 | Partner Center 賣方 ID。 |
| `--output <format>` | 否 | `json` (預設)、`json-compact`，或包含 `TYPE`、`SANDBOX`、`VALIDATE ONLY`、`CAN COMMIT`、`COMMITTED`、`FILES` 和 `ETAG FILE` 欄的 `table`。 |

當 XBOX services 無法儲存文件時 (搭配 `--validate-only` 時 `CanCommit` 為 false，否則 `Committed` 為 false)，命令仍會將結果寫入 stdout、將每個驗證訊息寫入 stderr、保持 ETag 檔案不變，並以 1 結束：

```text theme={null}
XBOX services can't save these documents:
Error: achievements2017.xml: The root namespace doesn't match the document type. (NamespaceDocTypeMismatch)
```

與最新工作文件相符的文件不算失敗：不會儲存任何項目，`ValidationInfo` 會回報 `FilesNotChangedCommit`，且命令以 0 結束。

#### `config download` 和 `config save` 範例

將最新的草稿沙箱文件下載到 `xbox-config`：

```bash theme={null}
xbox xbl config download \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --view draft --dest xbox-config
```

編輯文件之後，驗證所有文件，或只驗證您變更的兩個文件：

```bash theme={null}
xbox xbl config save \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
  --file "xbox-config/*.xml" --validate-only

xbox xbl config save \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
  --file xbox-config/achievements2017.xml --file xbox-config/localization.xml --validate-only
```

附上訊息儲存它們：

```bash theme={null}
xbox xbl config save \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
  --file "xbox-config/*.xml" --message "Update achievements"
```

下載某個文件在已發佈版本 7 中的內容：

```bash theme={null}
xbox xbl config download \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
  --view published --version 7 --document achievements.xml --dest xbox-config
```

下載帳戶的草稿文件：

```bash theme={null}
xbox xbl config download --type account --view draft --dest xbox-config --output table
```

### `config publish`

將 XBOX services 設定的工作版本發佈至沙箱的已發佈設定。發佈為非同步作業：請使用 `config publish` 開始發佈，然後對目的地沙箱執行 [`config status`](#config-list-and-config-status)，直到 `lastPublish.status` 為 `Success` 或 `Failed` 為止。

#### 來源選取

`--sandbox-id` 是目的地。來源是來源沙箱的工作版本，來源沙箱預設為目的地：

| 情境 | 效果 |
| - | - |
| 省略 `--source-sandbox-id` 或其等於 `--sandbox-id` | 發佈沙箱的最新工作版本。 |
| `--source-sandbox-id` 與 `--sandbox-id` 不同 | 將來源沙箱的最新工作版本發佈至目的地，並[取代目的地的全域遊戲儲存空間檔案](#cross-sandbox-publishing-replaces-global-title-storage-files)。 |
| `--configset <number>` | 發佈來源沙箱的該工作版本。 |

當來源沙箱有未發佈的變更時，其最新工作版本並不是該沙箱中目前上線的版本。此時，未搭配 `--configset` 的跨沙箱發佈會發出警告，並指出目前上線的版本：

```text theme={null}
Warning: XDKS.1 has unpublished changes. This publish uses its latest working version, 53; what's live in XDKS.1 is working version 52. To publish that instead, add --configset 52.
```

若要準確升級來源中目前上線的內容，請先搭配 `--validate-only` 執行，並加入它建議的 `--configset`。在 JSON 輸出中，`SourceVersion` 是使用的工作版本，`sourceHasUnpublishedChanges` 指出它是否與來源中目前上線的內容不同，而 `sourceLiveVersion` 是找到時該處目前上線的版本。

全遊戲發佈 (`--sandbox-id HIDDEN`) 一律會發佈 `ALL` 中的最新工作設定，因此不採用 `--source-sandbox-id` 或 `--configset`。若要查看哪個版本會上線，請先執行 `config status --sandbox-id ALL` 並讀取 `workingVersion`。

#### 確認

在下列情況下，`config publish` 會在發佈之前詢問：

| 發佈 | 詢問原因 |
| - | - |
| `--sandbox-id RETAIL` | 發佈完成時，玩家就會看到變更。 |
| `--sandbox-id CERT` 或 `CERT.DEBUG` | XBOX 認證會在這些沙箱中進行測試。 |
| `--sandbox-id HIDDEN` | 發佈全遊戲設定，每個沙箱 (包括 RETAIL) 都會使用此設定。 |
| `--source-sandbox-id` 與 `--sandbox-id` 不同 | 會先取代目的地中同名的工作文件，以及其[全域遊戲儲存空間檔案](#cross-sandbox-publishing-replaces-global-title-storage-files)。 |

在終端機中，它會描述發佈內容並詢問。沒有終端機時，它會拒絕並以 1 結束。`--confirm` (`--yes`、`-y`) 會略過此問題，而 `--validate-only` 絕不會詢問。請參閱[安全性和破壞性作業](https://docs.xbox.com/zh-TW/tools/xbox-cli/safety.md)。

在詢問 RETAIL 發佈之前，它會先驗證發佈並列出[它新增的成就](#achievements-a-retail-publish-adds)。如果您回答是，它會發佈它所驗證的工作版本，因此上線的內容就是列出的內容：

```console theme={null}
$ xbox xbl config publish --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id CERT --sandbox-id RETAIL
This publish adds 2 achievements to RETAIL: 1, 2. Once they're live in RETAIL, achievements can't be removed, and their unlock rules and gamerscore can't change.
This publishes working version 52 of CERT's configuration to RETAIL for SCID aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.
RETAIL is live: players see the change when the publish finishes.
Publishing from CERT first replaces RETAIL's working documents that have the same names.
Warning: publishing from CERT to RETAIL replaces RETAIL's global title storage files with CERT's. Files with the same path are overwritten, files only CERT holds are added, and files only RETAIL holds are deleted. Deleted files can't be recovered.

Publish to RETAIL? [y/N]:
```

當該驗證失敗時，它不會發佈任何內容，也不會詢問。因此在終端機中，依 `--title-id` 對其他遊戲所繫結之設定進行的 RETAIL 發佈需要 `--allow-shared-configuration`。搭配 `--confirm` 時不會顯示清單，因此請先執行 `--validate-only` 以查看清單。

#### RETAIL 發佈新增的成就

成就在 RETAIL 中上線後，就無法移除，其解除鎖定規則和玩家分數也無法變更。因此，RETAIL 發佈會指出它新增了哪些 RETAIL 尚未擁有的成就 ID：

* 搭配 `--validate-only` 時，清單會寫入 stderr，而 JSON 輸出會在 `achievementChanges.added` 中包含此清單。
* 在終端機中未搭配 `--validate-only` 時，清單會出現在問題之前，如[確認](#confirmation)中所示。

```console theme={null}
$ xbox xbl config publish --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id CERT --sandbox-id RETAIL --validate-only
This publish would add 2 achievements to RETAIL: 1, 2. Once they're live in RETAIL, achievements can't be removed, and their unlock rules and gamerscore can't change.
```

未新增任何成就的發佈也會指出這一點。其他沙箱不會列出成就。

#### 重新發佈

`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` 中。

```text theme={null}
XBOX services warning (FirstRetailPublishWithoutEffectiveEmbargo): This is the first time these Xbox Gameplay Settings will be published to RETAIL, and no embargo is configured.
```

驗證失敗時，`config publish` 會以 1 結束，並在 `validation` 底下列出每個訊息，如[錯誤](#errors)中所示。

#### 跨沙箱發佈會取代全域遊戲儲存空間檔案

> [!CAUTION]
>
> 從一個沙箱發佈至另一個沙箱，會讓目的地的全域遊戲儲存空間檔案成為來源檔案的完全複本。只有目的地才有的檔案會被刪除，且無法復原。

全域檔案是遊戲的每位玩家都會讀取的檔案，例如新聞摘要和地圖：

| 檔案 | 來源 | 發佈前的目的地 | 發佈後的目的地 |
| - | - | - | - |
| `news.json` | 存在 | 存在 | 以來源的複本覆寫 |
| `tuning.cfg` | 存在 | — | 已新增 |
| `maps.bin` | — | 存在 | **已刪除** |

複本會採用發佈執行時來源所包含的任何內容。玩家自己的資料不受影響，而相同沙箱內的發佈不會變更全域檔案。若要保留目的地檔案，請在發佈之前將它新增至來源沙箱。

每次跨沙箱發佈都會將此警告寫入 stderr (包括搭配 `--validate-only` 時)，並將它包含在[確認](#confirmation)問題中：

```text theme={null}
Warning: publishing from SANDBOX1 to SANDBOX2 replaces SANDBOX2's global title storage files with SANDBOX1's. Files with the same path are overwritten, files only SANDBOX1 holds are added, and files only SANDBOX2 holds are deleted. Deleted files can't be recovered.
```

#### `config publish` 選項

| 選項 | 別名 | 必要 | 描述 |
| - | - | - | - |
| `--scid <guid>` | — | 或遊戲 | 遊戲設定的 SCID。 |
| `--title-id <hex-id>` | — | 或 SCID | XBOX 遊戲識別碼。請參閱[遊戲目標設定](#title-targeting)。 |
| `--sandbox-id <id>` | — | 是 | 目的地沙箱 ID。預設為 `XBOX_SANDBOX_ID`，其次為已儲存的沙箱 ID。 |
| `--source-sandbox-id <id>` | — | 否 | 來源沙箱 ID。預設為 `--sandbox-id`。不允許與 `--sandbox-id HIDDEN` 搭配使用。 |
| `--validate-only` | — | 否 | 驗證但不發佈。若為 RETAIL，也會列出[發佈新增的成就](#achievements-a-retail-publish-adds)。 |
| `--allow-shared-configuration` | — | 否 | 依 `--title-id` 發佈至其他遊戲所繫結的設定，而不詢問。請參閱[遊戲目標設定](#title-targeting)。 |
| `--configset <number>` | — | 否 | 來源沙箱的正數工作版本。預設為其最新版本。不允許與 `--sandbox-id HIDDEN` 搭配使用。 |
| `--republish` | — | 否 | 即使沒有任何變更也進行完整發佈，或發佈至在移轉後遭鎖定的 RETAIL。請參閱[重新發佈](#republishing)。 |
| `--confirm` | `--yes`、`-y` | 否 | 發佈而不詢問。請參閱[確認](#confirmation)。 |
| `--seller-id <id>` | — | 否 | Partner Center 賣方 ID。 |
| `--output <format>` | `-o` | 否 | `json` (預設)、`json-compact`，或包含 `STATUS`、`SOURCE`、`DESTINATION`、`VALIDATE ONLY` 和 `SOURCE VERSION` 欄的 `table`。 |

#### `config publish` 範例

驗證對 SANDBOX1 的發佈，但不發佈：

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --validate-only
```

發佈 SANDBOX1 的最新工作設定，使其在 SANDBOX1 中上線：

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1
```

將 SANDBOX1 的最新工作版本發佈至 SANDBOX2。這也會以 SANDBOX1 的全域遊戲儲存空間檔案取代 SANDBOX2 的全域遊戲儲存空間檔案：

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id SANDBOX1 --sandbox-id SANDBOX2
```

將 SANDBOX1 的工作版本 42 發佈至 SANDBOX2：

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --source-sandbox-id SANDBOX1 --sandbox-id SANDBOX2 --configset 42
```

驗證從 CERT 到 RETAIL 的發佈，這會列出它新增的成就：

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id CERT --sandbox-id RETAIL --validate-only
```

然後將輸出的 `SourceVersion` 作為 `--configset` 傳遞，以發佈您所驗證的版本，且不顯示提示：

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id CERT --sandbox-id RETAIL --configset 52 --confirm
```

即使沒有任何變更，仍再次發佈 SANDBOX1：

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --republish
```

檢查對 SANDBOX2 的發佈：

```bash theme={null}
xbox xbl config status \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX2 --output table
```

***

## schema

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

| 命令 | 描述 |
| - | - |
| `schema list` | 列出每個結構描述類型。 |
| `schema list --type <type>` | 列出一個結構描述類型的版本。 |
| `schema get --type <type>` | 取得結構描述類型的一個版本：其類型、版本和命名空間。預設為最新版本。 |
| `schema download --dest <directory>` | 將 XSD 儲存至目錄：一個版本、一個類型的每個版本，或每個類型的每個版本。 |
| `schema download --type <type> --version <n> --dest -` | 將一個 XSD 寫入 stdout。 |

### `schema list` 選項

| 選項 | 必要 | 描述 |
| - | - | - |
| `--type <type>` | 否 | 要列出其版本的結構描述類型。省略它即可列出所有類型。 |
| `--output <format>` | 否 | `json` (預設)、`json-compact`，或包含 `TYPE`、`VERSION`、`NAMESPACE`、`PATH` 和 `BYTES` 欄的 `table`。 |

### `schema get` 選項

| 選項 | 必要 | 描述 |
| - | - | - |
| `--type <type>` | 是 | 結構描述類型。 |
| `--version <number>` | 否 | 正數的結構描述版本。預設為該類型的最新版本。 |
| `--output <format>` | 否 | `json` (預設)、`json-compact`，或包含 `TYPE`、`VERSION` 和 `NAMESPACE` 欄的 `table`。 |

`schema get` 會寫入一個 JSON 物件：

```json theme={null}
{
  "type": "achievements2017",
  "version": 1,
  "namespace": "http://config.mgt.xboxlive.com/schema/achievements2017/1"
}
```

### `schema download` 選項

| 選項 | 必要 | 描述 |
| - | - | - |
| `--dest <directory>` | 是 | 儲存 XSD 檔案的目錄，或使用 `-` 將一個 XSD 寫入 stdout。`-` 需要同時指定 `--type` 和 `--version`。 |
| `--type <type>` | 否 | 結構描述類型。省略它即可下載每個類型。 |
| `--version <number>` | 否 | 正數的結構描述版本。需要 `--type`。省略它即可下載每個版本。 |
| `--output <format>` | 否 | `json` (預設)、`json-compact`，或包含 `TYPE`、`VERSION`、`NAMESPACE`、`PATH` 和 `BYTES` 欄的 `table`。 |

每個結構描述都會儲存為 `<type>_<version>.xsd`，其中類型為小寫，而命令會列印儲存的路徑。使用 `--dest -` 時，它會改為將原始 XSD 寫入 stdout，且 `--output` 不適用。

### `schema` 範例

```bash theme={null}
# List every schema type
xbox xbl schema list

# List versions of one type, as a table
xbox xbl schema list --type achievements2017 --output table

# Get the latest version of one type
xbox xbl schema get --type achievements2017

# Redirect one XSD straight to a file
xbox xbl schema download --type achievements2017 --version 1 --dest - > achievements2017_1.xsd

# Save one XSD into a directory
xbox xbl schema download --type achievements2017 --version 1 --dest schemas

# Download every version of one schema type
xbox xbl schema download --type achievements2017 --dest schemas

# Download every version of every schema type
xbox xbl schema download --dest schemas
```

***

## 典型的設定往返流程

1. 尋找您可以存取的沙箱：

   ```bash theme={null}
   xbox sandbox list --output table
   ```

2. 查看工作設定和已發佈設定的狀態：

   ```bash theme={null}
   xbox xbl config list \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --output table
   ```

3. 下載草稿文件集，這也會儲存 `SANDBOX1.etag`：

   ```bash theme={null}
   xbox xbl config download \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --view draft --dest xbox-config
   ```

4. 編輯 `xbox-config` 中的文件，然後驗證它們：

   ```bash theme={null}
   xbox xbl config save \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
     --file "xbox-config/*.xml" --validate-only
   ```

5. 儲存它們：

   ```bash theme={null}
   xbox xbl config save \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
     --file "xbox-config/*.xml" --message "Update configuration"
   ```

6. 在 SANDBOX1 中發佈它們：

   ```bash theme={null}
   xbox xbl config publish \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1
   ```

7. 檢查發佈，並重複執行直到其狀態為 `Success` 或 `Failed` 為止：

   ```bash theme={null}
   xbox xbl config status \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --output table
   ```


## Related topics

- [設定 XBOX services](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/xbox-services.md)
- [設定預購產品](https://docs.xbox.com/zh-TW/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-configuring-pre-orders.md)
- [遊戲設定](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/game-setup-overview.md)
- [在 Partner Center 中設定 XBOX 服務設定](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/portal-config/live-config-xbl-setup.md)
- [在 Partner Center 中設定 XBOX 產品](https://docs.xbox.com/zh-TW/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-product-onboarding-and-configuration.md)
