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

# Principal de service

> Accordez, inspectez et révoquez l'accès PlayFab d'un principal de service Entra à un studio et à ses titres.

La famille de commandes `playfab service-principal` est expérimentale. Son interface CLI pourrait
changer ou être retirée en fonction des commentaires.

Un pipeline d'intégration continue (CI) ou une autre tâche sans surveillance se connecte en tant que principal de service
Microsoft Entra ID; consultez
[Authentification pour l'automatisation (principal de service)](https://docs.xbox.com/fr-CA/tools/xbox-cli/authentication.md#automation-service-principal-authentication).
PlayFab accepte le principal de service seulement après qu'une personne lui a accordé l'accès dans un studio
PlayFab. Ces commandes gèrent ces octrois d'accès.

Seule une personne connectée disposant de l'autorisation **Admin** sur le studio peut exécuter ces commandes. Elles
refusent de s'exécuter lorsque `XBOX_AUTHENTICATION__MODE` sélectionne un mode de principal de service; connectez-vous donc plutôt
avec `xbox auth login`.

| Commande | Chemin de l'API PlayFab | Description |
| - | - | - |
| `playfab service-principal list` | `/Studio/ListServicePrincipals` | Répertorie les principaux de service inscrits dans un studio. |
| `playfab service-principal get` | `/Studio/GetServicePrincipalAccess` | Affiche les octrois d'accès d'un principal de service. |
| `playfab service-principal set` | `/Studio/SetServicePrincipalAccess` | Inscrit un principal de service au besoin, et **remplace** tous ses octrois d'accès. |
| `playfab service-principal revoke` | `/Studio/DeleteServicePrincipalAccess` | Retire d'un studio un principal de service et tous ses octrois d'accès. Demande d'abord une confirmation; consultez [Sécurité et opérations destructrices](https://docs.xbox.com/fr-CA/tools/xbox-cli/safety.md). |

| Commande | Options |
| - | - |
| `service-principal list` | `--studio-id` (obligatoire), `--limit` (1-100), `--continuation-token`. |
| `service-principal get` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id` (toutes obligatoires). |
| `service-principal set` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id`, `--display-name`, `--grants-file` (toutes obligatoires), `--expected-version`. |
| `service-principal revoke` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id` (toutes obligatoires). |

`list` accepte `--output table`; les autres commandes ne l'acceptent pas. `list` retourne une seule page : lorsqu'il
y en a d'autres, le `ContinuationToken` de la réponse est défini, et exécuter `list` de nouveau avec
`--continuation-token` défini à cette valeur permet d'obtenir la page suivante.

## Identificateurs

* `--studio-id` nomme le studio propriétaire des octrois d'accès. Ces commandes n'acceptent pas de
  titre PlayFab; `--playfab-title-id` et le contexte enregistré ne s'appliquent donc pas.
* `--principal-tenant-id` et `--principal-object-id` identifient le principal de service : son
  locataire Entra ID et l'ID d'objet de son application d'entreprise, et non celui de son inscription
  d'application. `xbox auth status` l'indique sous la forme `objectId` lorsque vous êtes connecté en tant que principal
  de service.
* Vous ne transmettez pas l'ID d'application (client). PlayFab l'enregistre à partir du premier jeton du principal
  de service, et `list` et `get` l'indiquent sous la forme `ClientId`.
* Les options globales `--tenant-id` et `--client-id` configurent votre propre connexion, et non le
  principal de service auquel vous accordez l'accès.

## Fichier d'octrois d'accès

> [!WARNING]
>
> `set` remplace tous les octrois d'accès du principal de service par le contenu de
> `--grants-file`, et retire toute autorisation de studio ou tout titre que le fichier omet.

Partez des octrois d'accès actuels plutôt que d'écrire un fichier à partir de zéro. Enregistrez la sortie de
`get`, modifiez ses `StudioPermissions` et `TitleGrants`, puis transmettez-la à `set`, avec sa
`Version` comme valeur de `--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 fichier d'octrois d'accès peut être la sortie complète de `get`, son champ `data`, l'objet `ServicePrincipal`
qu'il contient, ou seulement les octrois d'accès :

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

* Les deux propriétés sont obligatoires. Une liste vide n'accorde rien de ce type.
* Chaque titre a besoin d'au moins une autorisation. Pour retirer l'octroi d'accès d'un titre, omettez le titre.
* Les noms de propriétés ne sont pas sensibles à la casse. Une propriété non reconnue constitue une erreur; ainsi, un
  `TitleGrants` mal orthographié ne peut pas retirer tous les octrois d'accès aux titres.
* Les valeurs `TenantId`, `ObjectId` et `DisplayName` du fichier, lorsqu'elles sont présentes, doivent correspondre à
  `--principal-tenant-id`, `--principal-object-id` et `--display-name`. Pour renommer le
  principal de service, modifiez aussi `DisplayName` dans le fichier, ou retirez-le.

### Version attendue

Chaque modification des octrois d'accès d'un principal de service leur attribue une nouvelle `Version`, que retournent `get` et
`set`. Avec `--expected-version`, `set` ne modifie rien, sauf si les octrois d'accès sont toujours
à cette version; elle ne peut donc pas annuler une modification effectuée par quelqu'un après que vous les avez lus.
`--expected-version 0` exige que le principal de service n'ait encore aucun accès. Sans
`--expected-version`, `set` remplace les octrois d'accès, quels qu'ils soient actuellement.

Lorsque le fichier d'octrois d'accès contient une `Version`, `--expected-version` est obligatoire et doit lui être égale.
Si elles diffèrent, exécutez `get` de nouveau et refaites vos modifications sur sa sortie. Pour remplacer les octrois d'accès
dans tous les cas, retirez `Version` du fichier et omettez `--expected-version`.

### Si `set` échoue

> [!WARNING]
>
> Si `set` échoue, le principal de service pourrait n'avoir aucun accès dans le studio jusqu'à ce qu'une commande `set`
> réussisse, ce qui peut interrompre un pipeline.

Un échec n'indique pas si les octrois d'accès ont changé; n'exécutez donc pas `set` de nouveau avec l'ancienne
version. Exécutez `get`, vérifiez ses octrois d'accès et sa `Version` et, s'ils ne correspondent pas à ce que vous vouliez
définir, modifiez cette sortie et transmettez-la à `set` avec sa `Version` comme valeur de `--expected-version`.

## Exemples

Répertorier les principaux de service d'un studio et afficher les octrois d'accès de l'un d'eux :

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

Remplacer les octrois d'accès du principal de service par ceux de `grants.json`, que vous avez enregistré à partir de
`get` et modifié :

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

Retirer le principal de service et ses octrois d'accès du studio :

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

Après `revoke`, la requête PlayFab suivante du principal de service dans le studio échoue. `revoke`
réussit aussi lorsque le principal de service n'a déjà aucun accès. Pour rétablir l'accès, exécutez
`set` avec l'ensemble complet des octrois d'accès.


## Related topics

- [Votre premier test de jeu](https://docs.xbox.com/fr-CA/tools/xbox-cli/first-playtest.md)
- [Auth](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/auth.md)
- [Problèmes connus](https://docs.xbox.com/fr-CA/tools/xbox-cli/known-issues.md)
- [Authentification](https://docs.xbox.com/fr-CA/tools/xbox-cli/authentication.md)
- [Programme de services payants de certification](https://docs.xbox.com/fr-CA/publishing/game-publishing/concepts/certification/certification-paid-services.md)
