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 commandesschema, 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-idest en hexadécimal, comme l’affichegame get: de00000001à7FFFFFFF, avec un préfixe0xfacultatif. 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 saveetconfig publisheffectué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-iddans 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-configurationignore la question. Une écriture avec--scidne demande pas de confirmation. config saveetconfig publishécrivent dans stderr le vendeur et le SCID qu’ils ont utilisés. Les commandes de lecture le font avec--verbose.
--title-id :
Sortie
Toutes les commandesxbl 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 avecstatus, 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, queconfig 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 :
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 :
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 :
--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é :
--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 dansachievementChanges.added. - Dans un terminal sans
--validate-only, la liste précède la question, comme le montre la section Confirmation.
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 dansValidationResult.
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.
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 :
SourceVersion de la sortie comme --configset pour publier la version que vous avez validée,
sans invite :
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
-
Trouvez les sandbox auxquels vous avez accès :
-
Vérifiez l’état de la configuration de travail et de la configuration publiée :
-
Téléchargez l’ensemble de documents de brouillon, ce qui enregistre aussi
SANDBOX1.etag: -
Modifiez les documents dans
xbox-config, puis validez-les : -
Enregistrez-les :
-
Publiez-les dans SANDBOX1 :
-
Vérifiez la publication, et répétez l’opération jusqu’à ce que son état soit
SuccessouFailed:
