xbl es experimental. Su interfaz de la CLI puede cambiar
o quitarse en función de los comentarios.
xbox xbl administra la configuración de servicios XBOX (el estado de la configuración de trabajo y
publicada, los documentos de configuración, la publicación y los esquemas de configuración), así como
las imágenes de logros. Para enumerar los sandboxes a los que se dirigen los comandos de configuración,
usa xbox sandbox list.
Estos comandos trabajan con la misma configuración que edita Partner Center. Para saber qué hace cada
característica de los servicios XBOX y cómo configurarla, consulta
Información general sobre la configuración del portal
en la documentación para desarrolladores de XBOX.
Comportamiento compartido
Vendedor y sandbox
Todos los comandos excepto los comandosschema aceptan --seller-id. Sin esta opción, un comando usa
XBOX_SELLER_ID o el vendedor guardado con xbox context set y, después, tu único
vendedor; si tienes varios, pasa --seller-id.
config status y config publish toman --sandbox-id de XBOX_SANDBOX_ID o del valor guardado
sandbox-id cuando lo omites. config download y config save necesitan --sandbox-id en
la línea de comandos para los documentos de sandbox.
Selección del título
config list, config status, config publish, y config download y config save con ámbito de sandbox
aceptan el identificador de configuración de servicio (SCID) del título con --scid, o su
identificador de título de XBOX con --title-id, pero no ambos. Sin ninguno de los dos, usan XBOX_TITLE_ID o el
valor guardado title-id; consulta Contexto. --scid ignora ambos.
--title-ides hexadecimal, tal como lo muestragame get: de00000001a7FFFFFFF, con un prefijo0xopcional. Para otros identificadores de título, pasa el SCID.- Las lecturas de un título vinculado a la configuración de otro título usan el SCID del título principal.
config saveyconfig publishcon el identificador de un título vinculado se rechazan, incluso con--validate-only(bound_title_requires_scid). El error indica el título principal y su SCID; vuelve a ejecutar el comando con ese--scid.- Guardar o publicar con
--title-iden una configuración a la que están vinculados otros títulos la cambia para todos ellos. En un terminal, la CLI enumera los títulos vinculados y pregunta primero; sin un terminal, produce un error.--allow-shared-configurationomite la pregunta. Una escritura con--scidno pregunta. config saveyconfig publishescriben en stderr el vendedor y el SCID que usaron. Los comandos de lectura lo hacen con--verbose.
--title-id en su lugar:
Salida
Todos los comandosxbl aceptan --output table, además de json (el predeterminado) y
json-compact. La tabla de opciones de cada comando enumera las columnas de su tabla.
Errores
Una solicitud con errores sale con 1 y escribe en stderr un error JSON constatus, title, detail
y code cuando el servicio envía uno. Bifurca según status o code, no según el texto de
detail. Un error 429 incluye retryAfterSeconds; consulta
Límites de frecuencia.
Cuando la validación de los servicios XBOX rechaza la configuración, el error enumera cada mensaje en
validation:
config save y config publish sin --validate-only indican si un cambio con errores
podría haberse aplicado:
Con la salida 3, no vuelvas a enviar. stderr imprime un comando de solo lectura con el que comprobarlo: para un guardado,
config download --view draft, para compararlo con los archivos que guardaste; para una publicación,
config status.
config
Inspecciona, descarga, guarda y publica la configuración de servicios XBOX de un SCID. Un sandbox contiene una configuración de trabajo, queconfig save cambia, y una configuración publicada,
que ven los jugadores y las cuentas de prueba una vez que config publish activa la configuración de trabajo.
config list y config status
Ambos comandos informan de las versiones de trabajo y publicadas más recientes, de la hora de confirmación de cada versión
y de si la versión de trabajo tiene cambios sin publicar. Una hora de confirmación publicada es
la hora de confirmación de la versión publicada, no el momento en que terminó la publicación.
config list devuelve una matriz con un objeto por sandbox. config status devuelve un objeto
para un sandbox y agrega su última publicación en lastPublish, o null cuando no hay ninguna de la que
informar. Para --sandbox-id ALL, lastPublish siempre es null, porque la configuración
de todo el título en ALL se activa mediante una publicación en HIDDEN.
Opciones de config list
Opciones de config status
Las tablas de ambos comandos tienen las columnas
SANDBOX, WORKING, WORKING COMMIT,
PUBLISHED, PUBLISHED COMMIT y UNPUBLISHED. config status agrega PUBLISH STATUS,
el status de la última publicación.
Ejemplos de config list y config status
config download y config save
Descarga, valida y guarda conjuntos de documentos de configuración de servicios XBOX. Un conjunto de documentos
pertenece a un sandbox (el valor predeterminado, que necesita un SCID o un título y --sandbox-id) o a la
cuenta (--type account, que no acepta SCID, título ni sandbox).
config download guarda la ETag del conjunto de documentos junto a los documentos, como <sandbox>.etag, o
Account.etag para el ámbito de cuenta; en Windows el archivo está oculto. config save lee el archivo de ETag
que está junto al primer archivo con el que coincide --file, y lo reescribe después de guardar. Si la
configuración cambió desde que la descargaste, el guardado produce un error; pasa --force para guardar sobre
esos cambios, o --etag para proporcionar una ETag tú mismo.
config save no pregunta antes de guardar, y --confirm no se aplica a este comando. Ejecútalo primero con
--validate-only.
Opciones de config download
Opciones de config save
Cuando los servicios XBOX no pueden guardar los documentos (
CanCommit es false con --validate-only;
de lo contrario, Committed es false), el comando sigue escribiendo el resultado en stdout, escribe cada
mensaje de validación en stderr, deja sin cambios el archivo de ETag y sale con 1:
ValidationInfo informa de FilesNotChangedCommit y el comando sale con 0.
Ejemplos de config download y config save
Descarga los documentos de sandbox en borrador más recientes en xbox-config:
config publish
Publica una versión de trabajo de la configuración de servicios XBOX en la configuración publicada de un sandbox.
La publicación es asincrónica: iníciala con config publish y, después, ejecuta
config status para el sandbox de destino hasta que
lastPublish.status sea Success o Failed.
Selección del origen
--sandbox-id es el destino. El origen es una versión de trabajo del sandbox de origen,
que de forma predeterminada es el destino:
Cuando el sandbox de origen tiene cambios sin publicar, su versión de trabajo más reciente no es la que está
activa allí. Una publicación entre sandboxes sin
--configset muestra entonces una advertencia e indica la versión
que está activa:
--validate-only y agrega el
--configset que sugiere. En la salida JSON, SourceVersion es la versión de trabajo usada,
sourceHasUnpublishedChanges indica si difiere de lo que está activo en el origen, y
sourceLiveVersion es la versión que está activa allí, cuando se encuentra una.
Una publicación de todo el título, --sandbox-id HIDDEN, siempre publica la configuración de trabajo más reciente
de ALL, por lo que no acepta --source-sandbox-id ni --configset. Para ver qué versión se
activa, ejecuta primero config status --sandbox-id ALL y lee workingVersion.
Confirmación
config publish pregunta antes de publicar en estos casos:
En un terminal, describe la publicación y pregunta. Sin un terminal, se niega y sale con 1.
--confirm (--yes, -y) omite la pregunta, y --validate-only nunca pregunta. Consulta
Seguridad y operaciones destructivas.
Antes de preguntar sobre una publicación en RETAIL, valida la publicación y enumera los
logros que agrega. Si respondes que sí, publica
la versión de trabajo que validó, de modo que lo que se activa es lo que se enumeró:
--title-id en una configuración a la que están vinculados otros títulos necesita
--allow-shared-configuration. Con --confirm no hay lista, así que ejecuta primero --validate-only
para verla.
Logros que agrega una publicación en RETAIL
Una vez que los logros están activos en RETAIL, no se pueden quitar, y sus reglas de desbloqueo y su gamerscore no pueden cambiar. Por eso, una publicación en RETAIL indica qué identificadores de logro agrega que RETAIL todavía no tiene:- Con
--validate-only, la lista va a stderr, y la salida JSON la incluye enachievementChanges.added. - En un terminal sin
--validate-only, la lista aparece antes de la pregunta, como se muestra en Confirmación.
Republicación
config publish publica solo los cambios. Cuando nada ha cambiado desde la última
publicación correcta del destino, no se inicia ninguna publicación, y el Status del resultado es AlreadyPublished. Después de
que una publicación produzca un error, volver a ejecutar config publish la reintenta.
A veces XBOX bloquea RETAIL para un producto, y una publicación de RETAIL a RETAIL produce entonces un error con
retail_locked. Para publicar de todos modos, agrega --republish: fuerza la
configuración seleccionada, de forma predeterminada la configuración de trabajo más reciente de RETAIL, en RETAIL. Publicar en
RETAIL desde otro sandbox, como CERT, también elimina el bloqueo, pero reemplaza los
documentos de trabajo de RETAIL por los de ese sandbox.
--republish publica de forma completa, incluso cuando nada ha cambiado. No se puede combinar con
--validate-only.
Diagnóstico
Los diagnósticos de validación de los servicios XBOX, como la advertencia de una primera publicación en RETAIL sin un embargo configurado, van a stderr, uno por línea. La salida JSON los conserva enValidationResult.
config publish sale con 1 y enumera cada mensaje en validation, como
se muestra en Errores.
La publicación entre sandboxes reemplaza los archivos globales del almacenamiento de títulos
Publicar de un sandbox a otro convierte los archivos globales del almacenamiento de títulos del destino
en una copia exacta de los del origen. Los archivos que solo tiene el destino se eliminan y no se pueden
recuperar.
La copia toma lo que contenga el origen cuando se ejecuta la publicación. Los datos propios de los jugadores no se
modifican, y una publicación dentro del mismo sandbox no afecta a los archivos globales. Para conservar un archivo del destino,
agrégalo al sandbox de origen antes de publicar.
Cada publicación entre sandboxes escribe esta advertencia en stderr, incluso con
--validate-only,
y la incluye en la pregunta de confirmación:
Opciones de config publish
Ejemplos de config publish
Valida una publicación en SANDBOX1 sin publicar:
SourceVersion de la salida como --configset para publicar la versión que validaste,
sin una solicitud de confirmación:
schema
Descubre y descarga esquemas de documentos de configuración de servicios XBOX.Opciones de schema list
Opciones de schema get
schema get escribe un objeto JSON:
Opciones de schema download
Cada esquema se guarda como
<type>_<version>.xsd, con el tipo en minúsculas, y el comando
imprime las rutas de acceso guardadas. Con --dest -, escribe en su lugar el XSD sin procesar en stdout, y
--output no se aplica.
Ejemplos de schema
Un ciclo completo típico de configuración
-
Busca los sandboxes a los que puedes acceder:
-
Comprueba en qué estado están las configuraciones de trabajo y publicada:
-
Descarga el conjunto de documentos en borrador, lo que también guarda
SANDBOX1.etag: -
Edita los documentos de
xbox-configy, después, valídalos: -
Guárdalos:
-
Publícalos en SANDBOX1:
-
Comprueba la publicación y repite hasta que su estado sea
SuccessoFailed:
