> ## 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.

# Playtest

> XBOX ゲームのプレイテストを一覧表示、取得、比較、作成、更新、公開、削除します。

プレイテストを使用すると、選ばれたプレイヤー グループがリリース前のゲームを試すことができます。`playtest` コマンドは、
パートナー センターでゲームのプレイテストを読み取り、作成、更新、公開、削除します。`create`、
`update`、`publish`、`delete` は、変更を行う前に確認を求めます。

`create`、`update`、`publish`、`delete` は試験段階 (Experimental) です。オプションと出力は変更または
削除される可能性があります。[試験段階のコマンド](https://docs.xbox.com/ja-jp/tools/xbox-cli/cli-command-lifecycle.md)を参照してください。

## コマンド

| コマンド | 説明 |
| - | - |
| `playtest list` | ゲームのプレイテストを一覧表示します。 |
| `playtest get <playtest-id>` | プレイテストを 1 つ取得します。詳細、パッケージ、画像、対象ユーザー、`etag` が含まれます。 |
| `playtest diff <playtest-id>` | プレイテストを、最後に公開されたバージョンまたは別のプレイテストと比較します。 |
| `playtest create` | 非公開の下書きプレイテストを作成します (試験段階)。 |
| `playtest update <playtest-id>` | プレイテストを変更します。公開済みのプレイテストは下書きに戻ります (試験段階)。 |
| `playtest publish <playtest-id>` | プレイテストを公開して開始日から対象ユーザーに提供し、スケジュール済みまたはライブになるまで待機します (試験段階)。 |
| `playtest delete <playtest-id>` | プレイテストを削除し、削除されるまで待機します (試験段階)。 |

## 引数とオプション

| 引数またはオプション | 適用対象 | 必須 | 説明 |
| - | - | - | - |
| `<playtest-id>` | `get`、`diff`、`update`、`publish`、`delete` | はい | `list` から取得した `playtestId` (`11111111-2222-3333-4444-555555555555` など)。 |
| `--store-id <id>` | すべて | 2 つのうちいずれか | ゲームの Store ID (`9N0000000000` など)。 |
| `--xbox-title-id <id>` | すべて | 2 つのうちいずれか | ゲームの XBOX タイトル ID (`1234ABCD` など)。PlayFab タイトル ID ではありません。一致するゲームがない場合や複数ある場合は、代わりに渡す Store ID がエラーに一覧表示されます。 |
| `--compare-to <playtest-id>` | `diff` | いいえ | 最後に公開されたバージョンの代わりに比較する別のプレイテスト。 |
| `--name <name>` | `create`、`update` | `create` | プレイヤーに表示されるプレイテストの名前。空白にすることはできません。 |
| `--description <text>` | `create`、`update` | いいえ | 短い説明。`update` では、`""` を指定するとクリアされます。 |
| `--long-description <text>` | `create`、`update` | いいえ | 長い説明。`update` では、`""` を指定するとクリアされます。 |
| `--start <date>` | `create`、`update` | `create` | プレイテストの開始日時。[日付](#dates)を参照してください。 |
| `--end <date>` | `create`、`update` | `create` | プレイテストの終了日時。`--start` より後である必要があります。 |
| `--audience-id <id>` | `create`、`update` | いいえ | 参加できる対象ユーザー。[`audience list`](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/audience) から取得します。複数指定するには繰り返します。[対象ユーザーの選択](#choosing-audiences)を参照してください。 |
| `--pc-package-id <id>` | `create`、`update` | いいえ | プレイヤーが入手する PC パッケージ。[パッケージ](#packages)を参照してください。 |
| `--console-package-id <id>` | `create`、`update` | いいえ | プレイヤーが入手する本体パッケージ。[パッケージ](#packages)を参照してください。 |
| `--idempotency-key <key>` | `create` | いいえ | 新しい GUID の代わりに使用する、1 から 50 文字の印刷可能な ASCII 文字。[プレイテストの作成](#creating-a-playtest)を参照してください。 |
| `--if-match <etag>` | `update` | いいえ | `playtest get` から取得したこの `etag` がプレイテストで変わっていない場合にのみ更新します。[プレイテストの更新](#updating-a-playtest)を参照してください。 |
| `--no-wait` | `publish`、`delete` | いいえ | 公開または削除がキューに登録されたらすぐに戻ります。`--timeout` と組み合わせることはできません。 |
| `--timeout <duration>` | `publish`、`delete` | いいえ | 待機する時間 (`90s`、`10m`、`2h` など)。既定値は `5m`、最大値は `7d` です。 |
| `--confirm` (`--yes`、`-y`) | `create`、`update`、`publish`、`delete` | いいえ | 確認プロンプトをスキップします。このオプションがなく、ターミナルもない場合、コマンドは変更を拒否します。 |
| `--seller-id <id>` | すべて | 保存されていない場合 | パートナー センターの販売者 ID。[コンテキスト](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/context.md)を参照してください。 |
| `--base-url <url>` | すべて | いいえ | リクエストのベース URL。`XboxPartner:BaseUrl` 構成キーをオーバーライドします。 |
| `--output <format>` | すべて | いいえ | `json` (既定)、`json-compact`、または `table`。`create`、`update`、`publish`、`delete` は `table` を拒否します。 |

## 例

プレイテストを一覧表示し、1 つを取得して、2 つを比較します。

```bash theme={null}
xbox playtest list --store-id 9N0000000000
xbox playtest list --xbox-title-id 1234ABCD --output table
xbox playtest get 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
xbox playtest diff 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --compare-to 22222222-3333-4444-5555-666666666666 --output table
```

対象ユーザー向けのプレイテストを作成します。

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --audience-id 1152921504606846976
```

プレイテストの終了日を変更します。

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30
```

プレイテストを公開します。

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

プレイテストを削除します。

```bash theme={null}
xbox playtest delete 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

## プレイテストの読み取り

`playtest list` は `playtests` 配列を書き込みます。テーブルには `PLAYTEST ID`、`NAME`、`STATUS`、`TYPE`、
`START`、`END` の列があります。抜粋を次に示します。

```json theme={null}
{ "playtests": [ { "playtestId": "11111111-2222-3333-4444-555555555555", "name": "Alpha", "status": "Live", "type": "Private" } ] }
```

`playtest get` は、サービスから返されたとおりにプレイテストを書き込みます。`etag` は
`update --if-match` に渡すバージョンで、`audiences.audienceIds` には参加できる対象ユーザーが一覧表示されます。テーブルには
`FIELD` と `VALUE` の行があります。

`playtest diff` は `hasDiffData`、`current`、`compared` を書き込みます。`hasDiffData` が `false` の場合、
比較するものはなく、`compared` は省略されます。テーブルには、異なるフィールドのみが `FIELD`、`CURRENT`、
`COMPARED` の列に表示されます。画像は比較されません。

## プレイテストの作成

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15
```

`playtest create` は非公開の下書きプレイテストを作成し、`playtest get` と同じ形式で書き込みます。
もう一度実行すると、別のプレイテストが作成されます。不要なプレイテストは
[`playtest delete`](#deleting-a-playtest) で削除します。

作成のたびに冪等性キーが送信されます。`--idempotency-key` を渡さない場合、キーは新しい GUID になります。
キーが重複する作成では、そのキーで作成されたプレイテストが返され、異なるオプションは無視されます。

タイムアウト後など、結果が不明な場合、コマンドは終了コード `3` で終了し、同じキーで再試行する
コマンドを表示します。

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --idempotency-key 11111111-2222-3333-4444-555555555555
```

再試行では、最初のリクエストでプレイテストが作成されていればそのプレイテストが返され、作成されていなければ作成されます。
オプションに改行が含まれている場合は、キーのみが表示されます。同じコマンドを `--idempotency-key` とそのキーを付けて
実行してください。終了日が過ぎているなどの理由で再試行が拒否された場合は、新しいキーでプレイテストを作成する前に
`playtest list` を確認してください。

## パッケージ

プレイテストには、PC パッケージと本体パッケージを 1 つずつ設定できます。[`xbox package list`](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/package#listing-packages) から
プレイテストの準備ができているパッケージを選択し、その `id` をプラットフォームに対応するオプションに
渡します。

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --pc-package-id 11111111-2222-3333-4444-555555555555
```

`update` では、省略したパッケージ オプションのパッケージは保持され、新しい ID を指定すると置き換えられ、`""` を指定すると
削除されます。

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --pc-package-id 22222222-3333-4444-5555-666666666666 --console-package-id ""
```

## プレイテストの更新

> [!WARNING]
>
> パートナー センターで編集した場合と同様に、更新を行うと公開済みのプレイテストは下書きに戻ります。プレイヤーが
> 利用できるようにするには、`playtest publish` でもう一度公開してください。

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30
```

`playtest update` は渡したオプションのみを変更します。少なくとも 1 つのオプションが必要です。更新された
プレイテストを `playtest get` と同じ形式で書き込みます。パートナー センターで構成されたゲームのアートは保持されます。
プレイテストにリンクされているその他のアートは、プレースホルダーに置き換えられます。

他のユーザーの変更を上書きしないようにするには、`playtest get` から取得した `etag` を `--if-match` に渡します。
`etag` を囲む二重引用符は省略可能です。`*`、弱い (`W/`) etag、および etag のリストは
拒否されます。

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30 --if-match 0x8DD1234ABCD5678
```

結果が不明な場合、コマンドは終了コード `3` で終了します。再試行する前に、`playtest get` でプレイテストを確認してください。

## 対象ユーザーの選択

対象ユーザーは、販売者がパートナー センターで管理する、テスターなどのプレイヤーのグループです。
[`audience list`](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/audience) から取得した `id` を `--audience-id` に渡します。複数指定するには繰り返します。

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --audience-id 1152921504606846976 --audience-id 1152921504606846977
```

`--audience-id` を指定しない場合、`create` は対象ユーザーのないプレイテストを作成し、`update` は既存の対象ユーザーを保持します。
`update` では、渡した ID によってプレイテストのすべての対象ユーザーが置き換えられます。すべての対象ユーザーを削除するには、
`""` のみを渡します。

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --audience-id ""
```

`""` を対象ユーザー ID と組み合わせることはできず、`create` では拒否されます。プレイテストを公開するには、
少なくとも 1 つの対象ユーザーが必要です。

## プレイテストの公開

ゲームで XBOX サービスを使用する場合は、公開する前に XBOX サービスの構成と公表解禁を設定してください。
[プレイテストで XBOX サービスを使用する](https://docs.xbox.com/ja-jp/tools/xbox-cli/xbox-services-in-a-playtest.md)を参照してください。

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

公開すると、プレイテストは開始日から対象ユーザーに提供されます。コマンドは最初に読み取ったバージョンを
公開します。その間にプレイテストが変更された場合、公開は `412` で失敗し、何も変更されません。

確認を求める前に、コマンドは公表解禁日がプレイテストの終了日より後かどうかなど、ゲームの XBOX サービスのセットアップを
チェックし、確認が必要な項目を stderr に一覧表示します。これらのチェックは助言のみを目的としています。`--confirm` を指定すると、確認を求めずに公開されます。

その後、サービスが独自のチェックを実行します。いずれかのチェックによって公開がブロックされた場合、何もキューに登録されず、
コマンドは各チェックを stderr に一覧表示して終了コード `1` で終了します。エラーを修正して、もう一度公開してください。
年齢別レーティングがないためにブロックされたプレイテストでは、パートナー センターで年齢別レーティングのアンケートに回答する必要があります。

公開がキューに登録されると、コマンドはプレイテストが `Scheduled`、`Live`、または
`PublishFailed` になるまで待機し、`playtest get` と同じ形式で書き込みます。Ctrl+C を押すと待機は停止しますが、公開は
続行されます。`--no-wait` を指定すると、コマンドは公開がキューに登録された時点で `publishJobId` と `warnings` (ある場合) を
書き込みます。その後は `playtest get` で状況を確認してください。

| 終了コード | 意味 |
| - | - |
| `0` | プレイテストは `Scheduled` または `Live` です。`--no-wait` を指定した場合は、公開がキューに登録されました。 |
| `1` | チェックによってブロックされた、プレイテストが変更されたなどの理由で、公開されませんでした。 |
| `2` | 公開に失敗しました。プレイテストは `PublishFailed` です。 |
| `3` | リクエストは送信されましたが、結果は不明です。もう一度公開する前に、`playtest get` でプレイテストを確認してください。 |
| `4` | 公開はキューに登録されましたが、完了する前に待機が終了しました。`playtest get` で確認してください。 |

## プレイテストの削除

```bash theme={null}
xbox playtest delete 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

`playtest delete` は、最初に読み取ったバージョンのプレイテストを削除します。プレイテストが
`Deleted` になるか存在しなくなるまで待機し、その後 `status` を含むサービスの応答を書き込みます。Ctrl+C を押すと待機は停止しますが、
削除は続行されます。`--no-wait` を指定すると、削除がキューに登録された時点で応答を書き込みます。
`412` の後は、削除が既にキューに登録されている可能性があるため、1 分待ってから `playtest get` で確認し、
その後でもう一度削除してください。

| 終了コード | 意味 |
| - | - |
| `0` | 削除されました。`--no-wait` を指定した場合は、削除がキューに登録されました。 |
| `1` | プレイテストが変更された、状態が削除を許可していないなどの理由で、削除されませんでした。 |
| `3` | リクエストは送信されましたが、結果は不明です。もう一度削除する前に、`playtest get` でプレイテストを確認してください。 |
| `4` | 削除はキューに登録されましたが、待機が終了する前にプレイテストが `Deleted` になりませんでした。`playtest get` で確認してください。 |

## 日付

`--start` と `--end` には、`2026-11-01T09:00:00-07:00` や `2026-11-01T16:00:00Z` などの ISO 8601 形式の日付と時刻を
指定できます。時刻のない日付は UTC の午前 0 時を意味し、オフセットのない時刻は
UTC として扱われます。更新で日付を 1 つだけ渡した場合、サービスはその日付をプレイテストのもう一方の日付と照らし合わせてチェックします。

## エラー

上記の終了コードの表で別途示されている場合を除き、失敗は stderr に出力され、終了コード `1` で終了します。`create` と
`update` は、結果が不明な場合に終了コード `3` で終了します。サービスから返された失敗には HTTP
状態が含まれます。`--verbose` を指定するとサービスの応答が追加されます。応答の `code` フィールドを次の表に示します。

| 状態 | `code` | 意味 |
| - | - | - |
| 400 | `invalid_playtest_request` | 開始より後ではない終了など、`create` または `update` が無効なリクエストを送信しました。 |
| 400 | `playtest_audience_not_found` | `--audience-id` が販売者の対象ユーザーのいずれでもありません。メッセージには確認用の `audience list` コマンドが表示されます。 |
| 400 | `playtest_package_not_found` | ゲームにその ID のパッケージがありません。 |
| 400 | `playtest_package_ambiguous` | パッケージ ID が複数のパッケージ セットに一致し、そのいずれもゲームの Main ブランチにない、または複数のマーケット グループに一致し、そのいずれも `default` ではありません。 |
| 400 | `playtest_package_platform_mismatch` | `--pc-package-id` に本体パッケージを指定した場合など、パッケージがオプションのプラットフォームと一致しません。`xbox package list` でプラットフォームを確認してください。 |
| 400 | `playtest_request_rejected` | パートナー センターがリクエストを拒否しました。たとえば、終了日が過去の `create` や `update`、まだプレイテストで使用できないパッケージ、削除されたプレイテストの `publish` などです。 |
| 403 | `audience_permission_denied` | 販売者に対するパートナー センターの顧客グループの読み取り権限がない状態で `--audience-id` を渡しました。何も変更されていません。パートナー センター アカウントのマネージャーにアクセス権を依頼してください。 |
| 403 | `package_permission_denied` | `list`、`get`、`diff` では、ゲームに対するパッケージの読み取り権限 (Developer ロールに含まれます) がありません。その他のコマンドでは、ゲームのプレイテストを変更する権限がありません。パートナー センター アカウントのマネージャーにアクセス権を依頼してください。 |
| 403 | `playtest_not_enabled` | ゲームと販売者に対してプレイテストが有効になっていないか、サービスが現在チェックできません。有効になっているはずの場合は、後でもう一度お試しください。 |
| 404 | `playtest_not_found` | ゲームに、その ID または `--compare-to` の ID のプレイテストがありません。メッセージには確認用の `playtest list` コマンドが表示されます。 |
| 404 | `game_not_found` | 販売者に、その Store ID のゲームがありません。`--store-id` と `--seller-id` を確認してください。 |
| 409 | `playtest_not_editable` | 公開中など、プレイテストの状態によって現在 `update` が許可されていません。`playtest get` で確認してください。 |
| 409 | `playtest_ended` | プレイテストが終了しており、`update` で `--end` が渡されませんでした。変更と一緒に将来の `--end` を渡してください。 |
| 409 | `playtest_not_publishable` | プレイテストの状態によって `publish` が許可されていないか、読み取り後にプレイテストが変更されました。`playtest get` で確認してください。 |
| 409 | `playtest_not_deletable` | プレイテストの状態によって `delete` が許可されていません。`playtest get` で確認してください。 |
| 412 | `playtest_precondition_failed` | 読み取り後にプレイテストが変更されました。`update` の場合は、`playtest get` を実行し、変更がまだ適用できることを確認してから、新しい `etag` で再試行してください。`publish` と `delete` の場合は、プレイテストを確認して再試行してください。 |
| 422 | `playtest_publish_blocked` | サービスの公開チェックが失敗したため、何もキューに登録されませんでした。コマンドは各チェックを一覧表示します。 |

その他の失敗では、コマンドはサービスのメッセージを表示します。429 は送信したリクエストが多すぎることを意味します。
もう一度試す前に、メッセージに示されている時間だけ待ってください。


## Related topics

- [Playtest の使用](https://docs.xbox.com/ja-jp/publishing/game-publishing/concepts/playtest-preview.md)
- [Playtest の概要](https://docs.xbox.com/ja-jp/publishing/game-publishing/concepts/playtest.md)
- [プレリリース テスト オプション](https://docs.xbox.com/ja-jp/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-prerelease.md)
- [製品変更とコンテンツ アップデート](https://docs.xbox.com/ja-jp/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-post-release-lifecycle.md)
- [サンドボックス](https://docs.xbox.com/ja-jp/publishing/game-publishing/concepts/sandboxes.md)
