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

# Entidad de servicio

> Concede, inspecciona y revoca el acceso de PlayFab de una entidad de servicio de Entra a un estudio y sus títulos.

La familia de comandos `playfab service-principal` es experimental. Su interfaz de la CLI puede
cambiar o quitarse en función de los comentarios.

Una canalización de integración continua (CI) u otro trabajo desatendido inicia sesión como una entidad de servicio de Microsoft
Entra ID; consulta
[Autenticación para automatización (entidad de servicio)](https://docs.xbox.com/es/tools/xbox-cli/authentication.md#automation-service-principal-authentication).
PlayFab acepta la entidad de servicio solo después de que una persona le conceda acceso en un estudio de
PlayFab. Estos comandos administran esas concesiones.

Solo una persona que haya iniciado sesión y tenga el permiso **Admin** en el estudio puede ejecutar estos comandos.
Se niegan a ejecutarse cuando `XBOX_AUTHENTICATION__MODE` selecciona un modo de entidad de servicio, así que inicia sesión
con `xbox auth login` en su lugar.

| Comando | Ruta de la API de PlayFab | Descripción |
| - | - | - |
| `playfab service-principal list` | `/Studio/ListServicePrincipals` | Enumera las entidades de servicio registradas en un estudio. |
| `playfab service-principal get` | `/Studio/GetServicePrincipalAccess` | Muestra las concesiones de una entidad de servicio. |
| `playfab service-principal set` | `/Studio/SetServicePrincipalAccess` | Registra una entidad de servicio si es necesario y **reemplaza** todas sus concesiones. |
| `playfab service-principal revoke` | `/Studio/DeleteServicePrincipalAccess` | Quita de un estudio una entidad de servicio y todas sus concesiones. Pregunta primero; consulta [Seguridad y operaciones destructivas](https://docs.xbox.com/es/tools/xbox-cli/safety.md). |

| Comando | Opciones |
| - | - |
| `service-principal list` | `--studio-id` (obligatoria), `--limit` (1-100), `--continuation-token`. |
| `service-principal get` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id` (todas obligatorias). |
| `service-principal set` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id`, `--display-name`, `--grants-file` (todas obligatorias), `--expected-version`. |
| `service-principal revoke` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id` (todas obligatorias). |

`list` acepta `--output table`; los demás comandos no. `list` devuelve una página: cuando
existen más, se establece el `ContinuationToken` de la respuesta, y volver a ejecutar `list` con
`--continuation-token` establecido en ese valor obtiene la página siguiente.

## Identificadores

* `--studio-id` indica el estudio propietario de las concesiones. Estos comandos no aceptan un
  título de PlayFab, por lo que `--playfab-title-id` y el contexto guardado no se aplican.
* `--principal-tenant-id` y `--principal-object-id` identifican la entidad de servicio: su
  inquilino de Entra ID y el identificador de objeto de su aplicación empresarial, no el de su
  registro de aplicación. `xbox auth status` lo indica como `objectId` cuando se ha iniciado sesión como la
  entidad de servicio.
* No pasas el identificador de aplicación (cliente). PlayFab lo registra a partir del primer token de la entidad
  de servicio, y `list` y `get` lo indican como `ClientId`.
* Las opciones globales `--tenant-id` y `--client-id` configuran tu propio inicio de sesión, no la
  entidad de servicio a la que concedes acceso.

## Archivo de concesiones

> [!WARNING]
>
> `set` reemplaza todas las concesiones de la entidad de servicio por el contenido de
> `--grants-file`, y quita cualquier permiso de estudio o título que el archivo omita.

Parte de las concesiones actuales en lugar de escribir un archivo desde cero. Guarda la salida de
`get`, edita sus `StudioPermissions` y `TitleGrants`, y pásala a `set`, con su
`Version` 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
```

Un archivo de concesiones puede ser la salida completa de `get`, su `data`, el objeto `ServicePrincipal`
que contiene o solo las concesiones:

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

* Ambas propiedades son obligatorias. Una lista vacía no concede nada de ese tipo.
* Cada título necesita al menos un permiso. Para quitar la concesión de un título, omite el título.
* Los nombres de propiedad no distinguen mayúsculas de minúsculas. Una propiedad no reconocida es un error, de modo que un
  `TitleGrants` mal escrito no puede quitar todas las concesiones de títulos.
* Los valores `TenantId`, `ObjectId` y `DisplayName` del archivo, cuando están presentes, deben coincidir con
  `--principal-tenant-id`, `--principal-object-id` y `--display-name`. Para cambiar el nombre de la
  entidad de servicio, cambia también `DisplayName` en el archivo o quítalo.

### Versión esperada

Cada cambio en las concesiones de una entidad de servicio les asigna una nueva `Version`, que devuelven `get` y
`set`. Con `--expected-version`, `set` no cambia nada a menos que las concesiones sigan
en esa versión, por lo que no puede deshacer un cambio que alguien hizo después de que las leyeras.
`--expected-version 0` requiere que la entidad de servicio aún no tenga acceso. Sin
`--expected-version`, `set` reemplaza las concesiones sean cuales sean en ese momento.

Cuando el archivo de concesiones tiene una `Version`, `--expected-version` es obligatoria y debe ser igual a ella.
Si son distintas, vuelve a ejecutar `get` y rehaz tus modificaciones sobre su salida. Para reemplazar las concesiones
de todos modos, quita `Version` del archivo y omite `--expected-version`.

### Si `set` falla

> [!WARNING]
>
> Si `set` falla, es posible que la entidad de servicio no tenga acceso en el estudio hasta que un `set`
> se complete correctamente, lo que puede dejar sin acceso a una canalización.

Un error no indica si las concesiones cambiaron, así que no vuelvas a ejecutar `set` con la versión
anterior. Ejecuta `get`, comprueba sus concesiones y su `Version` y, si no son las que querías
establecer, edita esa salida y pásala a `set` con su `Version` como `--expected-version`.

## Ejemplos

Enumerar las entidades de servicio de un estudio y mostrar las concesiones de una:

```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
```

Reemplazar las concesiones de la entidad de servicio por las de `grants.json`, que guardaste a partir de
`get` y editaste:

```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
```

Quitar del estudio la entidad de servicio y sus concesiones:

```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
```

Después de `revoke`, la siguiente solicitud de PlayFab de la entidad de servicio en el estudio falla. `revoke`
también se completa correctamente cuando la entidad de servicio ya no tiene acceso. Para restaurar el acceso, ejecuta
`set` con el conjunto completo de concesiones.


## Related topics

- [Identificadores de entidad](https://docs.xbox.com/es/services/playfab/sdks/c/entity-handles.md)
- [Archivos de entidad](https://docs.xbox.com/es/services/playfab/live-service-management/game-configuration/entities/entity-files.md)
- [Servidores de juegos a partir de una entidad de título](https://docs.xbox.com/es/services/playfab/sdks/c/server.md)
- [Modelo de programación de entidades](https://docs.xbox.com/es/services/playfab/live-service-management/game-configuration/entities/index.md)
- [Tipos de entidad integrados disponibles](https://docs.xbox.com/es/services/playfab/live-service-management/game-configuration/entities/available-built-in-entity-types.md)
