Pular para o conteúdo principal
A família de comandos xbl é Experimental. Sua interface de CLI pode mudar ou ser removida com base em comentários. xbox xbl gerencia a configuração dos serviços do XBOX — o estado da configuração de trabalho e da configuração publicada, os documentos de configuração, a publicação e os esquemas de configuração —, bem como as imagens de conquistas. Para listar as sandboxes às quais os comandos de configuração se destinam, use xbox sandbox list. Estes comandos trabalham com a mesma configuração que o Partner Center edita. Para saber o que cada recurso dos serviços do XBOX faz e como configurá-lo, consulte Visão geral da configuração do portal na documentação para desenvolvedores do XBOX.

Comportamento compartilhado

Vendedor e sandbox

Todos os comandos, exceto os comandos schema, aceitam --seller-id. Sem essa opção, o comando usa XBOX_SELLER_ID ou o vendedor salvo com xbox context set e, em seguida, seu único vendedor; se você tiver vários, passe --seller-id. config status e config publish obtêm --sandbox-id de XBOX_SANDBOX_ID ou da sandbox-id salva quando você a omite. config download e config save precisam de --sandbox-id na linha de comando para documentos de sandbox.

Direcionamento de título

config list, config status, config publish e config download e config save com escopo de sandbox aceitam o identificador de configuração de serviço (SCID) do título com --scid, ou sua ID de título do XBOX com --title-id, mas não ambos. Sem nenhum dos dois, eles usam XBOX_TITLE_ID ou a title-id salva; consulte Contexto. --scid ignora ambos.
  • --title-id é hexadecimal, como game get a mostra: de 00000001 a 7FFFFFFF, com um prefixo 0x opcional. Para outras IDs de título, passe o SCID.
  • As leituras de um título vinculado à configuração de outro título usam o SCID do título principal.
  • config save e config publish pela ID de um título vinculado são recusados, mesmo com --validate-only (bound_title_requires_scid). O erro indica o título principal e o SCID; execute novamente com esse --scid.
  • Salvar ou publicar por --title-id em uma configuração à qual outros títulos estão vinculados a altera para todos eles. Em um terminal, a CLI lista os títulos vinculados e pede confirmação primeiro; sem um terminal, ela falha. --allow-shared-configuration ignora a pergunta. Uma gravação por --scid não pede confirmação.
  • config save e config publish gravam em stderr o vendedor e o SCID que usaram. Os comandos de leitura fazem isso com --verbose.
Estes comandos salvam uma ID de título e, em seguida, a usam para ler, baixar e validar a configuração desse título em XDKS.1. O último indica o título com --title-id:

Saída

Todos os comandos xbl aceitam --output table, além de json (o padrão) e json-compact. A tabela de opções de cada comando lista as colunas da tabela dele.

Erros

Uma solicitação com falha sai com o código 1 e grava em stderr um erro JSON com status, title, detail e code quando o serviço envia um. Ramifique com base em status ou code, e não no texto de detail. Um erro 429 inclui retryAfterSeconds; consulte Limites de taxa. Quando a validação dos serviços do XBOX rejeita a configuração, o erro lista cada mensagem em validation:
config save e config publish sem --validate-only informam se uma alteração com falha pode ter sido aplicada: Na saída 3, não envie novamente. stderr imprime um comando somente leitura para verificar: para um salvamento, config download --view draft, para comparar com os arquivos que você salvou; para uma publicação, config status.

config

Inspecione, baixe, salve e publique a configuração dos serviços do XBOX para um SCID. Uma sandbox contém uma configuração de trabalho, que config save altera, e uma configuração publicada, que os jogadores e as contas de teste veem depois que config publish torna a configuração de trabalho ativa.

config list e config status

Ambos os comandos relatam as versões de trabalho e publicada mais recentes, a hora de confirmação de cada versão e se a versão de trabalho tem alterações não publicadas. A hora de confirmação publicada é a hora de confirmação da versão publicada, e não o momento em que a publicação terminou. config list retorna uma matriz com um objeto por sandbox. config status retorna um objeto para uma sandbox e adiciona sua última publicação em lastPublish, ou null quando não há nenhuma a relatar. Para --sandbox-id ALL, lastPublish é sempre null, porque a configuração de todo o título em ALL se torna ativa por meio de uma publicação em HIDDEN.

Opções de config list

Opções de config status

As tabelas de ambos os comandos têm as colunas SANDBOX, WORKING, WORKING COMMIT, PUBLISHED, PUBLISHED COMMIT e UNPUBLISHED. config status adiciona PUBLISH STATUS, o status da última publicação.

Exemplos de config list e config status

config download e config save

Baixe, valide e salve conjuntos de documentos de configuração dos serviços do XBOX. Um conjunto de documentos pertence a uma sandbox (o padrão, que exige um SCID ou título e --sandbox-id) ou à conta (--type account, que não aceita SCID, título nem sandbox). config download salva a ETag do conjunto de documentos ao lado dos documentos, como <sandbox>.etag, ou Account.etag para o escopo de conta; no Windows, o arquivo fica oculto. config save lê o arquivo de ETag ao lado do primeiro arquivo correspondente a --file e o regrava após um salvamento. Se a configuração tiver mudado desde que você a baixou, o salvamento falhará; passe --force para salvar por cima dessas alterações ou --etag para fornecer uma ETag você mesmo. config save não pede confirmação antes de salvar, e --confirm não se aplica a ele. Execute-o primeiro com --validate-only.

Opções de config download

Opções de config save

Quando os serviços do XBOX não conseguem salvar os documentos (CanCommit falso com --validate-only; caso contrário, Committed falso), o comando ainda grava o resultado em stdout, grava cada mensagem de validação em stderr, mantém o arquivo de ETag inalterado e sai com o código 1:
Documentos iguais aos de trabalho mais recentes não são uma falha: nada é salvo, ValidationInfo relata FilesNotChangedCommit e o comando sai com 0.

Exemplos de config download e config save

Baixe os documentos de rascunho mais recentes da sandbox em xbox-config:
Depois de editar os documentos, valide todos eles ou somente os dois que você alterou:
Salve-os com uma mensagem:
Baixe um documento como ele estava na versão publicada 7:
Baixe os documentos de rascunho da conta:

config publish

Publique uma versão de trabalho da configuração dos serviços do XBOX na configuração publicada de uma sandbox. A publicação é assíncrona: inicie-a com config publish e, em seguida, execute config status para a sandbox de destino até que lastPublish.status seja Success ou Failed.

Seleção da origem

--sandbox-id é o destino. A origem é uma versão de trabalho da sandbox de origem, que, por padrão, é o destino: Quando a sandbox de origem tem alterações não publicadas, sua versão de trabalho mais recente não é o que está ativo nela. Uma publicação entre sandboxes sem --configset então emite um aviso e indica a versão que está ativa:
Para promover exatamente o que está ativo na origem, execute primeiro com --validate-only e adicione o --configset sugerido. Na saída JSON, SourceVersion é a versão de trabalho usada, sourceHasUnpublishedChanges informa se ela difere do que está ativo na origem, e sourceLiveVersion é a versão que está ativa lá, quando uma é encontrada. Uma publicação de todo o título, --sandbox-id HIDDEN, sempre publica a configuração de trabalho mais recente em ALL; por isso, ela não aceita --source-sandbox-id nem --configset. Para ver qual versão se torna ativa, execute primeiro config status --sandbox-id ALL e leia workingVersion.

Confirmação

config publish pede confirmação antes de publicar nestes casos: Em um terminal, ele descreve a publicação e pede confirmação. Sem um terminal, ele se recusa e sai com o código 1. --confirm (--yes, -y) ignora a pergunta, e --validate-only nunca pede confirmação. Consulte Segurança e operações destrutivas. Antes de pedir confirmação para uma publicação em RETAIL, ele valida a publicação e lista as conquistas que ela adiciona. Se você responder sim, ele publicará a versão de trabalho que validou; portanto, o que se torna ativo é o que foi listado:
Quando essa validação falha, ele não publica nada e não pede confirmação. Portanto, em um terminal, uma publicação em RETAIL por --title-id em uma configuração à qual outros títulos estão vinculados exige --allow-shared-configuration. Com --confirm, não há lista; por isso, execute --validate-only primeiro para vê-la.

Conquistas que uma publicação em RETAIL adiciona

