> ## 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 服务配置

> 管理 XBOX 服务配置,包括其状态、文档、发布、架构和成就图像。

`xbl` 命令系列属于实验性功能。其 CLI 接口可能会根据反馈而更改或被删除。

`xbox xbl` 管理 XBOX 服务配置(工作配置和已发布配置的状态、配置文档、发布以及配置架构)以及成就图像。若要列出配置命令所针对的沙盒,请使用 [`xbox sandbox list`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/sandbox)。

这些命令使用的配置与 Partner Center 编辑的配置相同。有关每项 XBOX 服务功能的作用及其配置方式,请参阅 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-CN/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-CN/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 游戏 ID,但不能同时接受两者。如果两者都未指定,它们会使用 `XBOX_TITLE_ID` 或已保存的 `title-id`;请参阅[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。`--scid` 会忽略这两者。

* `--title-id` 为十六进制,与 [`game get`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/game) 显示的形式相同:`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,然后使用它来读取、下载和验证该游戏在 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-CN/tools/xbox-cli/cli-for-agents.md#rate-limits)。

当 XBOX 服务验证拒绝配置时,错误会在 `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 服务配置。沙盒包含一个工作配置(由 `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>` | 或游戏 ID | 游戏配置的 SCID。 |
| `--title-id <hex-id>` | 或 SCID | XBOX 游戏 ID。请参阅[游戏定位](#title-targeting)。 |
| `--seller-id <id>` | 否 | Partner Center 卖家 ID。 |
| `--output <format>` | 否 | `json`(默认)、`json-compact` 或 `table`。 |

#### `config status` 选项

| 选项 | 必需 | 说明 |
| - | - | - |
| `--scid <guid>` | 或游戏 ID | 游戏配置的 SCID。 |
| `--title-id <hex-id>` | 或 SCID | XBOX 游戏 ID。请参阅[游戏定位](#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 服务配置文档集。文档集属于沙盒(默认值,需要 SCID 或游戏 ID 以及 `--sandbox-id`)或属于帐户(`--type account`,不接受 SCID、游戏 ID 或沙盒)。

`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`,或使用游戏 ID | 游戏配置的 SCID。 |
| `--title-id <hex-id>` | 对于 `sandbox`,或使用 SCID | XBOX 游戏 ID。请参阅[游戏定位](#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>` | 是 | 本地文件或带引号的文件名通配模式。重复 `--file` 可指定更多文件,每个选项一个路径或模式:`--file a.xml --file b.xml`。每个文件的名称即为其文档名称。与任何文件都不匹配的值会导致命令失败。 |
| `--type <sandbox\|account>` | 否 | 文档范围。默认为 `sandbox`。 |
| `--scid <guid>` | 对于 `sandbox`,或使用游戏 ID | 游戏配置的 SCID。 |
| `--title-id <hex-id>` | 对于 `sandbox`,或使用 SCID | XBOX 游戏 ID。请参阅[游戏定位](#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 服务无法保存文档时(使用 `--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 服务配置的工作版本发布到沙盒的已发布配置。发布是异步的:使用 `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-CN/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 服务的验证诊断(例如首次在没有禁运的情况下发布到 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>` | — | 或游戏 ID | 游戏配置的 SCID。 |
| `--title-id <hex-id>` | — | 或 SCID | XBOX 游戏 ID。请参阅[游戏定位](#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 服务配置文档架构。

| 命令 | 说明 |
| - | - |
| `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 服务](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/xbox-services.md)
- [XBOX 服务配置 ID（面向托管合作伙伴）](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/portal-config/live-service-config-ids-mp.md)
- [在 Partner Center 中配置 XBOX 事件](https://docs.xbox.com/zh-CN/publishing/game-publishing/how-to/data-platform-2013/how-to-configure-events-2013.md)
- [XBOX 服务登录故障排除](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/identity/auth/live-troubleshooting-sign-in.md)
- [在 Partner Center 中配置 XBOX 数据平台 2013](https://docs.xbox.com/zh-CN/publishing/game-publishing/how-to/data-platform-2013/how-to-configure-data-platform-2013.md)
