> ## 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` 명령은 판매자의 대상 그룹을
나열하고 가져오며, 알려진 사용자 대상 그룹을 생성하고, 대상 그룹의 이름을 바꾸거나 구성원을 대체합니다.
대상 그룹이 플레이테스트에 참여할 수 있게 하려면 `playtest create` 또는 `playtest update`에 해당
`id`를 전달하세요.
[대상 그룹 선택](https://docs.xbox.com/ko/tools/xbox-cli/commands/playtest.md#choosing-audiences)을 참조하세요.

`audience`는 실험적 기능입니다. 명령, 옵션 및 출력이 변경되거나 제거될 수 있습니다.
[실험적 명령](https://docs.xbox.com/ko/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` | 예 | `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>` | 모두 | 저장되지 않은 경우 | Partner Center 판매자 ID입니다. [컨텍스트](https://docs.xbox.com/ko/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`는 같은 개체를 `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`은 전체 구성원 목록을 대체합니다. 파일에 없는 구성원은 제거되며, 빈 파일은 모든
> 구성원을 제거합니다. 구성원 하나를 추가하거나 제거하려면 `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/ko/publishing/game-publishing/concepts/availability/visibility.md)
- [가시성 - 대상 그룹](https://docs.xbox.com/ko/publishing/game-publishing/concepts/availability/visibility-audiences.md)
- [Playtest](https://docs.xbox.com/ko/tools/xbox-cli/commands/playtest.md)
- [Playtest 사용](https://docs.xbox.com/ko/publishing/game-publishing/concepts/playtest-preview.md)
- [첫 번째 플레이테스트](https://docs.xbox.com/ko/tools/xbox-cli/first-playtest.md)
