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 comandosschema, 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, comogame geta mostra: de00000001a7FFFFFFF, com um prefixo0xopcional. 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 saveeconfig publishpela 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-idem 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-configurationignora a pergunta. Uma gravação por--scidnão pede confirmação. config saveeconfig publishgravam em stderr o vendedor e o SCID que usaram. Os comandos de leitura fazem isso com--verbose.
--title-id:
Saída
Todos os comandosxbl 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 comstatus, 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, queconfig 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:
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:
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:
--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:
--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 emachievementChanges.added. - Em um terminal sem
--validate-only, a lista aparece antes da pergunta, conforme mostrado em Confirmação.
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 emValidationResult.
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.
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:
SourceVersion da saída como --configset para publicar a versão que você validou,
sem prompt:
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
-
Encontre as sandboxes que você pode acessar:
-
Veja a situação da configuração de trabalho e da publicada:
-
Baixe o conjunto de documentos de rascunho, o que também salva
SANDBOX1.etag: -
Edite os documentos em
xbox-confige, em seguida, valide-os: -
Salve-os:
-
Publique-os em SANDBOX1:
-
Verifique a publicação e repita até que o status seja
SuccessouFailed:
