> ## 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/ko/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/ko/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
    }
  ]
}
```

* `keywords`와 `sandboxAccess`는 `--include-sandboxes`를 전달하지 않으면 `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에 `status`, `title`, `detail`, 응답에 포함된 경우 `code`, 그리고
`correlationId`가 있는 JSON 오류가 출력되며, 대부분 `detail`에 힌트를 추가합니다. 그 밖의
실패는 텍스트 한 줄을 출력합니다. stderr를 구문 분석하기 전에 종료 코드를 확인하세요.

| 상태 | 의미 |
| - | - |
| 400 | 필터가 거부되었거나, 판매자가 여러 개인데 하나를 선택하지 않았습니다. `--seller-id`를 전달하세요. |
| 403 | 이 판매자의 구성원이 아니거나, 이 판매자에 대한 Partner Center 테스트 계정 역할이 없습니다. `batch get`의 경우 배치가 다른 판매자에 속할 수 있거나(`--seller-id`를 전달하세요), 다른 개발자가 배치를 생성했고 판매자의 모든 배치를 읽을 수 없는 경우입니다. 오류에서 다시 로그인하라고 하면 다시 로그인하세요. |
| 404 | 해당 ID의 배치가 없거나, 테스트 계정을 아직 사용할 수 없습니다. |
| 429 | 코드가 `rate_limited`이면 짧은 시간에 너무 많은 요청을 보냈다는 뜻입니다. 오류에 `retryAfterSeconds`가 포함됩니다. [속도 제한](https://docs.xbox.com/ko/tools/xbox-cli/cli-for-agents.md#rate-limits)을 참조하세요. |
| 502 | 서비스가 요청을 완료할 수 없습니다. 다시 시도하세요. 테스트 계정 역할이 없거나, `batch get`의 경우 다른 개발자가 배치를 생성했을 때 서비스가 403 대신 502를 반환할 수 있습니다. 개인 Microsoft 계정을 사용하는 경우 다시 시도해도 도움이 되지 않습니다. [알려진 문제](https://docs.xbox.com/ko/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`입니다. 샌드박스 그룹은 `ABCD.1`의 `ABCD`처럼 샌드박스 ID에서 점 앞부분입니다. |
| `--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로 해석됩니다. 기본값은 지금부터 3개월 후입니다. |
| `--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를 누르면 아무것도 생성하지 않고
취소됩니다. 질문을 선택해도 생성이 확인되지는 않습니다.

### 비밀

암호와 보안 답변은 옵션 값이나 환경 변수로 절대 받지 않으므로 셸 기록, 프로세스 목록,
로그에 남지 않습니다. 각 값은 다음에서 가져옵니다.

* 해당 `--password-file` 또는 `--security-answer-file`. 끝에 있는 줄 바꿈 하나는 제거됩니다.
* 경로 대신 `-`를 사용하면 stdin에서 읽습니다. 둘 중 하나만 stdin에서 읽을 수 있습니다.
* 파일 옵션이 없으면 입력 내용을 표시하지 않는 터미널 프롬프트.

암호는 8\~16자여야 하며 소문자, 대문자, 숫자, 기호 중 세 가지 이상을 포함해야 합니다. 밑줄은
기호로 간주되지 않습니다. 암호는 보안 답변과 같을 수 없습니다.

### 대기 및 종료 코드

기다리는 동안 명령은 진행 상황을 stderr에 출력합니다. 최종 작업은
[`job get`](#following-a-creation-job)과 같은 형식으로 stdout에 씁니다.

| 종료 코드 | 의미 |
| - | - |
| 0 | 작업이 성공했거나, `--no-wait`로 수락되었습니다. stderr에 작업을 추적하는 명령이 표시됩니다. |
| 1 | 아무것도 생성되지 않았습니다. 요청이 거부되었거나, 전송되기 전에 실패하거나 취소되었거나, `feature_disabled` 또는 `service_configuration_invalid`와 함께 503을 받았습니다. |
| 2 | 작업이 실패했습니다. 일부 계정이 생성되었을 수 있습니다. stderr에 개수와 배치를 검사하는 명령이 표시됩니다. |
| 3 | 결과를 알 수 없습니다. [결과를 알 수 없는 경우](#when-the-outcome-is-unknown)를 참조하세요. |
| 4 | 배치는 존재하지만 작업이 중지되기 전에 대기가 끝났습니다. `--timeout`이 지났거나, Ctrl+C를 눌렀거나, 작업 읽기가 실패했습니다. 작업은 계속 실행됩니다. stderr에 대기를 재개하는 명령이 표시됩니다. 다시 생성하지 마세요. |

### 결과를 알 수 없는 경우

요청이 전송된 후 연결이 끊기거나 서비스가 `5xx` 오류를 반환하는 경우처럼 서비스가 배치를
생성했는지 CLI가 알 수 없으면 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. 그러한 배치가 없을 때만 다시 생성합니다.

출력된 명령에는 사용한 판매자, 프로필, 로그인 옵션이 유지되므로 그대로 복사할 수 있습니다.

### 생성 시 오류

실패하면 `status`, `title`, `detail`, 응답에 포함된 경우 `code`가 있는 JSON 오류를 stderr에
씁니다. `detail`이 아니라 `code`를 기준으로 분기하세요.

| 코드 | 의미 |
| - | - |
| `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/ko/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>` | 필수입니다. `batch list` 또는 `batch create`에서 얻은 배치 ID입니다. |
| `--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/ko/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>` | 필수입니다. `batch list` 또는 `batch create`에서 얻은 배치 ID입니다. |
| `--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`이면 1분 정도 기다렸다가 다시 읽으세요. 여전히 `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/ko/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
```

계정 5개로 구성된 배치를 생성합니다. 명령은 암호와 보안 답변을 입력하라는 메시지를 표시한 다음
확인을 요청합니다.

```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
```

생성 작업이 끝날 때까지 최대 2시간 동안 기다립니다.

```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/ko/services/xbox-services/develop/test-accounts/index.md)
- [모던 게이머태그의 모범 사례 및 테스트](https://docs.xbox.com/ko/services/xbox-services/fundamentals/identity/user-profile/gamertags/live-modern-gamertags-best-practices-and-testing.md)
- [XBOX 서비스 샌드박스 개요](https://docs.xbox.com/ko/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [홈 페이지 (Dev Home)](https://docs.xbox.com/ko/tools/tools-console/devhome/devhome-home.md)
- [XBOX 테스트 계정](https://docs.xbox.com/ko/services/xbox-services/develop/test-accounts/live-test-accounts.md)
