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

# 受众

> 列出、获取、创建和更新 Partner Center 卖家的受众。

受众是已命名的一组玩家或设备(例如测试人员),卖家可以将内容定向到这些受众。Partner Center 将其称为客户组。`audience` 命令可列出和获取卖家的受众、创建已知用户受众,以及重命名受众或替换其成员。若要允许某个受众加入游戏测试,请将其 `id` 传递给 `playtest create` 或 `playtest update`;请参阅
[选择受众](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playtest.md#choosing-audiences)。

`audience` 属于实验性命令:其命令、选项和输出可能会更改或被删除。请参阅
[实验性命令](https://docs.xbox.com/zh-CN/tools/xbox-cli/cli-command-lifecycle.md)。列出和获取受众需要具有该卖家的 Partner
Center 客户组“读取”权限,创建和更新受众则需要“写入”权限。

## 命令

| 命令 | 说明 |
| - | - |
| `audience list` | 列出卖家的受众。 |
| `audience get <audience-id>` | 获取一个受众及其成员。 |
| `audience create` | 创建已知用户受众。 |
| `audience update <audience-id>` | 重命名已知用户受众或替换其完整成员列表。 |

CLI 无法删除受众或更改其类型;请在 Partner Center 中执行这些操作。

## 参数和选项

| 参数或选项 | 适用于 | 必需 | 说明 |
| - | - | - | - |
| `<audience-id>` | `get`、`update` | 是 | 受众 ID,与 `list` 返回的完全一致,例如 `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>` | 全部 | 如果未保存 | Partner Center 卖家 ID。请参阅[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。 |
| `--base-url <url>` | 全部 | 否 | 请求的基 URL,覆盖 `XboxPartner:BaseUrl` 配置键。 |
| `--output <format>` | 全部 | 否 | `json`(默认)、`json-compact` 或 `table`。 |

## 输出

`audience get` 写入一个受众:

```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` 写入一个由相同对象组成的 `audiences` 数组,不包含 `members`;如果没有受众,则写入
`{"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` 会替换完整的成员列表。不在文件中的成员会被删除,空文件会删除所有成员。若要添加或删除一个成员,请使用 `audience get` 读取列表,对其进行更改,然后传递整个列表。

更新不会针对其他更改进行检查:如果两个人同时更新某个受众,则以最后一次更新为准。

## 成员文件

成员文件是 UTF-8 文本,每行一个电子邮件地址,最多 1000 个成员:

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

空行以及每行前后的空格会被忽略。服务会检查每个成员,但已存储的成员并不能证明它会解析为可以看到定向到该受众的内容的帐户。

## 退出代码

| 退出代码 | 含义 |
| - | - |
| `0` | 命令已成功。 |
| `1` | 命令失败,并且未进行任何更改。 |
| `3` | `create` 或 `update` 已发送其请求,但结果未知。关联 ID 会输出到 stderr。 |

`create` 和 `update` 只发送一次请求。以代码 `3` 退出后,请在再次运行命令之前进行检查:

* 在 `create` 之后,运行 stderr 中显示的 `xbox audience list --name` 命令。匹配项只是一个
  提示,因为名称不必唯一,并且再次运行 `create` 可能会创建第二个受众。
* 在 `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/zh-CN/publishing/game-publishing/concepts/availability/visibility-audiences.md)
- [为游戏配置定价和可用性](https://docs.xbox.com/zh-CN/publishing/game-publishing/tutorial-xbox-managed/how-to-configure-pricing-and-availability.md)
- [可见性](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/availability/visibility.md)
- [Playtest](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playtest.md)
- [XBOX Insider Program 外部测试](https://docs.xbox.com/zh-CN/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-xbox-insider-flighting.md)
