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

# Utiliser l'XBOX CLI à partir d'agents

> Comment un agent d'IA exécute l'XBOX CLI, de la connexion et du choix d'une cible à la lecture de la sortie et à l'obtention d'une approbation avant de modifier quoi que ce soit.

L'XBOX CLI (`xbox`) est conçue pour être exécutée par des agents d'IA et des scripts aussi bien que par des personnes. Ses
commandes acceptent des arguments explicites, ses commandes de données écrivent du JSON, et ses erreurs sont envoyées à stderr
avec un code de sortie différent de zéro. Cette page s'adresse aux agents et aux personnes qui les configurent : comment
se connecter, choisir ce sur quoi une commande agit, lire sa sortie et trouver la bonne API, et quoi
demander avant de modifier quoi que ce soit.

## Avant de modifier quoi que ce soit

L'utilisateur connecté dispose habituellement de droits d'administrateur sur les titres et les vendeurs de production, et rien du
côté serveur n'empêche un appel erroné. [Sécurité et opérations destructrices](https://docs.xbox.com/fr-CA/tools/xbox-cli/safety.md) répertorie
ce pour quoi la CLI demande une confirmation et ce pour quoi elle n'en demande pas. Le reste vous incombe :

* Considérez une opération PlayFab comme étant en lecture seule uniquement si son nom commence par `Get`, `List` ou
  `Search`. Considérez toute autre opération, et toute commande `xbox` qui crée, modifie ou
  supprime quelque chose, comme une modification de production.
* Avant une modification de production, montrez la commande à l'utilisateur et indiquez en une phrase ce qu'elle
  modifie et sur quel titre ou vendeur, en précisant si cette cible provient du contexte
  enregistré. Exécutez-la uniquement après qu'il a dit oui, même si votre environnement d'exécution exécuterait `xbox` sans
  demander. Un oui couvre uniquement les appels que vous avez montrés.
* Passez le titre ou le vendeur sous forme d'indicateur pour chaque modification de production. Le contexte enregistré est partagé par
  toutes les sessions de l'utilisateur du système d'exploitation; il peut donc changer entre le oui de l'utilisateur et votre appel.
* Demandez avant `xbox pc sandbox set`, qui change le sandbox pour tous les utilisateurs du PC, et
  avant `xbox pc sandbox launch-apps`, qui ferme le Microsoft Store et l'application XBOX.
