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 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, 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-idest hexadécimal, tel que l’affichegame get: de00000001à7FFFFFFF, avec un préfixe0xfacultatif. 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 saveetconfig 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-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, elle échoue.--allow-shared-configurationignore la question. Une écriture à l’aide de--scidne demande pas de confirmation. config saveetconfig publishécrivent sur stderr le vendeur et le SCID qu’elles 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 de sortie.
Erreurs
Une requête qui échoue se termine avec le code 1 et écrit sur 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 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, queconfig 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 :
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 :
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 :
--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é :
--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 dansachievementChanges.added. - Dans un terminal sans
--validate-only, la liste précède la question, comme indiqué dans Confirmation.
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 dansValidationResult.
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.
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 :
SourceVersion de la sortie en tant que --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 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
-
Trouvez les sandboxes auxquels vous pouvez accéder :
-
Consultez l’état de la configuration de travail et de la configuration publiée :
-
Téléchargez l’ensemble de documents à l’état de brouillon, ce qui enregistre également
SANDBOX1.etag: -
Modifiez les documents dans
xbox-config, puis validez-les : -
Enregistrez-les :
-
Publiez-les dans SANDBOX1 :
-
Vérifiez la publication, et recommencez jusqu’à ce que son état soit
SuccessouFailed:
