Passer au contenu principal
La 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 prennent des arguments explicites, ses commandes de données écrivent du JSON et ses erreurs sont envoyées sur 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 agit une commande, lire sa sortie et trouver la bonne API, et ce qu’il faut demander avant de modifier quoi que ce soit.

Avant toute modification

L’utilisateur connecté dispose généralement de droits d’administrateur sur les titres et vendeurs de production, et rien côté serveur n’empêche un appel erroné. Sécurité et opérations destructives répertorie ce pour quoi la CLI demande confirmation et ce pour quoi elle ne le fait pas. Le reste relève de votre responsabilité :
  • Considérez une opération PlayFab comme en lecture seule uniquement si son nom commence par Get, List ou Search. Considérez toute autre opération, ainsi que 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, y compris si cette cible provient du contexte enregistré. Exécutez-la uniquement après son accord, même si votre environnement d’exécution exécuterait xbox sans demander. Un accord ne couvre que 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 l’accord 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 (ou --yes) au lieu de demander. La CLI ne peut pas savoir qui l’a ajouté.
  • Avant de demander à publier vers 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 supprimés ; consultez Succès ajoutés par une publication RETAIL.
  • 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.
  • Ne modifiez pas le contexte enregistré, sauf si l’utilisateur vous le demande. xbox context set, xbox context unset et xbox context profile delete modifient les valeurs par défaut de toutes les sessions.

Connexion

auth status se termine avec le code 0 et indique {"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 a été impossible, 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.

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 pour savoir laquelle l’emporte. Exécutez xbox context get --output json-compact pour voir ce qui est enregistré, et confirmez une fois le titre avec l’utilisateur avant tout appel substantiel.

Lire la sortie

Combinez --data-only et --output json-compact pour obtenir uniquement la charge utile, sur une seule ligne :
Un appel en échec 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. L’aide signale les commandes Experimental, dont l’interface peut changer. Consultez Commandes expérimentales.

Limites de débit

Lorsqu’un service XBOX répond HTTP 429, attendez avant de réessayer ; la CLI ne réessaie pas pour vous. Lorsque le service précise un délai d’attente, l’erreur indique le nombre de secondes, et les erreurs structurées le transmettent 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.

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 sont lisibles par une 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 : recherchez donc l’opération dans les paths des fichiers. /Catalog et /Inventory se trouvent dans Economy.swagger.json, et /Match, /Lobby et /MultiplayerServer 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é autorisés.
  • La référence de l’API REST PlayFab couvre les mêmes opérations pour les 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 n’acceptent que 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 généralement le problème, comme InvalidParameter ou MissingParameter. Consultez Intégration de l’API PlayFab 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 ne le reçoive. Consultez Exécution depuis Git Bash sous 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 n’apparaisse ni dans l’historique du shell ni dans les listes de processus. playfab mps certificate upload et playfab mps secret upload refusent --body, car leur corps en contient toujours un.
  • Ne placez pas de secrets dans les fichiers de configuration ni dans les variables d’environnement. ClientId, TenantId et les étendues OAuth sont des identificateurs, pas 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 d’accès de tout ce qu’un agent journalise relèvent de la responsabilité du propriétaire de l’agent.

Voir aussi

Dernière modification le 19 novembre 2026