Saltar al contenido principal
La familia de comandos 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 comandos schema 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-id es hexadecimal, tal como lo muestra game get: de 00000001 a 7FFFFFFF, con un prefijo 0x opcional. 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 save y config publish con 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-id en 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-configuration omite la pregunta. Una escritura con --scid no pregunta.
  • config save y config publish escriben en stderr el vendedor y el SCID que usaron. Los comandos de lectura lo hacen con --verbose.
Estos comandos guardan un identificador de título y, después, lo usan para leer, descargar y validar la configuración de ese título en XDKS.1. El último indica el título con --title-id en su lugar:

Salida

Todos los comandos xbl 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 con status, 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, que config 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:
Los documentos que coinciden con los de trabajo más recientes no son un error: no se guarda nada, 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:
Después de editar los documentos, valídalos todos o solo los dos que cambiaste:
Guárdalos con un mensaje:
Descarga un documento tal como estaba en la versión publicada 7:
Descarga los documentos en borrador de la cuenta:

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:
Para promover exactamente lo que está activo en el origen, ejecuta primero con --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ó:
Cuando esa validación produce un error, no publica nada ni pregunta. Por eso, en un terminal, una publicación en RETAIL con --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 en achievementChanges.added.
  • En un terminal sin --validate-only, la lista aparece antes de la pregunta, como se muestra en Confirmación.
Una publicación que no agrega ninguno lo indica. Los demás sandboxes no enumeran logros.

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 en ValidationResult.
Cuando la validación produce un error, 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.
Los archivos globales son los archivos que lee cada jugador del juego, como las fuentes de noticias y los mapas: 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:
Publica la configuración de trabajo más reciente de SANDBOX1 para que esté activa en SANDBOX1:
Publica la versión de trabajo más reciente de SANDBOX1 en SANDBOX2. Esto también reemplaza los archivos globales del almacenamiento de títulos de SANDBOX2 por los de SANDBOX1:
Publica la versión de trabajo 42 de SANDBOX1 en SANDBOX2:
Valida una publicación de CERT a RETAIL, que enumera los logros que agrega:
A continuación, pasa el SourceVersion de la salida como --configset para publicar la versión que validaste, sin una solicitud de confirmación:
Vuelve a publicar SANDBOX1 aunque nada haya cambiado:
Comprueba la publicación en SANDBOX2:

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

  1. Busca los sandboxes a los que puedes acceder:
  2. Comprueba en qué estado están las configuraciones de trabajo y publicada:
  3. Descarga el conjunto de documentos en borrador, lo que también guarda SANDBOX1.etag:
  4. Edita los documentos de xbox-config y, después, valídalos:
  5. Guárdalos:
  6. Publícalos en SANDBOX1:
  7. Comprueba la publicación y repite hasta que su estado sea Success o Failed:
Última modificación el 19 de noviembre de 2026