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

# Entidade de serviço

> Conceda, inspecione e revogue o acesso ao PlayFab de uma entidade de serviço do Entra a um estúdio e aos títulos dele.

A família de comandos `playfab service-principal` é Experimental. Sua interface de CLI pode
mudar ou ser removida com base em comentários.

Um pipeline de integração contínua (CI) ou outro trabalho autônomo entra como uma entidade de serviço do Microsoft
Entra ID; consulte
[Autenticação de automação (entidade de serviço)](https://docs.xbox.com/pt-BR/tools/xbox-cli/authentication.md#automation-service-principal-authentication).
O PlayFab aceita a entidade de serviço somente depois que uma pessoa concede acesso a ela em um
estúdio do PlayFab. Estes comandos gerenciam essas concessões.

Somente uma pessoa conectada com a permissão **Admin** no estúdio pode executar estes comandos. Eles
se recusam a ser executados quando `XBOX_AUTHENTICATION__MODE` seleciona um modo de entidade de serviço; portanto, entre
com `xbox auth login`.

| Comando | Caminho da API do PlayFab | Descrição |
| - | - | - |
| `playfab service-principal list` | `/Studio/ListServicePrincipals` | Lista as entidades de serviço registradas em um estúdio. |
| `playfab service-principal get` | `/Studio/GetServicePrincipalAccess` | Mostra as concessões de uma entidade de serviço. |
| `playfab service-principal set` | `/Studio/SetServicePrincipalAccess` | Registra uma entidade de serviço, se necessário, e **substitui** todas as concessões dela. |
| `playfab service-principal revoke` | `/Studio/DeleteServicePrincipalAccess` | Remove uma entidade de serviço e todas as concessões dela de um estúdio. Pergunta primeiro; consulte [Segurança e operações destrutivas](https://docs.xbox.com/pt-BR/tools/xbox-cli/safety.md). |

| Comando | Opções |
| - | - |
| `service-principal list` | `--studio-id` (obrigatória), `--limit` (1-100), `--continuation-token`. |
| `service-principal get` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id` (todas obrigatórias). |
| `service-principal set` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id`, `--display-name`, `--grants-file` (todas obrigatórias), `--expected-version`. |
| `service-principal revoke` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id` (todas obrigatórias). |

`list` aceita `--output table`; os outros comandos não. `list` retorna uma página: quando
houver mais, o `ContinuationToken` da resposta será definido, e executar `list` novamente com
`--continuation-token` definido com esse valor obtém a próxima página.

## Identificadores

* `--studio-id` nomeia o estúdio proprietário das concessões. Estes comandos não aceitam um
  título do PlayFab; portanto, `--playfab-title-id` e o contexto salvo não se aplicam.
* `--principal-tenant-id` e `--principal-object-id` identificam a entidade de serviço: o
  locatário do Entra ID dela e a ID de objeto do aplicativo empresarial dela, e não do
  registro de aplicativo dela. `xbox auth status` a informa como `objectId` quando conectado como a entidade
  de serviço.
* Você não passa a ID do aplicativo (cliente). O PlayFab a registra com base no primeiro token da entidade
  de serviço, e `list` e `get` a informam como `ClientId`.
* As opções globais `--tenant-id` e `--client-id` configuram sua própria entrada, e não a
  entidade de serviço à qual você está concedendo acesso.

## Arquivo de concessões

> [!WARNING]
>
> `set` substitui todas as concessões da entidade de serviço pelo conteúdo de
> `--grants-file` e remove qualquer permissão de estúdio ou título que o arquivo omita.

Comece com base nas concessões atuais, em vez de escrever um arquivo do zero. Salve a saída de
`get`, edite os `StudioPermissions` e `TitleGrants` dela e passe-a para `set`, com a
`Version` dela como `--expected-version`:

```bash theme={null}
xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  > grants.json
```

Um arquivo de concessões pode ser a saída inteira de `get`, o `data` dela, o objeto `ServicePrincipal`
dentro dele ou somente as concessões:

```json theme={null}
{
  "StudioPermissions": [],
  "TitleGrants": [
    { "TitleId": "ABC123", "Permissions": ["Admin"] }
  ]
}
```

* Ambas as propriedades são obrigatórias. Uma lista vazia não concede nada desse tipo.
* Cada título precisa de pelo menos uma permissão. Para remover a concessão de um título, omita o título.
* Os nomes das propriedades não diferenciam maiúsculas de minúsculas. Uma propriedade não reconhecida é um erro; assim, um
  `TitleGrants` digitado incorretamente não pode remover todas as concessões de título.
* `TenantId`, `ObjectId` e `DisplayName` do arquivo, quando presentes, devem corresponder a
  `--principal-tenant-id`, `--principal-object-id` e `--display-name`. Para renomear a
  entidade de serviço, altere também `DisplayName` no arquivo ou remova-o.

### Versão esperada

Cada alteração nas concessões de uma entidade de serviço atribui a elas uma nova `Version`, que `get` e
`set` retornam. Com `--expected-version`, `set` não altera nada, a menos que as concessões ainda estejam
nessa versão; assim, ele não pode desfazer uma alteração que alguém fez depois que você as leu.
`--expected-version 0` exige que a entidade de serviço ainda não tenha acesso. Sem
`--expected-version`, `set` substitui as concessões, quaisquer que sejam elas no momento.

Quando o arquivo de concessões tem uma `Version`, `--expected-version` é obrigatória e deve ser igual a ela.
Se forem diferentes, execute `get` novamente e refaça suas edições na saída dele. Para substituir as concessões
de qualquer forma, remova `Version` do arquivo e omita `--expected-version`.

### Se `set` falhar

> [!WARNING]
>
> Se `set` falhar, a entidade de serviço poderá ficar sem acesso no estúdio até que um `set`
> seja bem-sucedido, o que pode interromper um pipeline.

Uma falha não informa se as concessões foram alteradas; portanto, não execute `set` novamente com a versão
antiga. Execute `get`, verifique as concessões e a `Version` e, se elas não forem o que você pretendia
definir, edite essa saída e passe-a para `set` com a `Version` dela como `--expected-version`.

## Exemplos

Listar as entidades de serviço de um estúdio e mostrar as concessões de uma delas:

```bash theme={null}
xbox playfab service-principal list \
  --studio-id 1234567890ABCDEF

xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777
```

Substituir as concessões da entidade de serviço pelas que estão em `grants.json`, que você salvou de
`get` e editou:

```bash theme={null}
xbox playfab service-principal set \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --display-name "Nod Publishers build" \
  --grants-file grants.json \
  --expected-version 3
```

Remover a entidade de serviço e as concessões dela do estúdio:

```bash theme={null}
xbox playfab service-principal revoke \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --confirm
```

Depois de `revoke`, a próxima solicitação da entidade de serviço ao PlayFab no estúdio falha. `revoke`
também é bem-sucedido quando a entidade de serviço já não tem acesso. Para restaurar o acesso, execute
`set` com o conjunto completo de concessões.


## Related topics

- [Problemas conhecidos](https://docs.xbox.com/pt-BR/tools/xbox-cli/known-issues.md)
- [Auth](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/auth.md)
- [Identificadores de entidade](https://docs.xbox.com/pt-BR/services/playfab/sdks/c/entity-handles.md)
- [Modelo de programação de entidades](https://docs.xbox.com/pt-BR/services/playfab/live-service-management/game-configuration/entities/index.md)
- [Arquivos de entidade](https://docs.xbox.com/pt-BR/services/playfab/live-service-management/game-configuration/entities/entity-files.md)