* N'ajoutez pas `--confirm` (ni `--yes`) au lieu de demander. La CLI ne peut pas savoir qui l'a ajouté.
* Avant de demander à publier dans RETAIL avec `xbox xbl config publish`, exécutez la commande avec
  `--validate-only` et montrez à l'utilisateur les succès qu'elle répertorie. Publiez ensuite avec
  `--configset` défini sur la valeur `SourceVersion` de sa sortie JSON. Les succès dans RETAIL ne peuvent pas être
  retirés; consultez
  [Succès ajoutés par une publication dans RETAIL](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/xbl.md#achievements-a-retail-publish-adds).
* Si une modification de production échoue et que son résultat est inconnu, elle a peut-être été appliquée. Lisez
  l'état concerné avant de réessayer; consultez
  [Une écriture interrompue signale que son résultat est inconnu](https://docs.xbox.com/fr-CA/tools/xbox-cli/safety.md#an-interrupted-write-reports-that-its-outcome-is-unknown).
* Ne touchez pas au contexte enregistré, sauf si l'utilisateur vous demande de le modifier. `xbox context set`,
  `xbox context unset` et `xbox context profile delete` modifient les valeurs par défaut de toutes
  les sessions.

## Connexion

```bash theme={null}
xbox auth login                          # once, in the system browser
xbox auth status --output json-compact   # {"signedIn":true,"username":"...",...}
```

`auth status` se termine avec le code 0 et signale `{"signedIn":false}` lorsque personne n'est connecté;
basez donc votre logique sur `signedIn`. Un code de sortie différent de zéro signifie que la vérification n'a pas pu être effectuée, et l'erreur figure sur stderr.
Les appels PlayFab échouent, sauf si l'utilisateur connecté dispose de l'autorisation Admin sur le titre. Consultez
[Authentification](https://docs.xbox.com/fr-CA/tools/xbox-cli/authentication.md).

## Choisir le titre ou le vendeur

Passez le titre ou le vendeur sous forme d'indicateur, comme `--playfab-title-id ABC123`. Sans indicateur, une
commande utilise une variable d'environnement `XBOX_` ou une valeur enregistrée avec `xbox context set`; consultez
[Contexte](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/context.md) pour savoir laquelle l'emporte. Exécutez `xbox context get --output json-compact` pour
voir ce qui est enregistré, et confirmez le titre une fois avec l'utilisateur avant d'appeler quoi que ce soit
d'important.

## Lire la sortie

Combinez `--data-only` et `--output json-compact` pour obtenir uniquement la charge utile, sur une seule ligne :

```bash theme={null}
xbox --playfab-title-id ABC123 --data-only --output json-compact playfab api /Admin/GetTitleData
```

```json theme={null}
{"Data":{"MyKey":"my-value"}}
```

Un appel qui échoue se termine avec un code différent de zéro et écrit son erreur sur stderr. Avec `--data-only`, stdout est
vide en cas d'erreur; vérifiez donc le code de sortie avant d'analyser stdout.

`playfab file upload`, `download` et `delete` n'écrivent rien sur stdout, et leurs messages sur stderr
peuvent changer; vérifiez donc leur code de sortie. Consultez [Fichiers](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/playfab/file.md#output).

L'aide signale les commandes **expérimentales**, dont l'interface peut changer. Consultez
[Commandes expérimentales](https://docs.xbox.com/fr-CA/tools/xbox-cli/cli-command-lifecycle.md).

### Limites de débit

Lorsqu'un service XBOX répond HTTP 429, attendez avant de réessayer; la CLI ne réessaie pas à votre
place. Lorsque le service précise un délai d'attente, l'erreur indique le nombre de secondes, et les erreurs structurées
le contiennent aussi dans `retryAfterSeconds`. Un code 429 avec le code d'erreur `rate_limited` signifie que vous avez envoyé trop
de requêtes en peu de temps; ralentissez donc.

## Trouver la bonne API PlayFab

`xbox playfab api <api-path>` appelle n'importe quelle opération de l'API PlayFab. Le chemin est
`/<Prefix>/<Operation>`, comme `/MultiplayerServer/ListBuildSummariesV2`, et le corps de la
requête est l'objet de requête JSON de l'opération. PlayFab documente les deux :

* Les [spécifications Swagger de PlayFab](https://github.com/PlayFab/API_Specs/tree/master/Swagger/PlayFab)
  sont lisibles par machine. Chaque fichier répertorie ses opérations par chemin, avec leurs schémas de requête et
  de réponse et leurs champs obligatoires. Les fichiers sont nommés d'après les groupes d'API de PlayFab, et non
  d'après le premier segment du chemin; cherchez donc l'opération dans les `paths` des fichiers : `/Catalog`
  et `/Inventory` se trouvent dans `Economy.swagger.json`, et `/Match`, `/Lobby` et
  `/MultiplayerServer` se trouvent dans `Multiplayer.swagger.json`. Le champ `security` de chaque opération
  nomme les informations d'identification qu'elle accepte : `SecretKey`, `EntityToken`, `SessionTicket` ou `None`
  pour les opérations qui n'en nécessitent aucune, comme les appels de connexion des joueurs. Certaines opérations
  indiquent également dans leur description les types de jetons d'entité qu'elles autorisent.
* La [référence de l'API REST PlayFab](https://learn.microsoft.com/rest/api/playfab/) couvre les
  mêmes opérations à l'intention des personnes.

La CLI effectue les appels avec les informations d'identification Microsoft Entra ID de l'utilisateur au lieu d'une clé secrète de titre ou d'un jeton
d'entité de titre; les opérations qui nécessitent un `SessionTicket` de joueur, ou qui acceptent uniquement des jetons d'entité de joueur ou
de serveur de jeu, ne sont donc pas autorisées. Lorsqu'un appel échoue, sa réponse d'erreur indique habituellement le problème, comme
`InvalidParameter` ou `MissingParameter`. Consultez [Intégration de l'API PlayFab](https://docs.xbox.com/fr-CA/tools/xbox-cli/playfab-api.md) pour
en savoir plus.

Dans Git Bash sous Windows, définissez `MSYS_NO_PATHCONV=1` pour la commande, car sinon Git Bash
convertit le chemin de l'API en chemin Windows avant que la CLI le reçoive. Consultez
[Exécution à partir de Git Bash sous Windows](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/playfab/api.md#running-from-git-bash-on-windows).

## Garder les secrets hors des journaux

* Lorsqu'un corps de requête peut contenir des secrets, passez-le avec `--body-file` plutôt qu'avec `--body`, afin
  qu'il reste hors de l'historique du shell et des listes de processus. `playfab mps certificate upload` et
  `playfab mps secret upload` refusent `--body`, car leur corps en contient toujours un.
* Gardez les secrets hors des fichiers de configuration et des variables d'environnement. `ClientId`, `TenantId`
  et les étendues OAuth sont des identificateurs, et non des secrets.
* Les réponses PlayFab peuvent contenir des données de joueur, d'inventaire ou d'économie. Le masquage, la conservation et
  le contrôle de l'accès à tout ce qu'un agent consigne relèvent du propriétaire de l'agent.

## Voir aussi

* [Commandes](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands.md) : la référence complète des commandes
* [Sécurité et opérations destructrices](https://docs.xbox.com/fr-CA/tools/xbox-cli/safety.md) : ce qui demande une confirmation, et ce qui fait plus que ce qu'indique son nom


## Related topics

- [XBOX CLI](https://docs.xbox.com/fr-CA/tools/xbox-cli/index.md)
- [Sécurité et opérations destructrices](https://docs.xbox.com/fr-CA/tools/xbox-cli/safety.md)
- [Utiliser des agents de codage IA avec le GDK](https://docs.xbox.com/fr-CA/build/gdk-and-engines/guides/use-ai-coding-agents-with-the-gdk.md)
- [Installation](https://docs.xbox.com/fr-CA/tools/xbox-cli/installation.md)
- [DevKit Agent pour la gestion des kits de développement XBOX](https://docs.xbox.com/fr-CA/tools/tools-console/devkitagent/devkitagent-overview.md)
