跳转到主要内容
XBOX 测试帐户是为 Partner Center 卖家按批次创建的。这些命令可创建、更新和删除批次,跟踪创建帐户的作业,以及读取批次和其中的帐户。它们无法更改单个帐户,并且从不返回密码。你的帐户需要具有该卖家的 Partner Center 测试帐户角色。 每个命令都接受 --seller-id。如果未指定,命令会使用 XBOX_SELLER_ID 或通过 xbox context set 保存的卖家,然后使用你唯一的卖家;如果你有多个卖家,请传递 --seller-id。

命令

batch create、batch update 和 batch delete 在进行任何更改之前都会进行询问,并且只发送一次,从不重试。请参阅安全性和破坏性操作。

用于读取批次的选项

标记在 JSON 输出和错误代码(例如 test_account_keyword_invalid)中显示为 keywords。--tag 匹配整个标记,而不是标记的一部分。 如果你无法读取卖家的所有批次,不会收到错误:batch list 仅返回你创建的批次。

已过期的批次

批次的 accessExpirationDate(即其沙盒访问权限结束的日期)一过,该批次即过期。没有日期的批次永不过期。过期并不说明帐户是否仍可登录。 batch list --expired 会读取卖家的整个列表以查找已过期的批次,因此对于拥有许多批次的卖家,速度会较慢。它不能与 --include-sandboxes 结合使用;请对已过期的批次运行 batch get 以查看其沙盒访问权限。

响应结构

list 返回:
  • 除非传递 --include-sandboxes,否则 keywords 和 sandboxAccess 为 null。get 始终返回它们。
  • isComplete 表示创建作业已停止,而不表示每个帐户都已创建。请将 get 中的帐户数与 batchSize 进行比较,并读取 progress 以获取状态消息。
  • createdBy 是数字形式的 Partner Center 用户 ID。
  • jobId 是批次正在运行的作业,作业停止后为 null。更新和删除作业也会显示在此处,但只有创建作业可以使用 job wait 进行跟踪。
get 返回相同的批次对象及其帐户:
每个帐户仅包含 xuid、email、gamertag 和 isDeleted。xuid 是字符串。

读取批次时的错误

batch list、batch get 和 test-account get 失败时以 1 退出。当服务返回 JSON 错误时,stderr 会收到一个 JSON 错误,其中包含 status、title、detail、code(如果响应包含)及其 correlationId;大多数错误会在 detail 中添加提示。其他失败会打印一行文本。在解析 stderr 之前,请检查退出代码。

查找帐户

test-account get <email> 说明包含某个帐户的批次是否已过期。电子邮件必须以 @xboxtest.com 结尾。该命令会搜索电子邮件模板与帐户名称匹配的最新 10 个批次。如果在其中找不到该帐户,它会说明未搜索较早的批次,并打印 batch list 和 batch get 命令,供你自行检查。 它返回以下内容(此处已缩短);batch 包含 batch list 返回的每个批次字段:
批次未过期时,expiredOn 为 null。仅当不存在有效副本时才会报告已删除的帐户,并设置 account.isDeleted。只要找到帐户,无论是否过期,该命令都以 0 退出,因此脚本应读取 expired。在以下情况下,它以 1 退出:
  • 该帐户不在你可以看到的批次中。它可能属于其他卖家,因此请尝试 --seller-id;或者其批次由其他开发人员创建,而你无法读取该卖家的所有批次。
  • 该电子邮件出现在多个批次中。stderr 会为每个批次列出一个 batch get 命令。
  • 某个请求失败,如读取批次时的错误中所述。

创建批次

batch create 启动一个创建帐户的作业,然后等待其停止。在批次被删除之前,这些帐户会计入卖家的测试帐户限制。 在终端中,该命令会显示安全问题选择器,列出它将发送的值(包括你省略的选项的默认值),并要求你确认。然后,它会提示你输入密码和安全答案,进行登录并发送请求。--confirm (--yes, -y) 仅跳过确认。 如果没有终端,请传递 --password-file、--security-answer-file 和 --confirm。如果不使用 --confirm,该命令会打印这些值,然后拒绝执行,不发送任何内容。

选择安全问题

在终端中,如果你既未传递 --security-question 也未传递 --security-answer-file,该命令会显示这些问题的编号选择器。按 Enter 会选择第一个问题。若要在不使用选择器的情况下选择问题,请使用 --security-question 传递其文本:
  1. What is your favorite hobby?(你最喜欢的爱好是什么?)
  2. Who is your favorite athlete?(你最喜欢的运动员是谁?)
  3. What is your maternal grandmother’s first name?(你外祖母的名字是什么?)
  4. What was your childhood best friend’s first name?(你童年最好的朋友叫什么名字?)
  5. What was the name of your first pet?(你的第一只宠物叫什么名字?)
  6. What is your current best friend’s first name?(你现在最好的朋友叫什么名字?)
  7. What was your favorite city to visit as a child?(你小时候最喜欢去哪个城市?)
如果没有终端,或者提供了答案文件但未指定问题,则问题为 What is your favorite hobby?。在选择器中按 Ctrl+C 会取消操作,不会创建任何内容。选择问题并不代表确认创建。

机密

密码和安全答案从不作为选项值或环境变量接受,因此它们不会出现在 shell 历史记录、进程列表和日志中。每一项都来自:
  • 其 --password-file 或 --security-answer-file。会删除末尾的单个换行符。
  • 用 - 代替路径,从 stdin 读取。两者中只有一个可以读取 stdin。
  • 如果没有文件选项,则在终端中显示提示,且不回显你键入的内容。
密码必须为 8 到 16 个字符,并且至少包含以下四类中的三类:小写字母、大写字母、数字和符号。下划线不算作符号。密码不能与安全答案相同。

等待和退出代码

等待期间,该命令会将进度打印到 stderr。它会将最终作业写入 stdout,结构与 job get 相同。

结果未知时

当 CLI 无法判断服务是否创建了批次时(例如在发送请求后连接断开,或服务返回 5xx 错误),它会以 3 退出。它从不再次发送创建请求。stderr 会打印请求开始的时间 (UTC) 以及以下步骤:
  1. 等待几分钟;仍在创建中的批次可能尚未列出。
  2. 运行 xbox test-account batch list --mine --email-prefix <prefix>,查找具有相同电子邮件前缀和模板、且在该时间或之后创建的批次。
  3. 如果该批次的 jobId 已设置,请使用 xbox test-account job wait <job-id> --batch-id <batch-id> 跟踪它。如果 jobId 为 null,则作业已停止;请使用 xbox test-account batch get <batch-id> 检查它。
  4. 仅当不存在此类批次时才再次创建。
打印的命令会保留你使用的卖家、配置文件和登录选项,因此你可以按原样复制它们。

创建时的错误

失败时会将 JSON 错误写入 stderr,其中包含 status、title、detail 以及 code(如果响应包含)。请根据 code 而不是 detail 进行分支处理。

跟踪创建作业

作业一被接受,batch create 就会打印批次 ID 和作业 ID。作业可能会运行数天,因此你可以随时停止等待,稍后再跟踪它: 两者都返回作业:
state 为 running、succeeded 或 failed。作业失败时,errorCode 为 test_account_job_failed。job wait 会重试临时读取失败,例如限制或连接中断。

跟踪作业时的错误

以下错误代码指向作业 ID、--batch-id 或 --seller-id:

更新批次

batch update 会更改批次中的每个帐户:它可以授予帐户对更多沙盒的访问权限、撤销访问权限、调整该访问权限的过期时间,以及添加或替换批次的标记。然后,它会等待批次显示这些更改。 在终端中,该命令首先会在批次当前值旁边显示每项请求的更改,在批次上仍有作业运行时发出警告,然后进行询问。传递 --confirm (--yes, -y) 可跳过提示。如果没有终端且未使用 --confirm,它会打印更改,然后拒绝执行,不发送任何内容。 至少传递一项更改。一个批次最多可以有 20 个标记。--replace-tags 和 --clear-tags 会保留记录创建该批次的工具的标记,该标记不计入限制。更改沙盒或过期时间需要具有这些沙盒的访问权限;延长过期时间需要具有批次上每个沙盒的访问权限。 更新完成后,该命令会返回批次的值:
批次显示更改后,state 为 updated;使用 --no-wait 或等待先结束时,state 为 updating。当批次已具有每个请求的值时,不会进行任何更改:state 为 unchanged,jobId 为 null,并且命令以 0 退出。无法使用 job get 或 job wait 跟踪更新作业。

更新时的等待和退出代码

更新时的错误

无代码的 404 或 405 表示更新批次功能不可用。

删除批次

batch delete 删除整个批次,然后等待其消失。批次中的每个帐户都会失去其沙盒访问权限,并且其测试帐户记录会被删除。这些帐户的 Microsoft 帐户和 XBOX 个人资料不会被关闭。 在终端中,该命令首先会显示批次的电子邮件模板、大小和创建者,在批次上仍有作业运行时发出警告,然后进行询问。传递 --confirm (--yes, -y) 可跳过提示。如果没有终端且未使用 --confirm,它会打印将要删除的内容,然后拒绝执行,不发送任何内容。不支持批量删除;请一次删除一个批次。 该命令返回:
批次消失后,state 为 deleted;使用 --no-wait 或等待先结束时,state 为 deleting。无法使用 job get 或 job wait 跟踪删除作业;删除运行期间,批次会显示其 jobId。

删除时的等待和退出代码

删除时的错误

无代码的 404 或 405 表示删除批次功能不可用。

表格输出

每个命令都接受 --output table。时间以 UTC 显示,摘要行会写入 stderr,因此 stdout 仅包含表格。

示例

以下命令列出并读取批次、帐户和作业:
创建一个包含五个帐户的批次。该命令会提示你输入密码和安全答案,然后要求你确认:
以无人参与方式创建批次,从文件读取机密,不显示提示,并最多等待 30 分钟:
最多等待两小时以完成创建作业:
添加一个沙盒,并设置沙盒访问权限的过期时间。该命令会显示更改,要求你确认,然后等待批次显示这些更改:
以无人参与方式添加两个标记,且不等待:
将所有标记替换为一个标记:
删除批次。该命令会显示批次,要求你确认,然后等待其消失:
以无人参与方式删除其他开发人员创建的批次,且不等待:
最后修改于 2026年11月19日