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

# Público

> Liste, obtenha, crie e atualize os públicos de um vendedor do Partner Center.

Um público é um grupo nomeado de jogadores ou dispositivos, como testadores, para o qual um vendedor pode direcionar
conteúdo. O Partner Center chama esses públicos de grupos de clientes. Os comandos `audience` listam e obtêm os
públicos de um vendedor, criam públicos de usuários conhecidos e renomeiam um público ou substituem seus membros. Para permitir que um
público participe de um playtest, passe a `id` dele para `playtest create` ou `playtest update`; consulte
[Escolher públicos](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/playtest.md#choosing-audiences).

`audience` é Experimental: seus comandos, opções e saída podem mudar ou ser removidos. Consulte
[Comandos experimentais](https://docs.xbox.com/pt-BR/tools/xbox-cli/cli-command-lifecycle.md). Listar e obter públicos exige a permissão
Read de grupos de clientes do Partner Center para o vendedor, e criá-los e atualizá-los exige a permissão
Write.

## Comandos

| Comando | Descrição |
| - | - |
| `audience list` | Lista os públicos do vendedor. |
| `audience get <audience-id>` | Obtém um público, com seus membros. |
| `audience create` | Cria um público de usuários conhecidos. |
| `audience update <audience-id>` | Renomeia um público de usuários conhecidos ou substitui a lista completa de membros dele. |

A CLI não pode excluir um público nem alterar o tipo dele; faça isso no Partner Center.

## Argumentos e opções

| Argumento ou opção | Aplica-se a | Obrigatório | Descrição |
| - | - | - | - |
| `<audience-id>` | `get`, `update` | Sim | ID do público, exatamente como `list` a retorna, como `1152921504606846976`. |
| `--name <text>` | `list` | Não | Lista somente os públicos cujo nome contém este texto, sem diferenciar maiúsculas de minúsculas. |
| `--name <text>` | `create`, `update` | `create` | Nome do público, com até 200 caracteres. Não pode ficar em branco e não precisa ser exclusivo. |
| `--members-file <path>` | `create`, `update` | Não | Arquivo que lista os membros. Consulte [Arquivos de membros](#members-files). |
| `--confirm` (`--yes`, `-y`) | `create`, `update` | Não | Ignora a solicitação de confirmação. Sem essa opção, o comando pergunta em um terminal e falha nos demais casos. |
| `--seller-id <id>` | todos | Se não estiver salva | ID do vendedor no Partner Center. Consulte [Contexto](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md). |
| `--base-url <url>` | todos | Não | URL base das solicitações, que substitui a chave de configuração `XboxPartner:BaseUrl`. |
| `--output <format>` | todos | Não | `json` (padrão), `json-compact` ou `table`. |

## Saída

`audience get` grava um público:

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

| Campo | Descrição |
| - | - |
| `name` | O nome do público ou `null`. |
| `id` | A ID do público. Passe-a para outros comandos sem alterações. |
| `members` | Os membros armazenados. `list` omite este campo. |
| `dnaTags` | As marcas do público. |
| `sellerId` | O vendedor proprietário do público. |
| `groupType` | O tipo do público, como `User`, `PreCreated` ou `XboxDevice`, ou `null`. Somente públicos `User` podem ser atualizados. |
| `groupUsage` | A finalidade do público, como sinalizadores separados por vírgulas, ou `null`. |

`audience list` grava uma matriz `audiences` com os mesmos objetos, sem `members`, e
`{"audiences":[]}` quando não há nenhum. `create` e `update` gravam o público da mesma forma que `get`.

Com `--output table`, todos os comandos mostram as colunas `ID`, `NAME` e `TYPE`, em que `TYPE` é
`groupType`. Os membros aparecem somente na saída JSON.

## Criar um público

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

Sem `--members-file`, o público não tem membros. Cada execução cria um novo público, mesmo quando
já existe um com o mesmo nome.

## Atualizar um público

Passe `--name`, `--members-file` ou ambos; o que você omitir será mantido. Este comando renomeia um público:

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

Este substitui os membros dele pelos endereços em `testers.txt`:

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

> [!WARNING]
>
> `--members-file` substitui a lista completa de membros. Os membros que não estiverem no arquivo serão removidos, e um
> arquivo vazio remove todos os membros. Para adicionar ou remover um membro, leia a lista com `audience get`,
> altere-a e passe a lista inteira.

A atualização não é verificada em relação a outras alterações: se duas pessoas atualizarem um público ao mesmo tempo, a
última prevalece.

## Arquivos de membros

Um arquivo de membros é um texto UTF-8 com um endereço de email por linha, com até 1.000 membros:

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

Linhas em branco e espaços ao redor de cada linha são ignorados. O serviço verifica cada membro, mas um membro
armazenado não comprova que ele corresponde a uma conta que pode ver o conteúdo direcionado ao público.

## Códigos de saída

| Código de saída | Significado |
| - | - |
| `0` | O comando foi bem-sucedido. |
| `1` | O comando falhou e nada foi alterado. |
| `3` | `create` ou `update` enviou sua solicitação, mas o resultado é desconhecido. A ID de correlação está em stderr. |

`create` e `update` enviam sua solicitação uma única vez. Depois do código de saída `3`, verifique antes de executar o comando
novamente:

* Depois de `create`, execute o comando `xbox audience list --name` que stderr mostra. Uma correspondência é apenas uma
  indicação, porque os nomes não precisam ser exclusivos, e executar `create` novamente pode criar um segundo
  público.
* Depois de `update`, execute `xbox audience get <audience-id>` para verificar o nome e os membros dele.

## Erros

Os erros vão para stderr como texto, qualquer que seja o valor de `--output`, com a ID de correlação, orientações para o
status HTTP e o detalhe do erro do serviço, quando houver. `--verbose` adiciona a resposta do serviço,
que pode incluir membros. Os scripts devem se basear no código de saída, e não no texto da mensagem.

Um 403 pode significar uma permissão ausente, que você não pertence ao vendedor ou que os playtests
não estão habilitados para ele. Em `list` e `get`, uma recusa pode aparecer como 502; verifique o
detalhe do erro para saber a causa. A criação e a atualização de públicos estão sendo distribuídas e talvez ainda não estejam disponíveis
para você; até que estejam, `create` e `update` falham sem alterar nada.

## Exemplos

Listar e obter públicos:

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

Criar um público sem a solicitação de confirmação:

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

Substituir os membros de um público e mostrar o resultado como uma tabela:

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


## Related topics

- [Visibilidade - Públicos](https://docs.xbox.com/pt-BR/publishing/game-publishing/concepts/availability/visibility-audiences.md)
- [Visibilidade](https://docs.xbox.com/pt-BR/publishing/game-publishing/concepts/availability/visibility.md)
- [Configurar preços e disponibilidade para um jogo](https://docs.xbox.com/pt-BR/publishing/game-publishing/tutorial-xbox-managed/how-to-configure-pricing-and-availability.md)
- [Flighting do Programa XBOX Insider](https://docs.xbox.com/pt-BR/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-xbox-insider-flighting.md)
- [Opções de teste de pré-lançamento](https://docs.xbox.com/pt-BR/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-prerelease.md)