Depois que as conquistas estão ativas em RETAIL, elas não podem ser removidas, e suas regras de desbloqueio e gamerscore não podem mudar. Por isso, uma publicação em RETAIL informa quais IDs de conquista ela adiciona que RETAIL ainda não tem:
  • Com --validate-only, a lista vai para stderr, e a saída JSON a inclui em achievementChanges.added.
  • Em um terminal sem --validate-only, a lista aparece antes da pergunta, conforme mostrado em Confirmação.
Uma publicação que não adiciona nenhuma conquista informa isso. As outras sandboxes não listam conquistas.

Republicação

config publish publica somente alterações. Quando nada mudou desde a última publicação bem-sucedida do destino, nenhuma publicação é iniciada, e o Status do resultado é AlreadyPublished. Depois que uma publicação falha, executar config publish novamente faz uma nova tentativa. Às vezes, o XBOX bloqueia RETAIL para um produto, e uma publicação de RETAIL para RETAIL falha com retail_locked. Para publicar mesmo assim, adicione --republish: essa opção força a configuração selecionada, por padrão a configuração de trabalho mais recente de RETAIL, em RETAIL. Publicar em RETAIL a partir de outra sandbox, como CERT, também remove o bloqueio, mas substitui os documentos de trabalho de RETAIL pelos dessa sandbox. --republish publica tudo, mesmo quando nada mudou. Não pode ser combinada com --validate-only.

Diagnóstico

Os diagnósticos de validação dos serviços do XBOX, como o aviso para uma primeira publicação em RETAIL sem embargo, vão para stderr, um por linha. A saída JSON os mantém em ValidationResult.
Quando a validação falha, config publish sai com o código 1 e lista cada mensagem em validation, conforme mostrado em Erros.

A publicação entre sandboxes substitui os arquivos globais do Title Storage

Publicar de uma sandbox para outra torna os arquivos globais do Title Storage do destino uma cópia exata dos da origem. Os arquivos que existem somente no destino são excluídos e não podem ser recuperados.
Os arquivos globais são os arquivos que todos os jogadores do jogo leem, como feeds de notícias e mapas: A cópia usa o que a origem contém no momento em que a publicação é executada. Os dados dos próprios jogadores não são afetados, e uma publicação na mesma sandbox não altera os arquivos globais. Para manter um arquivo do destino, adicione-o à sandbox de origem antes de publicar. Toda publicação entre sandboxes grava este aviso em stderr, inclusive com --validate-only, e o inclui na pergunta de confirmação:

Opções de config publish

Exemplos de config publish

Valide uma publicação em SANDBOX1 sem publicar:
Publique a configuração de trabalho mais recente de SANDBOX1 para que ela fique ativa em SANDBOX1:
Publique a versão de trabalho mais recente de SANDBOX1 em SANDBOX2. Isso também substitui os arquivos globais do Title Storage de SANDBOX2 pelos de SANDBOX1:
Publique a versão de trabalho 42 de SANDBOX1 em SANDBOX2:
Valide uma publicação de CERT para RETAIL, o que lista as conquistas que ela adiciona:
Em seguida, passe o SourceVersion da saída como --configset para publicar a versão que você validou, sem prompt:
Publique SANDBOX1 novamente, embora nada tenha mudado:
Verifique a publicação em SANDBOX2:

schema

Descubra e baixe os esquemas de documentos de configuração dos serviços do XBOX.

Opções de schema list

Opções de schema get

schema get grava um objeto JSON:

Opções de schema download

Cada esquema é salvo como <type>_<version>.xsd, com o tipo em minúsculas, e o comando imprime os caminhos salvos. Com --dest -, ele grava o XSD bruto em stdout, e --output não se aplica.

Exemplos de schema


Um ciclo típico de configuração

  1. Encontre as sandboxes que você pode acessar:
  2. Veja a situação da configuração de trabalho e da publicada:
  3. Baixe o conjunto de documentos de rascunho, o que também salva SANDBOX1.etag:
  4. Edite os documentos em xbox-config e, em seguida, valide-os:
  5. Salve-os:
  6. Publique-os em SANDBOX1:
  7. Verifique a publicação e repita até que o status seja Success ou Failed:
Última modificação em 19 de novembro de 2026