Passer au contenu principal
La famille de commandes xbl est expérimentale. Son interface CLI peut changer ou être supprimée en fonction des retours. xbox xbl gère la configuration des XBOX services (l’état de la configuration de travail et de la configuration publiée, les documents de configuration, la publication et les schémas de configuration) ainsi que les images de succès. Pour répertorier les sandboxes que ciblent les commandes de configuration, utilisez xbox sandbox list. Ces commandes fonctionnent avec la même configuration que celle modifiée par Partner Center. Pour savoir ce que fait chaque fonctionnalité des XBOX services et comment la configurer, consultez Vue d’ensemble de la configuration du portail dans la documentation pour les développeurs XBOX.

Comportement commun

Vendeur et sandbox

Toutes les commandes, à l’exception des commandes schema, acceptent --seller-id. Sans cette option, une commande utilise XBOX_SELLER_ID ou le vendeur enregistré avec xbox context set, puis votre seul vendeur ; si vous en avez plusieurs, passez --seller-id. config status et config publish prennent --sandbox-id dans XBOX_SANDBOX_ID ou dans le sandbox-id enregistré lorsque vous l’omettez. config download et config save nécessitent --sandbox-id sur la ligne de commande pour les documents de sandbox.

Ciblage du titre

config list, config status, config publish, ainsi que config download et config save limités à un sandbox, acceptent l’identificateur de configuration de service (SCID) du titre avec --scid, ou son ID de titre XBOX avec --title-id, mais pas les deux. Sans l’un ni l’autre, ils utilisent XBOX_TITLE_ID ou le title-id enregistré ; consultez Contexte. --scid ignore les deux.
  • --title-id est hexadécimal, tel que l’affiche game get : de 00000001 à 7FFFFFFF, avec un préfixe 0x facultatif. Pour les autres ID de titre, passez le SCID.
  • Les lectures d’un titre lié à la configuration d’un autre titre utilisent le SCID du titre principal.
  • config save et config publish à l’aide de l’ID d’un titre lié sont refusées, même avec --validate-only (bound_title_requires_scid). L’erreur nomme le titre principal et le SCID ; relancez la commande avec ce --scid.
  • L’enregistrement ou la publication à l’aide de --title-id dans une configuration à laquelle d’autres titres sont liés la modifie pour tous ces titres. Dans un terminal, la CLI répertorie les titres liés et demande d’abord une confirmation ; sans terminal, elle échoue. --allow-shared-configuration ignore la question. Une écriture à l’aide de --scid ne demande pas de confirmation.
  • config save et config publish écrivent sur stderr le vendeur et le SCID qu’elles ont utilisés. Les commandes de lecture le font avec --verbose.
Ces commandes enregistrent un ID de titre, puis l’utilisent pour lire, télécharger et valider la configuration de ce titre dans XDKS.1. La dernière nomme plutôt le titre avec --title-id :

Sortie

Toutes les commandes xbl acceptent --output table ainsi que json (par défaut) et json-compact. Le tableau des options de chaque commande répertorie les colonnes de son tableau de sortie.

Erreurs

Une requête qui échoue se termine avec le code 1 et écrit sur stderr une erreur JSON avec status, title, detail et code lorsque le service en envoie un. Basez votre logique sur status ou code, et non sur la formulation de detail. Une erreur 429 inclut retryAfterSeconds ; consultez Limites de débit. Lorsque la validation des XBOX services rejette la configuration, l’erreur répertorie chaque message sous validation :
config save et config publish sans --validate-only indiquent si une modification ayant échoué a pu être appliquée : En cas de code de sortie 3, ne renvoyez pas la requête. stderr affiche une commande en lecture seule permettant de vérifier : pour un enregistrement, config download --view draft, afin de comparer avec les fichiers que vous avez enregistrés ; pour une publication, config status.

config

Examinez, téléchargez, enregistrez et publiez la configuration des XBOX services pour un SCID. Un sandbox contient une configuration de travail, que config save modifie, et une configuration publiée, que les joueurs et les comptes de test voient une fois que config publish a mis la configuration de travail en ligne.

config list et config status

Les deux commandes indiquent les dernières versions de travail et publiées, l’heure de validation de chaque version, et si la version de travail comporte des modifications non publiées. L’heure de validation publiée est l’heure de validation de la version publiée, et non l’heure de fin de la publication. config list renvoie un tableau contenant un objet par sandbox. config status renvoie un objet pour un sandbox et ajoute sa dernière publication sous lastPublish, ou null lorsqu’il n’y en a aucune à signaler. Pour --sandbox-id ALL, lastPublish vaut toujours null, car la configuration à l’échelle du titre dans ALL est mise en ligne par une publication dans HIDDEN.

Options de config list

Options de config status

Les tableaux de sortie des deux commandes comportent les colonnes SANDBOX, WORKING, WORKING COMMIT, PUBLISHED, PUBLISHED COMMIT et UNPUBLISHED. config status ajoute PUBLISH STATUS, le status de la dernière publication.

Exemples de config list et config status

config download et config save

Téléchargez, validez et enregistrez des ensembles de documents de configuration des XBOX services. Un ensemble de documents appartient à un sandbox (par défaut, ce qui nécessite un SCID ou un titre et --sandbox-id) ou au compte (--type account, qui n’accepte ni SCID, ni titre, ni sandbox). config download enregistre l’ETag de l’ensemble de documents à côté des documents, sous la forme <sandbox>.etag, ou Account.etag pour l’étendue du compte ; sous Windows, le fichier est masqué. config save lit le fichier ETag situé à côté du premier fichier auquel correspond --file, et le réécrit après un enregistrement. Si la configuration a changé depuis que vous l’avez téléchargée, l’enregistrement échoue ; passez --force pour enregistrer par-dessus ces modifications, ou --etag pour fournir vous-même un ETag. config save ne demande pas de confirmation avant d’enregistrer, et --confirm ne s’y applique pas. Exécutez-la d’abord avec --validate-only.

Options de config download

Options de config save

Lorsque les XBOX services ne peuvent pas enregistrer les documents (CanCommit à false avec --validate-only, sinon Committed à false), la commande écrit tout de même le résultat sur stdout, écrit chaque message de validation sur stderr, laisse le fichier ETag inchangé et se termine avec le code 1 :
Des documents identiques aux derniers documents de travail ne constituent pas un échec : rien n’est enregistré, ValidationInfo signale FilesNotChangedCommit, et la commande se termine avec le code 0.

Exemples de config download et config save

Télécharger les derniers documents de sandbox à l’état de brouillon dans xbox-config :
Après avoir modifié les documents, validez-les tous, ou uniquement les deux que vous avez modifiés :
Les enregistrer avec un message :
Télécharger un document tel qu’il était dans la version publiée 7 :
Télécharger les documents à l’état de brouillon du compte :

config publish

Publiez une version de travail de la configuration des XBOX services dans la configuration publiée d’un sandbox. La publication est asynchrone : démarrez-la avec config publish, puis exécutez config status pour le sandbox de destination jusqu’à ce que lastPublish.status vaille Success ou Failed.

Sélection de la source

--sandbox-id est la destination. La source est une version de travail du sandbox source, qui est par défaut la destination : Lorsque le sandbox source comporte des modifications non publiées, sa dernière version de travail n’est pas celle qui est en ligne dans ce sandbox. Une publication entre sandboxes sans --configset émet alors un avertissement et nomme la version en ligne :
Pour promouvoir exactement ce qui est en ligne dans la source, exécutez d’abord la commande avec --validate-only et ajoutez le --configset qu’elle suggère. Dans la sortie JSON, SourceVersion est la version de travail utilisée, sourceHasUnpublishedChanges indique si elle diffère de ce qui est en ligne dans la source, et sourceLiveVersion est la version en ligne dans celle-ci, lorsqu’elle est trouvée. Une publication à l’échelle du titre, --sandbox-id HIDDEN, publie toujours la dernière configuration de travail de ALL ; elle n’accepte donc ni --source-sandbox-id ni --configset. Pour savoir quelle version sera mise en ligne, exécutez d’abord config status --sandbox-id ALL et lisez workingVersion.

Confirmation

config publish demande une confirmation avant de publier dans les cas suivants : Dans un terminal, elle décrit la publication et demande une confirmation. Sans terminal, elle refuse et se termine avec le code 1. --confirm (--yes, -y) ignore la question, et --validate-only ne demande jamais de confirmation. Consultez Sécurité et opérations destructrices. Avant de demander une confirmation pour une publication dans RETAIL, elle valide la publication et répertorie les succès qu’elle ajoute. Si vous répondez oui, elle publie la version de travail qu’elle a validée ; ce qui est mis en ligne correspond donc à ce qui a été répertorié :
Lorsque cette validation échoue, elle ne publie rien et ne demande pas de confirmation. Ainsi, dans un terminal, une publication dans RETAIL à l’aide de --title-id dans une configuration à laquelle d’autres titres sont liés nécessite --allow-shared-configuration. Avec --confirm, aucune liste n’est affichée ; exécutez donc d’abord --validate-only pour la voir.

Succès ajoutés par une publication dans RETAIL

Une fois que des succès sont en ligne dans RETAIL, ils ne peuvent plus être supprimés, et leurs règles de déverrouillage et leur gamerscore ne peuvent plus changer. C’est pourquoi une publication dans RETAIL indique quels ID de succès elle ajoute alors que RETAIL ne les possède pas encore :
  • Avec --validate-only, la liste est écrite sur stderr, et la sortie JSON la contient dans achievementChanges.added.
  • Dans un terminal sans --validate-only, la liste précède la question, comme indiqué dans Confirmation.
Une publication qui n’en ajoute aucun l’indique. Les autres sandboxes ne répertorient pas les succès.

Republication

config publish ne publie que les modifications. Lorsque rien n’a changé depuis la dernière publication réussie de la destination, aucune publication ne démarre, et le Status du résultat est AlreadyPublished. Après l’échec d’une publication, exécuter de nouveau config publish la relance. Il arrive que XBOX verrouille RETAIL pour un produit ; une publication de RETAIL vers RETAIL échoue alors avec retail_locked. Pour publier malgré tout, ajoutez --republish : cette option force la configuration sélectionnée, par défaut la dernière configuration de travail de RETAIL, dans RETAIL. Une publication dans RETAIL depuis un autre sandbox, comme CERT, lève également le verrou, mais elle remplace les documents de travail de RETAIL par ceux de ce sandbox. --republish effectue une publication complète, même lorsque rien n’a changé. Elle ne peut pas être combinée avec --validate-only.

Diagnostics

Les diagnostics de validation des XBOX services, comme l’avertissement émis pour une première publication dans RETAIL sans embargo, sont écrits sur stderr, un par ligne. La sortie JSON les conserve dans ValidationResult.
Lorsque la validation échoue, config publish se termine avec le code 1 et répertorie chaque message sous validation, comme indiqué dans Erreurs.

La publication entre sandboxes remplace les fichiers de stockage de titre global

Une publication d’un sandbox vers un autre fait des fichiers de stockage de titre global de la destination une copie exacte de ceux de la source. Les fichiers que seule la destination possède sont supprimés et ne peuvent pas être récupérés.
Les fichiers globaux sont les fichiers que lit chaque joueur du jeu, comme les flux d’actualités et les cartes : La copie reprend le contenu de la source au moment de l’exécution de la publication. Les données propres aux joueurs ne sont pas touchées, et une publication au sein d’un même sandbox laisse les fichiers globaux intacts. Pour conserver un fichier de la destination, ajoutez-le au sandbox source avant de publier. Chaque publication entre sandboxes écrit cet avertissement sur stderr, y compris avec --validate-only, et l’inclut dans la question de confirmation :

Options de config publish

Exemples de config publish

Valider une publication dans SANDBOX1 sans publier :
Publier la dernière configuration de travail de SANDBOX1, afin qu’elle soit en ligne dans SANDBOX1 :
Publier la dernière version de travail de SANDBOX1 dans SANDBOX2. Cette opération remplace également les fichiers de stockage de titre global de SANDBOX2 par ceux de SANDBOX1 :
Publier la version de travail 42 de SANDBOX1 dans SANDBOX2 :
Valider une publication de CERT vers RETAIL, ce qui répertorie les succès qu’elle ajoute :
Passez ensuite le SourceVersion de la sortie en tant que --configset pour publier la version que vous avez validée, sans invite :
Publier de nouveau SANDBOX1 bien que rien n’ait changé :
Vérifier la publication dans SANDBOX2 :

schema

Découvrez et téléchargez les schémas des documents de configuration des XBOX services.

Options de schema list

Options de schema get

schema get écrit un objet JSON :

Options de schema download

Chaque schéma est enregistré sous la forme <type>_<version>.xsd, avec le type en minuscules, et la commande affiche les chemins enregistrés. Avec --dest -, elle écrit plutôt le XSD brut sur stdout, et --output ne s’applique pas.

Exemples de schema


Un aller-retour de configuration type

  1. Trouvez les sandboxes auxquels vous pouvez accéder :
  2. Consultez l’état de la configuration de travail et de la configuration publiée :
  3. Téléchargez l’ensemble de documents à l’état de brouillon, ce qui enregistre également SANDBOX1.etag :
  4. Modifiez les documents dans xbox-config, puis validez-les :
  5. Enregistrez-les :
  6. Publiez-les dans SANDBOX1 :
  7. Vérifiez la publication, et recommencez jusqu’à ce que son état soit Success ou Failed :
Dernière modification le 19 novembre 2026