Passer au contenu principal
La famille de commandes xbl est expérimentale. Son interface CLI pourrait changer ou être retirée en fonction des commentaires. 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 sandbox que ciblent les commandes de configuration, utilisez xbox sandbox list. Ces commandes fonctionnent avec la même configuration que celle que modifie Partner Center. Pour savoir ce que fait chaque fonctionnalité des XBOX services et comment la configurer, consultez Vue d’ensemble de la configuration dans le portail dans la documentation pour les développeurs XBOX.

Comportement commun

Vendeur et sandbox

Toutes les commandes, sauf les 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, transmettez --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 en hexadécimal, comme l’affiche game get : de 00000001 à 7FFFFFFF, avec un préfixe 0x facultatif. Pour les autres ID de titre, transmettez 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 effectués avec l’ID d’un titre lié sont refusés, même avec --validate-only (bound_title_requires_scid). L’erreur nomme le titre principal et le SCID; exécutez de nouveau la commande avec ce --scid.
  • L’enregistrement ou la publication avec --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, la commande échoue. --allow-shared-configuration ignore la question. Une écriture avec --scid ne demande pas de confirmation.
  • config save et config publish écrivent dans stderr le vendeur et le SCID qu’ils 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.

Erreurs

Une requête qui échoue se termine avec le code 1 et écrit dans 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 le libellé 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 qui a échoué a pu être appliquée : Avec le code de sortie 3, ne soumettez pas de nouveau la requête. stderr affiche une commande en lecture seule pour 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

Inspectez, 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 voient les joueurs et les comptes de test une fois que config publish a mis la configuration de travail en ligne.

config list et config status

Les deux commandes indiquent les versions de travail et publiées les plus récentes, l’heure de validation (commit) de chaque version, et si la version de travail comporte des modifications non publiées. L’heure de validation d’une version publiée est l’heure de validation de cette version, et non le moment où la publication s’est terminée. config list retourne un tableau contenant un objet par sandbox. config status retourne un seul objet pour un sandbox, et ajoute sa dernière publication sous lastPublish, ou null lorsqu’il n’y a rien à signaler. Pour --sandbox-id ALL, lastPublish est toujours null, car la configuration à l’échelle du titre dans ALL est mise en ligne au moyen d’une publication dans HIDDEN.

Options de config list

Options de config status

Les tableaux 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 de 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 (la valeur par défaut, qui nécessite un SCID ou un titre ainsi que --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 le nom <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; transmettez --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 est false avec --validate-only, sinon Committed est false), la commande écrit tout de même le résultat dans stdout, écrit chaque message de validation dans stderr, laisse le fichier ETag inchangé et se termine avec le code 1 :
Des documents identiques aux documents de travail les plus récents 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 de config save

Télécharger les documents de sandbox de brouillon les plus récents dans xbox-config :
Après avoir modifié les documents, validez-les tous, ou seulement 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 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 soit 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 version de travail la plus récente n’est pas celle qui est en ligne dans ce sandbox. Une publication entre sandbox sans --configset affiche alors un avertissement et nomme la version qui est 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 qui y est en ligne, lorsqu’elle est trouvée. Une publication à l’échelle du titre, --sandbox-id HIDDEN, publie toujours la configuration de travail la plus récente dans ALL; elle n’accepte donc ni --source-sandbox-id ni --configset. Pour voir 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, la commande 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 destructives. Avant de demander une confirmation pour une publication dans RETAIL, la commande 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, la commande ne publie rien et ne demande pas de confirmation. Ainsi, dans un terminal, une publication dans RETAIL avec --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. Une publication dans RETAIL indique donc les ID des succès qu’elle ajoute et que RETAIL n’a pas encore :
  • Avec --validate-only, la liste est écrite dans stderr, et la sortie JSON la contient dans achievementChanges.added.
  • Dans un terminal sans --validate-only, la liste précède la question, comme le montre la section Confirmation.
Une publication qui n’en ajoute aucun l’indique. Les autres sandbox ne répertorient pas les succès.

Republication

config publish publie seulement 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 config publish de nouveau la relance. Il arrive qu’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 impose la configuration sélectionnée, par défaut la configuration de travail la plus récente de RETAIL, à RETAIL. Une publication dans RETAIL à partir d’un autre sandbox, comme CERT, lève aussi 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 lors d’une première publication dans RETAIL sans embargo, sont écrits dans 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 le montre la section Erreurs.

La publication entre sandbox remplace les fichiers de stockage de titre globaux

La publication d’un sandbox à un autre fait des fichiers de stockage de titre globaux 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 lisent tous les joueurs du jeu, comme les fils d’actualités et les cartes : La copie reprend tout ce que contient 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 dans le 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 sandbox écrit cet avertissement dans 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 configuration de travail la plus récente de SANDBOX1, pour qu’elle soit en ligne dans SANDBOX1 :
Publier la version de travail la plus récente de SANDBOX1 dans SANDBOX2. Cette opération remplace aussi les fichiers de stockage de titre globaux 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 :
Transmettez ensuite le SourceVersion de la sortie comme --configset pour publier la version que vous avez validée, sans invite :
Publier de nouveau SANDBOX1 même si rien n’a 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 le nom <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 dans stdout, et --output ne s’applique pas.

Exemples de schema


Un aller-retour de configuration typique

  1. Trouvez les sandbox auxquels vous avez accès :
  2. Vérifiez l’état de la configuration de travail et de la configuration publiée :
  3. Téléchargez l’ensemble de documents de brouillon, ce qui enregistre aussi 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 répétez l’opération jusqu’à ce que son état soit Success ou Failed :
Dernière modification le 19 novembre 2026