xbl 命令系列属于实验性功能。其 CLI 接口可能会根据反馈而更改或被删除。
xbox xbl 管理 XBOX 服务配置(工作配置和已发布配置的状态、配置文档、发布以及配置架构)以及成就图像。若要列出配置命令所针对的沙盒,请使用 xbox sandbox list。
这些命令使用的配置与 Partner Center 编辑的配置相同。有关每项 XBOX 服务功能的作用及其配置方式,请参阅 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 游戏 ID,但不能同时接受两者。如果两者都未指定,它们会使用 XBOX_TITLE_ID 或已保存的 title-id;请参阅上下文。--scid 会忽略这两者。
--title-id为十六进制,与game get显示的形式相同: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 命令都接受 --output table,以及 json(默认)和 json-compact。每个命令的选项表都列出了其表格列。
错误
失败的请求以 1 退出,并将 JSON 错误写入 stderr,其中包含status、title、detail 以及 code(如果服务发送了)。请根据 status 或 code 而不是 detail 的措辞进行分支处理。429 错误包含 retryAfterSeconds;请参阅速率限制。
当 XBOX 服务验证拒绝配置时,错误会在 validation 下列出每条消息:
--validate-only 时,config save 和 config publish 会说明失败的更改是否可能已被应用:
以 3 退出时,请勿重新提交。stderr 会打印一个用于检查的只读命令:对于保存,是
config download --view draft,用于与你保存的文件进行比较;对于发布,是 config status。
config
检查、下载、保存和发布一个 SCID 的 XBOX 服务配置。沙盒包含一个工作配置(由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 服务配置文档集。文档集属于沙盒(默认值,需要 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 选项
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 启动发布,然后针对目标沙盒运行 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 服务的验证诊断(例如首次在没有禁运的情况下发布到 RETAIL 时的警告)会写入 stderr,每行一条。JSON 输出会将它们保存在ValidationResult 中。
config publish 以 1 退出,并在 validation 下列出每条消息,如错误中所示。
跨沙盒发布会替换全局游戏存储文件
从一个沙盒发布到另一个沙盒会使目标的全局游戏存储文件成为源的精确副本。仅目标拥有的文件会被删除,且无法恢复。
复制会获取发布运行时源所包含的任何内容。玩家自己的数据不受影响,同一沙盒内的发布也不会改动全局文件。若要保留某个目标文件,请在发布之前将其添加到源沙盒。
每次跨沙盒发布都会将此警告写入 stderr(包括使用
--validate-only 时),并将其包含在确认询问中:
config publish 选项
config publish 示例
验证到 SANDBOX1 的发布而不实际发布:
SourceVersion 作为 --configset 传递,以在不显示提示的情况下发布你验证过的版本:
schema
发现和下载 XBOX 服务配置文档架构。schema list 选项
schema get 选项
schema get 写入一个 JSON 对象:
schema download 选项
每个架构都保存为
<type>_<version>.xsd(类型为小写),并且该命令会打印已保存的路径。使用 --dest - 时,它会改为将原始 XSD 写入 stdout,并且 --output 不适用。
schema 示例
典型的配置往返流程
-
查找你可以访问的沙盒:
-
查看工作配置和已发布配置的状态:
-
下载草稿文档集,这也会保存
SANDBOX1.etag: -
编辑
xbox-config中的文档,然后验证它们: -
保存它们:
-
在 SANDBOX1 中发布它们:
-
检查发布,并重复此操作,直到其状态为
Success或Failed:
