> ## 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 测试帐户是为 Partner Center 卖家按批次创建的。这些命令可创建、更新和删除批次,跟踪创建帐户的作业,以及读取批次和其中的帐户。它们无法更改单个帐户,并且从不返回密码。你的帐户需要具有该卖家的 Partner Center 测试帐户角色。

每个命令都接受 `--seller-id`。如果未指定,命令会使用 `XBOX_SELLER_ID` 或通过 [`xbox context set`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context) 保存的卖家,然后使用你唯一的卖家;如果你有多个卖家,请传递 `--seller-id`。

## 命令

| 命令 | 说明 |
| - | - |
| `test-account batch list` | 列出卖家的测试帐户批次,最新的排在最前面。 |
| `test-account batch get <batch-id>` | 显示一个批次及其帐户。 |
| `test-account get <email>` | 查找包含某个帐户的批次,并报告其访问权限是否已过期。请参阅[查找帐户](#looking-up-an-account)。 |
| `test-account batch create` | 创建一批测试帐户并等待其创建作业。请参阅[创建批次](#creating-a-batch)。 |
| `test-account batch update <batch-id>` | 更改批次的沙盒、沙盒访问权限过期时间或标记,并等待批次显示这些更改。请参阅[更新批次](#updating-a-batch)。 |
| `test-account batch delete <batch-id>` | 删除批次并等待其消失。请参阅[删除批次](#deleting-a-batch)。 |
| `test-account job get <job-id>` | 显示一次创建作业的状态。 |
| `test-account job wait <job-id>` | 等待创建作业,直到其停止运行或等待超时。 |

`batch create`、`batch update` 和 `batch delete` 在进行任何更改之前都会进行询问,并且只发送一次,从不重试。请参阅[安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)。

## 用于读取批次的选项

| 选项 | 命令 | 说明 |
| - | - | - |
| `--seller-id <id>` | `batch list`、`batch get`、`test-account get` | Partner Center 卖家 ID。 |
| `--mine` | `list` | 仅限你创建的批次。不能与 `--created-by-id` 结合使用。 |
| `--created-by-id <id>` | `list` | 仅限由此数字 Partner Center 用户 ID 创建的批次。不能与 `--mine` 结合使用。 |
| `--email-prefix <text>` | `list` | 仅限电子邮件模板以此文本开头的批次,不区分大小写。 |
| `--tag <tag>` | `list` | 仅限具有此确切标记的批次。接受一个值。 |
| `--state <state>` | `list` | `complete` 或 `pending`,小写。 |
| `--limit <count>` | `list` | 最多返回此数量的最新匹配批次。 |
| `--include-sandboxes` | `list` | 同时返回每个批次的标记 (`keywords`) 和 `sandboxAccess`。如果不使用 `--limit`,则最多列出最新的 10 个匹配批次;设置 `--limit` 可列出更多。 |
| `--expired` | `list` | 仅限沙盒访问权限已过期的批次。此时 `--limit` 应用于已过期的批次。请参阅[已过期的批次](#expired-batches)。 |
| `--output <format>` | `batch list`、`batch get`、`test-account get` | `json`(默认)、`json-compact` 或 `table`。 |

标记在 JSON 输出和错误代码(例如 `test_account_keyword_invalid`)中显示为 `keywords`。`--tag` 匹配整个标记,而不是标记的一部分。

如果你无法读取卖家的所有批次,不会收到错误:`batch list` 仅返回你创建的批次。

### 已过期的批次

批次的 `accessExpirationDate`(即其沙盒访问权限结束的日期)一过,该批次即过期。没有日期的批次永不过期。过期并不说明帐户是否仍可登录。

`batch list --expired` 会读取卖家的整个列表以查找已过期的批次,因此对于拥有许多批次的卖家,速度会较慢。它不能与 `--include-sandboxes` 结合使用;请对已过期的批次运行 `batch get` 以查看其沙盒访问权限。

## 响应结构

`list` 返回:

```json theme={null}
{
  "batches": [
    {
      "id": 123456,
      "emailTemplate": "ABCDEF-smoke",
      "batchSize": 2,
      "createdBy": 7654321,
      "familyPermission": "Adult",
      "creationDate": "2026-09-12T04:00:00+00:00",
      "accessExpirationDate": "2027-03-12T04:00:00+00:00",
      "locale": "en-US",
      "keywords": null,
      "sandboxAccess": null,
      "isComplete": true,
      "jobId": null,
      "progress": null
    }
  ]
}
```

* 除非传递 `--include-sandboxes`,否则 `keywords` 和 `sandboxAccess` 为 `null`。`get` 始终返回它们。
* `isComplete` 表示创建作业已停止,而不表示每个帐户都已创建。请将 `get` 中的帐户数与 `batchSize` 进行比较,并读取 `progress` 以获取状态消息。
* `createdBy` 是数字形式的 Partner Center 用户 ID。
* `jobId` 是批次正在运行的作业,作业停止后为 `null`。更新和删除作业也会显示在此处,但只有创建作业可以使用 [`job wait`](#following-a-creation-job) 进行跟踪。

`get` 返回相同的批次对象及其帐户:

```json theme={null}
{
  "batch": { "id": 123456, "batchSize": 2, "isComplete": true },
  "accounts": [
    {
      "xuid": "2814600000000001",
      "email": "ABCDEF-smoke-1@example.com",
      "gamertag": "SmokeOne",
      "isDeleted": false
    }
  ]
}
```

每个帐户仅包含 `xuid`、`email`、`gamertag` 和 `isDeleted`。`xuid` 是字符串。

## 读取批次时的错误

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

| 状态 | 含义 |
| - | - |
| 400 | 某个筛选器被拒绝,或者你有多个卖家但未选择其中一个;请传递 `--seller-id`。 |
| 403 | 你不是此卖家的成员,或者没有该卖家的 Partner Center 测试帐户角色。对于 `batch get`,该批次可能属于其他卖家(请传递 `--seller-id`),或者由其他开发人员创建而你无法读取该卖家的所有批次。如果错误要求你重新登录,请重新登录。 |
| 404 | 不存在具有该 ID 的批次,或者测试帐户尚不可用。 |
| 429 | 代码为 `rate_limited` 时,表示你在短时间内发送的请求过多。错误包含 `retryAfterSeconds`;请参阅[速率限制](https://docs.xbox.com/zh-CN/tools/xbox-cli/cli-for-agents.md#rate-limits)。 |
| 502 | 服务无法完成请求;请重试。当你没有测试帐户角色,或者对于 `batch get` 而言批次由其他开发人员创建时,服务可能返回 502 而不是 403。使用个人 Microsoft 帐户时,重试无济于事;请参阅[已知问题](https://docs.xbox.com/zh-CN/tools/xbox-cli/known-issues.md#some-commands-dont-work-yet-with-a-personal-microsoft-account)。 |
| 503 | 测试帐户不可用。 |
| 504 | 服务未及时响应;请重试。 |

## 查找帐户

`test-account get <email>` 说明包含某个帐户的批次是否已过期。电子邮件必须以 `@xboxtest.com` 结尾。该命令会搜索电子邮件模板与帐户名称匹配的最新 10 个批次。如果在其中找不到该帐户,它会说明未搜索较早的批次,并打印 `batch list` 和 `batch get` 命令,供你自行检查。

它返回以下内容(此处已缩短);`batch` 包含 `batch list` 返回的每个批次字段:

```json theme={null}
{
  "account": { "xuid": "2814600000000001", "email": "ABCD-tester00007@xboxtest.com", "gamertag": "TesterSeven", "isDeleted": false },
  "batch": { "id": 123456, "emailTemplate": "ABCD-tester", "accessExpirationDate": "2026-01-01T00:00:00+00:00" },
  "expired": true,
  "expiredOn": "2026-01-01T00:00:00+00:00"
}
```

批次未过期时,`expiredOn` 为 `null`。仅当不存在有效副本时才会报告已删除的帐户,并设置 `account.isDeleted`。只要找到帐户,无论是否过期,该命令都以 0 退出,因此脚本应读取 `expired`。在以下情况下,它以 1 退出:

* 该帐户不在你可以看到的批次中。它可能属于其他卖家,因此请尝试 `--seller-id`;或者其批次由其他开发人员创建,而你无法读取该卖家的所有批次。
* 该电子邮件出现在多个批次中。stderr 会为每个批次列出一个 `batch get` 命令。
* 某个请求失败,如[读取批次时的错误](#errors-when-reading-batches)中所述。

## 创建批次

`batch create` 启动一个创建帐户的作业,然后等待其停止。在批次被[删除](#deleting-a-batch)之前,这些帐户会计入卖家的测试帐户限制。

在终端中,该命令会显示[安全问题选择器](#choosing-a-security-question),列出它将发送的值(包括你省略的选项的默认值),并要求你确认。然后,它会[提示](#secrets)你输入密码和安全答案,进行登录并发送请求。`--confirm` (`--yes`, `-y`) 仅跳过确认。

如果没有终端,请传递 `--password-file`、`--security-answer-file` 和 `--confirm`。如果不使用 `--confirm`,该命令会打印这些值,然后拒绝执行,不发送任何内容。

| 选项 | 说明 |
| - | - |
| `--email-prefix <text>` | 必需。沙盒组、一个连字符和一个模板,例如 `ABCD-tester`。沙盒组是沙盒 ID 中点之前的部分,例如 `ABCD.1` 中的 `ABCD`。 |
| `--count <count>` | 必需。要创建的帐户数;至少为 1。最大值由服务设置。 |
| `--sandbox-id <id>` | 必需。帐户可以访问的沙盒。重复此选项可添加更多沙盒。 |
| `--password-file <path>` | 包含帐户密码的文件,或使用 `-` 表示 stdin。请参阅[机密](#secrets)。 |
| `--security-answer-file <path>` | 包含安全答案的文件,或使用 `-` 表示 stdin。请参阅[机密](#secrets)。 |
| `--child-count <count>` | 批次中的子帐户总数,全部关联到第一个帐户;0 或更多。`--count 5 --child-count 2` 会创建 5 个帐户和 2 个子帐户,而不是每个帐户 2 个子帐户。最大值由服务设置。 |
| `--first-name <text>` | 默认为 `Test`。 |
| `--last-name <text>` | 默认为 `Account`。 |
| `--security-question <text>` | 每个帐户获得的安全问题。请参阅[选择安全问题](#choosing-a-security-question)。 |
| `--alternate-email <text>` | 默认为你的电子邮件。 |
| `--access-expiration <date>` | 沙盒访问权限的过期时间,例如 `2026-12-31`,按 UTC 解读。默认为从现在起三个月。 |
| `--tag <tag>` | 要存储在批次上的标记,之后可通过 `batch list --tag` 查找。重复此选项可添加更多标记。 |
| `--locale <locale>` | 默认为 `en-US`。 |
| `--subscription <name>` | 帐户的 XBOX 服务层级,`Silver` 或 `Gold`,不区分大小写。默认为 `Gold`。 |
| `--seller-id <id>` | 要为其创建帐户的卖家。 |
| `--confirm`、`--yes`、`-y` | 创建时不显示确认提示。 |
| `--no-wait` | 服务一接受作业就立即返回。不能与 `--timeout` 结合使用。 |
| `--timeout <duration>` | 等待作业的时长,例如 `90s`、`10m`、`2h` 或 `1d`。默认为 `5m`;最长为 `7d`。 |
| `--output <format>` | `json`(默认)、`json-compact` 或 `table`。 |

### 选择安全问题

在终端中,如果你既未传递 `--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`](#following-a-creation-job) 相同。

| 退出代码 | 含义 |
| - | - |
| 0 | 作业已成功,或使用 `--no-wait` 时已被接受。stderr 会给出跟踪它的命令。 |
| 1 | 未创建任何内容:请求被拒绝或驳回,在发送之前失败或被取消,或者收到带有 `feature_disabled` 或 `service_configuration_invalid` 的 503。 |
| 2 | 作业失败。可能已创建部分帐户;stderr 会给出计数和检查批次的命令。 |
| 3 | 结果未知。请参阅[结果未知时](#when-the-outcome-is-unknown)。 |
| 4 | 批次已存在,但等待在作业停止之前结束:已超过 `--timeout`、你按了 Ctrl+C,或读取作业失败。作业会继续运行。stderr 会给出恢复等待的命令。请勿再次创建。 |

### 结果未知时

当 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` 进行分支处理。

| 代码 | 含义 |
| - | - |
| `test_account_sandbox_access_denied` | 你无法授予对某个 `--sandbox-id` 值的访问权限。如果每个沙盒都被拒绝,则你的帐户可能未关联到该卖家、该卖家可能没有沙盒,或者 Partner Center 可能不允许你管理测试帐户。 |
| `test_account_count_invalid` | `--count` 超出了服务允许的范围。 |
| `test_account_child_count_invalid` | `--child-count` 超出了服务允许的范围。 |
| `test_account_email_prefix_invalid` | `--email-prefix` 不是由沙盒组、连字符和模板组成的形式,例如 `ABCD-tester`。 |
| `test_account_name_invalid` | `--first-name` 或 `--last-name` 被拒绝。 |
| `test_account_password_invalid` | 密码不符合密码规则。 |
| `test_account_security_question_invalid` | `--security-question` 被拒绝。 |
| `test_account_security_answer_invalid` | 安全答案被拒绝,例如因为它与密码相同或出现在安全问题中。 |
| `test_account_alternate_email_invalid` | `--alternate-email` 被拒绝。 |
| `test_account_keyword_invalid` | 某个 `--tag` 值被拒绝,或者标记过多。 |
| `test_account_locale_invalid` | 不支持 `--locale`;请尝试 `en-US`。 |
| `test_account_subscription_unavailable` | 该 `--subscription` 不可用;请尝试 `--subscription Silver`。 |
| `test_account_limit_exceeded` | 卖家已达到其测试帐户限制。 |
| `test_account_access_denied` | 你没有为此卖家创建测试帐户的 Partner Center 角色。 |
| `test_account_create_outcome_unknown` | 退出代码 3;请参阅[结果未知时](#when-the-outcome-is-unknown)。 |
| `downstream_request_rejected` | 请求被拒绝,但未指明字段,例如因为 `--email-prefix` 的组不是你的沙盒组之一,或者安全问题或答案过长。 |
| `downstream_throttled` | 请求正受到限制,未创建任何内容。请等待,然后重试。 |
| `rate_limited` | 429:你在短时间内发送的请求过多,未创建任何内容。请参阅[速率限制](https://docs.xbox.com/zh-CN/tools/xbox-cli/cli-for-agents.md#rate-limits)。 |
| 5xx 上的任何其他代码或无代码 | 退出代码 3,因为批次可能已存在;请参阅[结果未知时](#when-the-outcome-is-unknown)。 |
| `feature_disabled`、`service_configuration_invalid` | 503:测试帐户创建不可用。退出代码 1。 |
| `invalid_request`,或无代码的 `400` | 请求格式不正确或某个值不被允许;`detail` 或 `errors` 会指明字段。如果 CLI 比服务新,则对于服务尚不支持的选项可能会收到此错误。 |

## 跟踪创建作业

作业一被接受,`batch create` 就会打印批次 ID 和作业 ID。作业可能会运行数天,因此你可以随时停止等待,稍后再跟踪它:

| 选项 | 命令 | 说明 |
| - | - | - |
| `<job-id>` | `get`、`wait` | 必需。来自 `batch create` 的作业 ID,或来自 `batch list` 的批次的 `jobId`。 |
| `--batch-id <id>` | `get`、`wait` | 必需。作业所属的批次。 |
| `--seller-id <id>` | `get`、`wait` | 拥有该批次的卖家。 |
| `--timeout <duration>` | `wait` | 等待时长,例如 `90s`、`10m`、`2h` 或 `1d`。默认为 `5m`;最长为 `7d`。 |
| `--output <format>` | `get`、`wait` | `json`(默认)、`json-compact` 或 `table`。 |

两者都返回作业:

```json theme={null}
{
  "batchId": 123456,
  "jobId": "0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "running",
  "total": 5,
  "succeeded": 3,
  "failed": 0,
  "errorCode": null,
  "errorMessage": null,
  "progress": "Creating accounts"
}
```

`state` 为 `running`、`succeeded` 或 `failed`。作业失败时,`errorCode` 为 `test_account_job_failed`。`job wait` 会重试临时读取失败,例如限制或连接中断。

| 退出代码 | `job get` | `job wait` |
| - | - | - |
| 0 | 正在运行或已成功 | 已成功 |
| 1 | 请求失败 | 第一次读取失败,例如因为作业 ID 或批次 ID 错误;不会向 stdout 写入任何内容 |
| 2 | 失败 | 失败 |
| 4 | 未使用 | 等待在作业停止之前结束:已超过 `--timeout`、你按了 Ctrl+C,或读取作业失败。作业会继续运行。stderr 会给出恢复等待的命令;请在修复 stderr 上的错误或错误消失后运行该命令。 |

### 跟踪作业时的错误

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

| `code` | 含义 |
| - | - |
| `test_account_job_not_in_batch` | 404:作业不在 `--batch-id` 指定的批次中。 |
| `test_account_batch_not_found` | 404:此卖家没有这样的批次。 |
| `downstream_request_rejected` | 404:不存在具有该 ID 的作业。 |
| `test_account_access_denied` | 403:批次或作业属于其他卖家,因此 `--batch-id` 或 `--seller-id` 可能有误。否则,是其他开发人员启动了该作业,而你无法读取该卖家的所有批次。 |

## 更新批次

`batch update` 会更改批次中的每个帐户:它可以授予帐户对更多沙盒的访问权限、撤销访问权限、调整该访问权限的过期时间,以及添加或替换批次的标记。然后,它会等待批次显示这些更改。

在终端中,该命令首先会在批次当前值旁边显示每项请求的更改,在批次上仍有作业运行时发出警告,然后进行询问。传递 `--confirm` (`--yes`, `-y`) 可跳过提示。如果没有终端且未使用 `--confirm`,它会打印更改,然后拒绝执行,不发送任何内容。

| 选项 | 说明 |
| - | - |
| `<batch-id>` | 必需。批次 ID,来自 `batch list` 或 `batch create`。 |
| `--add-sandbox-id <id>` | 要授予帐户访问权限的沙盒。重复此选项可添加更多沙盒。 |
| `--remove-sandbox-id <id>` | 要撤销帐户访问权限的沙盒。重复此选项可添加更多沙盒。同一个沙盒不能既添加又删除。 |
| `--access-expiration <date>` | 帐户沙盒访问权限的新过期日期,例如 `2026-12-31`。它必须是将来的日期,服务仅保留日期部分。对于没有沙盒的批次,服务会拒绝此选项。 |
| `--tag <tag>` | 要添加到批次的标记,最多 100 个字符。批次已有的标记(不区分大小写)会被跳过。重复此选项可添加更多标记。不能与 `--clear-tags` 结合使用。 |
| `--replace-tags` | 用 `--tag` 值替换批次上的每个标记。需要 `--tag`。此处区分大小写,因此将 `smoke` 替换为 `Smoke` 属于更改。 |
| `--clear-tags` | 从批次中删除每个标记。 |
| `--allow-not-mine` | 允许更改其他开发人员创建的批次。如果不使用此选项,更新会被拒绝,并返回 `test_account_batch_not_owned`。你的权限仍可能拒绝此操作。 |
| `--seller-id <id>` | 拥有该批次的卖家。 |
| `--confirm`、`--yes`、`-y` | 更新时不显示确认提示。 |
| `--no-wait` | 服务一接受更新就立即返回。不能与 `--timeout` 结合使用。 |
| `--timeout <duration>` | 等待更新的时长,例如 `90s`、`10m` 或 `2h`。默认为 `5m`;最长为 `7d`。 |
| `--output <format>` | `json`(默认)、`json-compact` 或 `table`。 |

至少传递一项更改。一个批次最多可以有 20 个标记。`--replace-tags` 和 `--clear-tags` 会保留记录创建该批次的工具的标记,该标记不计入限制。更改沙盒或过期时间需要具有这些沙盒的访问权限;延长过期时间需要具有批次上每个沙盒的访问权限。

更新完成后,该命令会返回批次的值:

```json theme={null}
{
  "batchId": 123456,
  "jobId": "0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "updated",
  "sandboxes": ["ABCD.1", "ABCD.2"],
  "accessExpirationDate": "2026-12-31T00:00:00+00:00",
  "keywords": ["smoke"]
}
```

批次显示更改后,`state` 为 `updated`;使用 `--no-wait` 或等待先结束时,`state` 为 `updating`。当批次已具有每个请求的值时,不会进行任何更改:`state` 为 `unchanged`,`jobId` 为 `null`,并且命令以 0 退出。无法使用 `job get` 或 `job wait` 跟踪更新作业。

### 更新时的等待和退出代码

| 退出代码 | 含义 |
| - | - |
| 0 | 批次显示了更改、批次已具有这些值,或者使用 `--no-wait` 时更新已被接受。 |
| 1 | 未进行任何更改:请求被拒绝或驳回、在发送之前失败、在提示之前无法读取批次,或者你拒绝了操作。 |
| 2 | 更新作业已结束,但批次未显示更改。stderr 会指明存在差异的字段。请使用 `batch get` 读取批次,然后再次更新。 |
| 3 | 结果未知。在再次更新之前,请使用打印的 `batch get` 命令读取批次。在没有作业运行后,再次发送相同的更改是安全的。 |
| 4 | 更新已被接受,但等待在其仍在运行时结束:已超过 `--timeout`、你按了 Ctrl+C,或读取批次失败。如果 `jobId` 一直未清除,则表明作业失败或停滞。 |

### 更新时的错误

| `code` | 含义 |
| - | - |
| `test_account_batch_not_owned` | 403:该批次由其他开发人员创建。传递 `--allow-not-mine` 可取消此检查。 |
| `test_account_sandbox_access_denied` | 403:你没有更改中某个沙盒的访问权限。延长过期时间需要具有批次上每个沙盒的访问权限。 |
| `test_account_batch_not_found` | 404:此卖家没有这样的批次。 |
| `test_account_batch_busy` | 409:批次上有作业正在运行。请等待 `batch get` 显示 `jobId` 为 `null`。 |
| `test_account_keyword_invalid` | 400:某个 `--tag` 值不被允许。 |
| `test_account_access_denied` | 你没有为此卖家管理测试帐户的 Partner Center 角色,或者在使用 `--allow-not-mine` 时,没有更改非你创建的批次的角色。 |
| `downstream_throttled` | 请求正受到限制。请等待,然后重试。 |
| `rate_limited` | 429:你在短时间内发送的请求过多。请参阅[速率限制](https://docs.xbox.com/zh-CN/tools/xbox-cli/cli-for-agents.md#rate-limits)。 |
| `test_account_update_outcome_unknown` | 502:退出代码 3。 |
| `feature_disabled`、`service_configuration_invalid` | 503:测试帐户不可用。退出代码 1。 |

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

## 删除批次

`batch delete` 删除整个批次,然后等待其消失。批次中的每个帐户都会失去其沙盒访问权限,并且其测试帐户记录会被删除。这些帐户的 Microsoft 帐户和 XBOX 个人资料不会被关闭。

在终端中,该命令首先会显示批次的电子邮件模板、大小和创建者,在批次上仍有作业运行时发出警告,然后进行询问。传递 `--confirm` (`--yes`, `-y`) 可跳过提示。如果没有终端且未使用 `--confirm`,它会打印将要删除的内容,然后拒绝执行,不发送任何内容。不支持批量删除;请一次删除一个批次。

| 选项 | 说明 |
| - | - |
| `<batch-id>` | 必需。批次 ID,来自 `batch list` 或 `batch create`。 |
| `--allow-not-mine` | 允许删除其他开发人员创建的批次。如果不使用此选项,删除会被拒绝,并返回 `test_account_batch_not_owned`。你的权限仍可能拒绝此操作,并返回 `test_account_access_denied`。 |
| `--seller-id <id>` | 拥有该批次的卖家。 |
| `--confirm`、`--yes`、`-y` | 删除时不显示确认提示。 |
| `--no-wait` | 服务一接受删除就立即返回。不能与 `--timeout` 结合使用。 |
| `--timeout <duration>` | 等待批次消失的时长,例如 `90s`、`10m` 或 `2h`。默认为 `5m`;最长为 `7d`。 |
| `--output <format>` | `json`(默认)、`json-compact` 或 `table`。 |

该命令返回:

```json theme={null}
{
  "batchId": 123456,
  "jobId": "0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "deleted",
  "emailTemplate": "ABCD-tester",
  "batchSize": 5
}
```

批次消失后,`state` 为 `deleted`;使用 `--no-wait` 或等待先结束时,`state` 为 `deleting`。无法使用 `job get` 或 `job wait` 跟踪删除作业;删除运行期间,批次会显示其 `jobId`。

### 删除时的等待和退出代码

| 退出代码 | 含义 |
| - | - |
| 0 | 批次已消失,或者使用 `--no-wait` 时删除已被接受。 |
| 1 | 未删除任何内容:请求被拒绝或驳回、在发送之前失败、在提示之前无法读取批次,或者你拒绝了操作。 |
| 2 | 删除作业已停止,但批次仍然存在。请使用 `batch get` 检查它。 |
| 3 | 结果未知。请使用打印的 `batch get` 命令读取批次:带有 `test_account_batch_not_found` 的 `404` 表示批次已删除,已设置的 `jobId` 表示删除可能正在运行。如果 `jobId` 为 `null`,请等待一分钟后再次读取;仅当它仍为 `null` 时才再次删除。 |
| 4 | 删除已被接受,但等待在批次仍然存在时结束:已超过 `--timeout`、你按了 Ctrl+C,或读取批次失败。如果 `jobId` 一直保持设置状态且 `progress` 未变化,则表明删除已停滞。 |

### 删除时的错误

| `code` | 含义 |
| - | - |
| `test_account_batch_not_owned` | 403:该批次由其他开发人员创建;消息会指明其 Partner Center 用户 ID。传递 `--allow-not-mine` 可取消此检查。 |
| `test_account_batch_not_found` | 404:此卖家没有这样的批次,或者该批次已被删除。只有此代码表示批次已消失。 |
| `test_account_batch_busy` | 409:批次上有作业正在运行,可能是已在进行中的删除。请等待 `batch get` 显示 `jobId` 为 `null`,或返回带有 `test_account_batch_not_found` 的 `404`。 |
| `test_account_access_denied` | 你没有为此卖家管理测试帐户的 Partner Center 角色,或者在使用 `--allow-not-mine` 时,没有删除非你创建的批次的角色。 |
| `downstream_throttled` | 请求正受到限制。请等待,然后重试。 |
| `rate_limited` | 429:你在短时间内发送的请求过多。请参阅[速率限制](https://docs.xbox.com/zh-CN/tools/xbox-cli/cli-for-agents.md#rate-limits)。 |
| `test_account_delete_outcome_unknown` | 502 或 504:退出代码 3。无代码的 504 也按相同方式处理。 |
| `feature_disabled`、`service_configuration_invalid` | 503:测试帐户不可用。退出代码 1。 |

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

## 表格输出

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

| 命令 | 列 |
| - | - |
| `test-account batch list` | `BATCH ID`、`EMAIL TEMPLATE`、`SIZE`、`STATE`(`complete` 或 `pending`)、`CREATED BY`、`CREATED (UTC)`、`EXPIRES (UTC)`,使用 `--include-sandboxes` 时还有 `SANDBOXES`。 |
| `test-account batch get` | 每个帐户一行:`EMAIL`、`GAMERTAG`、`XUID` 和 `DELETED`。stderr 会汇总批次及其沙盒访问权限。 |
| `test-account get` | 一行:`EMAIL`、`GAMERTAG`、`BATCH ID`、`EMAIL TEMPLATE`、`EXPIRES (UTC)` 和 `EXPIRED`(`yes` 或 `no`)。 |
| `test-account batch create`、`job get`、`job wait` | 一行:`BATCH ID`、`JOB ID`、`STATE`(`running`、`succeeded` 或 `failed`)、`TOTAL`、`SUCCEEDED`、`FAILED`。 |
| `test-account batch update` | 一行:`BATCH ID`、`JOB ID`、`STATE`(`updated`、`updating` 或 `unchanged`)、`EXPIRES (UTC)`。stderr 会列出沙盒和关键字。 |
| `test-account batch delete` | 一行:`BATCH ID`、`JOB ID`、`STATE`(`deleted` 或 `deleting`)、`EMAIL TEMPLATE`、`SIZE`。 |

## 示例

以下命令列出并读取批次、帐户和作业:

```bash theme={null}
xbox test-account batch list --mine --limit 5

xbox test-account batch list --state pending --output table

xbox test-account batch list --email-prefix ABCDEF-smoke --include-sandboxes

xbox test-account batch get 123456 --output table

xbox test-account batch list --expired --limit 10

xbox test-account get ABCD-tester00007@xboxtest.com --output table

xbox test-account batch get 123456 --seller-id 1234567 --output json-compact

xbox test-account job get 0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b --batch-id 123456 --output table
```

创建一个包含五个帐户的批次。该命令会提示你输入密码和安全答案,然后要求你确认:

```bash theme={null}
xbox test-account batch create --email-prefix ABCD-tester --count 5 --sandbox-id ABCD.1
```

以无人参与方式创建批次,从文件读取机密,不显示提示,并最多等待 30 分钟:

```bash theme={null}
xbox test-account batch create --email-prefix ABCD-smoke --count 2 --sandbox-id ABCD.1 \
  --password-file ./password.txt --security-answer-file ./answer.txt \
  --subscription Silver --tag smoke --timeout 30m --confirm
```

最多等待两小时以完成创建作业:

```bash theme={null}
xbox test-account job wait 0f8e5b2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b --batch-id 123456 --timeout 2h
```

添加一个沙盒,并设置沙盒访问权限的过期时间。该命令会显示更改,要求你确认,然后等待批次显示这些更改:

```bash theme={null}
xbox test-account batch update 123456 --add-sandbox-id ABCD.2 --access-expiration 2026-12-31
```

以无人参与方式添加两个标记,且不等待:

```bash theme={null}
xbox test-account batch update 123456 --tag smoke --tag nightly --confirm --no-wait
```

将所有标记替换为一个标记:

```bash theme={null}
xbox test-account batch update 123456 --tag nightly --replace-tags --confirm
```

删除批次。该命令会显示批次,要求你确认,然后等待其消失:

```bash theme={null}
xbox test-account batch delete 123456
```

以无人参与方式删除其他开发人员创建的批次,且不等待:

```bash theme={null}
xbox test-account batch delete 123456 --allow-not-mine --confirm --no-wait
```


## Related topics

- [XBOX 服务沙盒概述](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [主页 (Dev Home)](https://docs.xbox.com/zh-CN/tools/tools-console/devhome/devhome-home.md)
- [XBOX 测试帐户](https://docs.xbox.com/zh-CN/services/xbox-services/develop/test-accounts/live-test-accounts.md)
- [创建测试帐户](https://docs.xbox.com/zh-CN/services/xbox-services/develop/test-accounts/live-setup-testaccounts.md)
- [导出 XBOX 测试帐户](https://docs.xbox.com/zh-CN/services/xbox-services/develop/test-accounts/live-exporting-test-accounts.md)
