> ## 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-TW/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-TW/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-TW/tools/xbox-cli/cli-for-agents.md#rate-limits)。 |
| 502 | 服務無法完成要求；請重試。當您缺少測試帳戶角色時，或對於 `batch get` 而言當批次由其他開發人員建立時，服務可能會傳回 502 而非 403。若使用個人 Microsoft 帳戶，重試並無幫助；請參閱[已知問題](https://docs.xbox.com/zh-TW/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 services 層級，`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-TW/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。作業可能會執行數天，因此您可以隨時停止等候，稍後再追蹤：

| 選項 | 命令 | 描述 |
| - | - | - |
| `<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 錯誤；不會將任何內容寫入 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` 或等候先結束時，則為 `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-TW/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` 或等候先結束時，則為 `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-TW/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

- [測試帳戶](https://docs.xbox.com/zh-TW/services/xbox-services/develop/test-accounts/index.md)
- [新式玩家代號的最佳做法和測試](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/identity/user-profile/gamertags/live-modern-gamertags-best-practices-and-testing.md)
- [XBOX 服務沙箱概觀](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [XBOX 測試帳戶](https://docs.xbox.com/zh-TW/services/xbox-services/develop/test-accounts/live-test-accounts.md)
- [建立測試帳戶](https://docs.xbox.com/zh-TW/services/xbox-services/develop/test-accounts/live-setup-testaccounts.md)
