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

# 対象ユーザー

> パートナー センターの販売者の対象ユーザーを一覧表示、取得、作成、更新します。

対象ユーザーは、テスターなど、販売者がコンテンツの対象にできるプレイヤーまたはデバイスの名前付きグループです。
パートナー センターでは、これを顧客グループと呼びます。`audience` コマンドは、販売者の対象ユーザーを一覧表示および
取得し、既知のユーザーの対象ユーザーを作成し、対象ユーザーの名前を変更したりメンバーを置き換えたりします。対象ユーザーが
プレイテストに参加できるようにするには、その `id` を `playtest create` または `playtest update` に渡します。
[対象ユーザーの選択](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/playtest.md#choosing-audiences)を参照してください。

`audience` は試験段階 (Experimental) です。コマンド、オプション、出力は変更または削除される可能性があります。
[試験段階のコマンド](https://docs.xbox.com/ja-jp/tools/xbox-cli/cli-command-lifecycle.md)を参照してください。対象ユーザーの一覧表示と取得には、
販売者に対するパートナー センターの顧客グループの読み取り権限が必要であり、作成と更新には書き込み権限が
必要です。

## コマンド

| コマンド | 説明 |
| - | - |
| `audience list` | 販売者の対象ユーザーを一覧表示します。 |
| `audience get <audience-id>` | 対象ユーザーを 1 つ、メンバーと共に取得します。 |
| `audience create` | 既知のユーザーの対象ユーザーを作成します。 |
| `audience update <audience-id>` | 既知のユーザーの対象ユーザーの名前を変更するか、メンバー リスト全体を置き換えます。 |

CLI では、対象ユーザーを削除したり、種類を変更したりすることはできません。これらはパートナー センターで行ってください。

## 引数とオプション

| 引数またはオプション | 適用対象 | 必須 | 説明 |
| - | - | - | - |
| `<audience-id>` | `get`、`update` | はい | `list` から返されたとおりの対象ユーザー ID (`1152921504606846976` など)。 |
| `--name <text>` | `list` | いいえ | 名前にこのテキストが含まれる対象ユーザーのみを一覧表示します。大文字と小文字は区別されません。 |
| `--name <text>` | `create`、`update` | `create` | 対象ユーザーの名前 (最大 200 文字)。空白にすることはできませんが、一意である必要はありません。 |
| `--members-file <path>` | `create`、`update` | いいえ | メンバーを一覧表示したファイル。[メンバー ファイル](#members-files)を参照してください。 |
| `--confirm` (`--yes`、`-y`) | `create`、`update` | いいえ | 確認プロンプトをスキップします。指定しない場合、コマンドはターミナルでは確認を求め、それ以外では失敗します。 |
| `--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`。 |

## 出力

`audience get` は対象ユーザーを 1 つ書き込みます。

```json theme={null}
{
  "name": "Nod Arena testers",
  "id": "1152921504606846976",
  "members": ["dev@nodpublishers.com"],
  "dnaTags": ["AppFlighting"],
  "sellerId": "1234567",
  "groupType": "User",
  "groupUsage": "ForPackageFlight, ForLimitedDistribution"
}
```

| フィールド | 説明 |
| - | - |
| `name` | 対象ユーザーの名前、または `null`。 |
| `id` | 対象ユーザー ID。他のコマンドにそのまま渡します。 |
| `members` | 保存されているメンバー。`list` ではこのフィールドは省略されます。 |
| `dnaTags` | 対象ユーザーのタグ。 |
| `sellerId` | 対象ユーザーを所有する販売者。 |
| `groupType` | 対象ユーザーの種類 (`User`、`PreCreated`、`XboxDevice` など)、または `null`。更新できるのは `User` の対象ユーザーのみです。 |
| `groupUsage` | 対象ユーザーの用途を示すコンマ区切りのフラグ、または `null`。 |

`audience list` は、同じオブジェクトから `members` を除いた `audiences` 配列を書き込み、対象ユーザーがない場合は
`{"audiences":[]}` を書き込みます。`create` と `update` は、`get` と同じように対象ユーザーを書き込みます。

`--output table` を指定すると、すべてのコマンドで `ID`、`NAME`、`TYPE` の列が表示されます。`TYPE` は
`groupType` です。メンバーは JSON 出力にのみ含まれます。

## 対象ユーザーの作成

```bash theme={null}
xbox audience create --name "Nod Arena testers" --members-file testers.txt
```

`--members-file` を指定しない場合、対象ユーザーにメンバーはいません。同じ名前の対象ユーザーが存在する場合でも、
実行するたびに新しい対象ユーザーが作成されます。

## 対象ユーザーの更新

`--name`、`--members-file`、またはその両方を渡します。省略したものは保持されます。次の例では、対象ユーザーの名前を変更します。

```bash theme={null}
xbox audience update 1152921504606846976 --name "Nod Arena beta testers"
```

次の例では、メンバーを `testers.txt` のアドレスに置き換えます。

```bash theme={null}
xbox audience update 1152921504606846976 --members-file testers.txt
```

> [!WARNING]
>
> `--members-file` はメンバー リスト全体を置き換えます。ファイルに含まれていないメンバーは削除され、
> 空のファイルを指定するとすべてのメンバーが削除されます。メンバーを 1 人追加または削除するには、`audience get` でリストを読み取り、
> 変更してから、リスト全体を渡します。

更新は他の変更と照合されません。2 人が同時に対象ユーザーを更新した場合は、
最後の更新が優先されます。

## メンバー ファイル

メンバー ファイルは、1 行に 1 つのメール アドレスを記述した UTF-8 テキストで、最大 1000 メンバーまで指定できます。

```text theme={null}
dev@nodpublishers.com
tester@nodpublishers.com
```

空白行と各行の前後のスペースは無視されます。サービスは各メンバーをチェックしますが、メンバーが保存されていても、
そのメンバーが対象ユーザー向けのコンテンツを表示できるアカウントに解決されるとは限りません。

## 終了コード

| 終了コード | 意味 |
| - | - |
| `0` | コマンドは成功しました。 |
| `1` | コマンドは失敗し、何も変更されていません。 |
| `3` | `create` または `update` は要求を送信しましたが、結果は不明です。相関 ID は stderr に出力されます。 |

`create` と `update` は要求を 1 回だけ送信します。終了コード `3` の後は、コマンドを再実行する前に
確認してください。

* `create` の後は、stderr に表示される `xbox audience list --name` コマンドを実行します。名前は一意である必要がないため、
  一致したものはヒントにすぎません。また、`create` を再実行すると 2 つ目の対象ユーザーが作成される可能性があります。
* `update` の後は、`xbox audience get <audience-id>` を実行して名前とメンバーを確認します。

## エラー

エラーは `--output` の値にかかわらずテキストとして stderr に出力され、相関 ID、HTTP ステータスに応じたガイダンス、
およびサービスのエラーの詳細 (ある場合) が含まれます。`--verbose` を指定するとサービスの応答が追加され、
これにはメンバーが含まれる場合があります。スクリプトでは、文言ではなく終了コードで分岐してください。

403 は、権限がないこと、販売者に所属していないこと、または販売者に対してプレイテストが有効になっていないことを
示している可能性があります。`list` と `get` では、拒否が代わりに 502 として表示される場合があります。原因については
エラーの詳細を確認してください。対象ユーザーの作成と更新は段階的にロールアウト中であり、まだ利用できない場合があります。
利用可能になるまでは、`create` と `update` は何も変更せずに失敗します。

## 例

対象ユーザーを一覧表示および取得します。

```bash theme={null}
xbox audience list --name testers
xbox audience list --output table
xbox audience get 1152921504606846976 --seller-id 1234567
```

確認プロンプトなしで対象ユーザーを作成します。

```bash theme={null}
xbox audience create --name "Nod Arena testers" --members-file testers.txt --confirm
```

対象ユーザーのメンバーを置き換え、結果を表として表示します。

```bash theme={null}
xbox audience update 1152921504606846976 --members-file testers.txt --output table
```


## Related topics

- [表示範囲](https://docs.xbox.com/ja-jp/publishing/game-publishing/concepts/availability/visibility.md)
- [表示範囲 - 対象ユーザー](https://docs.xbox.com/ja-jp/publishing/game-publishing/concepts/availability/visibility-audiences.md)
- [XBOX Insider Program のフライティング](https://docs.xbox.com/ja-jp/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-xbox-insider-flighting.md)
- [Playtest](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/playtest.md)
- [game_chat_communication_relationship_flags](https://docs.xbox.com/ja-jp/reference/chat/gamechat2/enums/game_chat_communication_relationship_flags.md)
