Pular para o conteúdo principal
A XBOX CLI (xbox) foi criada para ser executada por agentes de IA e scripts, além de por pessoas. Seus comandos recebem argumentos explícitos, seus comandos de dados gravam JSON e seus erros vão para stderr com um código de saída diferente de zero. Esta página é para agentes e para as pessoas que os configuram: como entrar, escolher sobre o que um comando atua, ler a saída e encontrar a API certa, e o que perguntar antes de alterar qualquer coisa.

Antes de alterar qualquer coisa

O usuário conectado geralmente tem direitos de administrador em títulos e vendedores de produção, e nada no lado do servidor impede uma chamada equivocada. Segurança e operações destrutivas lista o que a CLI pergunta e o que ela não pergunta. O restante cabe a você:
  • Trate uma operação do PlayFab como somente leitura apenas se o nome dela começar com Get, List ou Search. Trate todas as outras operações, e todos os comandos xbox que criam, alteram ou excluem algo, como uma alteração de produção.
  • Antes de uma alteração de produção, mostre o comando ao usuário e diga em uma frase o que ele altera e em qual título ou vendedor, incluindo se esse destino vem do contexto salvo. Execute-o somente depois que o usuário disser sim, mesmo que seu runtime execute xbox sem perguntar. Um sim abrange apenas as chamadas que você mostrou.
  • Passe o título ou o vendedor como sinalizador em todas as alterações de produção. O contexto salvo é compartilhado por todas as sessões do usuário do SO; portanto, ele pode mudar entre o sim do usuário e a sua chamada.
  • Pergunte antes de xbox pc sandbox set, que troca a sandbox para todos no PC, e antes de xbox pc sandbox launch-apps, que fecha a Microsoft Store e o aplicativo XBOX.
  • Não adicione --confirm (ou --yes) em vez de perguntar. A CLI não consegue saber quem o adicionou.
  • Antes de pedir para publicar em RETAIL com xbox xbl config publish, execute-o com --validate-only e mostre ao usuário as conquistas listadas. Em seguida, publique com --configset definido como o SourceVersion da saída JSON. As conquistas em RETAIL não podem ser removidas; consulte Conquistas que uma publicação em RETAIL adiciona.
  • Se uma alteração de produção falhar e o resultado dela for desconhecido, ela pode ter sido aplicada. Leia o estado afetado antes de tentar novamente; consulte Uma gravação interrompida informa que seu resultado é desconhecido.
  • Não mexa no contexto salvo, a menos que o usuário peça para alterá-lo. xbox context set, xbox context unset e xbox context profile delete alteram os padrões de todas as sessões.

Entrar

auth status sai com o código 0 e informa {"signedIn":false} quando ninguém está conectado; portanto, tome decisões com base em signedIn. Um código de saída diferente de zero significa que não foi possível verificar, e o erro está em stderr. As chamadas ao PlayFab falham, a menos que o usuário conectado tenha a permissão Admin no título. Consulte Autenticação.

Escolher o título ou o vendedor

Passe o título ou o vendedor como sinalizador, como --playfab-title-id ABC123. Sem ele, um comando usa uma variável de ambiente XBOX_ ou um valor salvo com xbox context set; consulte Contexto para saber qual prevalece. Execute xbox context get --output json-compact para ver o que está salvo e confirme o título com o usuário uma vez antes de chamar qualquer coisa substancial.

Ler a saída

Combine --data-only e --output json-compact para obter somente o conteúdo, em uma única linha:
Uma chamada com falha sai com código diferente de zero e grava o erro em stderr. Com --data-only, stdout fica vazio em caso de erro; portanto, verifique o código de saída antes de analisar stdout. playfab file upload, download e delete não gravam nada em stdout, e as mensagens deles em stderr podem mudar; portanto, verifique o código de saída. Consulte Arquivos. A Ajuda marca os comandos Experimental, cuja interface pode mudar. Consulte Comandos experimentais.

Limites de taxa

Quando um serviço do XBOX responde com HTTP 429, aguarde antes de tentar novamente; a CLI não tenta novamente por você. Quando o serviço especifica uma espera, o erro informa quantos segundos, e os erros estruturados também a incluem como retryAfterSeconds. Um 429 com o código de erro rate_limited significa que você enviou solicitações demais em pouco tempo; portanto, diminua o ritmo.

Encontrar a API do PlayFab certa

xbox playfab api <api-path> chama qualquer operação de API do PlayFab. O caminho é /<Prefix>/<Operation>, como /MultiplayerServer/ListBuildSummariesV2, e o corpo da solicitação é o objeto de solicitação JSON da operação. O PlayFab documenta ambos:
  • As especificações Swagger do PlayFab são legíveis por máquina. Cada arquivo lista suas operações por caminho, com os esquemas de solicitação e de resposta e os campos obrigatórios. Os arquivos têm os nomes dos grupos de API do PlayFab, não do primeiro segmento do caminho; portanto, pesquise a operação nos paths dos arquivos: /Catalog e /Inventory estão em Economy.swagger.json, e /Match, /Lobby e /MultiplayerServer estão em Multiplayer.swagger.json. O campo security de cada operação nomeia a credencial que ela aceita: SecretKey, EntityToken, SessionTicket ou None para operações que não precisam de credencial, como chamadas de login de jogadores. Algumas operações também listam os tipos de token de entidade permitidos na descrição.
  • A referência da API REST do PlayFab abrange as mesmas operações para pessoas.
A CLI faz as chamadas com as credenciais do Microsoft Entra ID do usuário em vez de uma chave secreta de título ou de um token de entidade de título; portanto, as operações que precisam de um SessionTicket de jogador, ou que aceitam somente tokens de entidade de jogador ou de servidor de jogo, não são autorizadas. Quando uma chamada falha, a resposta de erro geralmente nomeia o problema, como InvalidParameter ou MissingParameter. Consulte Integração com a API do PlayFab para saber mais. No Git Bash no Windows, defina MSYS_NO_PATHCONV=1 para o comando, porque, caso contrário, o Git Bash converte o caminho da API em um caminho do Windows antes que a CLI o receba. Consulte Executar a partir do Git Bash no Windows.

Manter segredos fora dos logs

  • Quando o corpo de uma solicitação puder conter segredos, passe-o com --body-file em vez de --body, para que ele fique fora do histórico do shell e das listagens de processos. playfab mps certificate upload e playfab mps secret upload recusam --body, porque o corpo deles sempre contém um segredo.
  • Mantenha segredos fora dos arquivos de configuração e das variáveis de ambiente. ClientId, TenantId e os escopos OAuth são identificadores, não segredos.
  • As respostas do PlayFab podem conter dados de jogadores, de inventário ou de economia. Ocultar, reter e controlar o acesso a tudo o que um agente registra em log é responsabilidade do proprietário do agente.

Confira também

Última modificação em 19 de novembro de 2026