> ## 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 テスト アカウントは、パートナー センターの販売者用にバッチ単位で作成されます。これらのコマンドは、
バッチを作成、更新、削除し、アカウントを作成するジョブを追跡し、バッチとそのバッチ内の
アカウントを読み取ります。個々のアカウントを変更することはできず、パスワードが返されることもありません。
アカウントには、その販売者に対するパートナー センターのテスト アカウント ロールが必要です。

すべてのコマンドは `--seller-id` を受け取ります。指定しない場合、コマンドは `XBOX_SELLER_ID` または
[`xbox context set`](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/context) で保存された販売者を使用し、それもない場合は唯一の販売者を使用します。販売者が複数ある場合は、
`--seller-id` を渡してください。

## コマンド

| コマンド | 説明 |
| - | - |
| `test-account batch list` | 販売者のテスト アカウントのバッチを新しい順に一覧表示します。 |
| `test-account batch get <batch-id>` | 1 つのバッチとそのアカウントを表示します。 |
| `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>` | 作成ジョブの状態を 1 回表示します。 |
| `test-account job wait <job-id>` | 作成ジョブの実行が停止するか、待機がタイムアウトするまで待機します。 |

`batch create`、`batch update`、`batch delete` は、何かを変更する前に確認を求めます。また、
リクエストは 1 回だけ送信され、再試行されることはありません。[安全性と破壊的な操作](https://docs.xbox.com/ja-jp/tools/xbox-cli/safety.md)を参照してください。

## バッチを読み取るためのオプション

| オプション | コマンド | 説明 |
| - | - | - |
| `--seller-id <id>` | `batch list`、`batch get`、`test-account get` | パートナー センターの販売者 ID。 |
| `--mine` | `list` | 自分が作成したバッチのみ。`--created-by-id` と組み合わせることはできません。 |
| `--created-by-id <id>` | `list` | この数値のパートナー センター ユーザー ID で作成されたバッチのみ。`--mine` と組み合わせることはできません。 |
| `--email-prefix <text>` | `list` | 大文字と小文字を区別せず、メール テンプレートがこのテキストで始まるバッチのみ。 |
| `--tag <tag>` | `list` | このタグと完全に一致するタグを持つバッチのみ。値は 1 つだけ受け付けます。 |
| `--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 出力では `keywords` として表示され、`test_account_keyword_invalid` などのエラー コードでも
同様に表されます。`--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` は数値のパートナー センター ユーザー 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` にはヒントが追加されます。その他の失敗では、
1 行のテキストが出力されます。stderr を解析する前に終了コードを確認してください。

| 状態 | 意味 |
| - | - |
| 400 | フィルターが拒否されたか、販売者が複数あるのに選択していません。`--seller-id` を渡してください。 |
| 403 | この販売者のメンバーではないか、販売者に対するパートナー センターのテスト アカウント ロールがありません。`batch get` の場合は、バッチが別の販売者に属している (`--seller-id` を渡してください) か、別の開発者がバッチを作成しており、販売者のすべてのバッチを読み取ることができない可能性があります。エラーで再度サインインするよう求められた場合は、サインインしてください。 |
| 404 | その ID のバッチが存在しないか、テスト アカウントがまだ利用できません。 |
| 429 | コード `rate_limited` の場合、短時間に送信したリクエストが多すぎます。エラーには `retryAfterSeconds` が含まれます。[レート制限](https://docs.xbox.com/ja-jp/tools/xbox-cli/cli-for-agents.md#rate-limits)を参照してください。 |
| 502 | サービスがリクエストを完了できませんでした。再試行してください。テスト アカウント ロールがない場合や、`batch get` で別の開発者がバッチを作成した場合、サービスは 403 ではなく 502 を返すことがあります。個人用の Microsoft アカウントの場合、再試行しても解決しません。[既知の問題](https://docs.xbox.com/ja-jp/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 として解釈されます。既定値は現在から 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`。末尾の改行 1 つは削除されます。
* パスの代わりに `-` を指定した場合は stdin。stdin から読み取ることができるのは、2 つのうち 1 つだけです。
* ファイル オプションがない場合は、入力内容をエコーしないターミナルのプロンプト。

パスワードは 8 から 16 文字で、英小文字、英大文字、数字、記号のうち少なくとも 3 種類を含む必要があります。
アンダースコアは記号としてカウントされません。パスワードをセキュリティの質問の答えと
同じにすることはできません。

### 待機と終了コード

待機中、コマンドは進行状況を 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` の値のいずれかに対するアクセスを付与できません。すべてのサンドボックスが拒否された場合は、アカウントが販売者にリンクされていない、販売者にサンドボックスがない、またはパートナー センターでテスト アカウントの管理が許可されていない可能性があります。 |
| `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` | この販売者のテスト アカウントを作成するためのパートナー センターのロールがありません。 |
| `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/ja-jp/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`。 |

少なくとも 1 つの変更を渡してください。バッチに設定できるタグは最大 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` | この販売者のテスト アカウントを管理するためのパートナー センターのロールがないか、`--allow-not-mine` を指定した場合は、自分が作成していないバッチを変更するためのロールがありません。 |
| `downstream_throttled` | リクエストがスロットリングされています。しばらく待ってから、もう一度お試しください。 |
| `rate_limited` | 429: 短時間に送信したリクエストが多すぎます。[レート制限](https://docs.xbox.com/ja-jp/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` もない場合、コマンドは削除対象を表示して処理を拒否し、
何も送信しません。一括削除はできないため、バッチは 1 つずつ削除してください。

| オプション | 説明 |
| - | - |
| `<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: 別の開発者がバッチを作成しました。メッセージには、その開発者のパートナー センター ユーザー 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` | この販売者のテスト アカウントを管理するためのパートナー センターのロールがないか、`--allow-not-mine` を指定した場合は、自分が作成していないバッチを削除するためのロールがありません。 |
| `downstream_throttled` | リクエストがスロットリングされています。しばらく待ってから、もう一度お試しください。 |
| `rate_limited` | 429: 短時間に送信したリクエストが多すぎます。[レート制限](https://docs.xbox.com/ja-jp/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` | アカウントごとに 1 行: `EMAIL`、`GAMERTAG`、`XUID`、`DELETED`。stderr には、バッチとそのサンドボックス アクセスの概要が出力されます。 |
| `test-account get` | 1 行: `EMAIL`、`GAMERTAG`、`BATCH ID`、`EMAIL TEMPLATE`、`EXPIRES (UTC)`、`EXPIRED` (`yes` または `no`)。 |
| `test-account batch create`、`job get`、`job wait` | 1 行: `BATCH ID`、`JOB ID`、`STATE` (`running`、`succeeded`、または `failed`)、`TOTAL`、`SUCCEEDED`、`FAILED`。 |
| `test-account batch update` | 1 行: `BATCH ID`、`JOB ID`、`STATE` (`updated`、`updating`、または `unchanged`)、`EXPIRES (UTC)`。stderr には、サンドボックスとキーワードが一覧表示されます。 |
| `test-account batch delete` | 1 行: `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
```

待機せずに、無人で 2 つのタグを追加します。

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

すべてのタグを 1 つのタグに置き換えます。

```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/ja-jp/services/xbox-services/develop/test-accounts/index.md)
- [モダン ゲーマータグのベスト プラクティスとテスト](https://docs.xbox.com/ja-jp/services/xbox-services/fundamentals/identity/user-profile/gamertags/live-modern-gamertags-best-practices-and-testing.md)
- [XBOX services サンドボックスの概要](https://docs.xbox.com/ja-jp/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [ホーム ページ (Dev Home)](https://docs.xbox.com/ja-jp/tools/tools-console/devhome/devhome-home.md)
- [XBOX テスト アカウント](https://docs.xbox.com/ja-jp/services/xbox-services/develop/test-accounts/live-test-accounts.md)
