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,ListouSearch. Trate todas as outras operações, e todos os comandosxboxque 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
xboxsem 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 dexbox 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-onlye mostre ao usuário as conquistas listadas. Em seguida, publique com--configsetdefinido como oSourceVersionda 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 unsetexbox context profile deletealteram 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:
--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 comoretryAfterSeconds. 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
pathsdos arquivos:/Cataloge/Inventoryestão emEconomy.swagger.json, e/Match,/Lobbye/MultiplayerServerestão emMultiplayer.swagger.json. O camposecurityde cada operação nomeia a credencial que ela aceita:SecretKey,EntityToken,SessionTicketouNonepara 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.
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-fileem vez de--body, para que ele fique fora do histórico do shell e das listagens de processos.playfab mps certificate uploadeplayfab mps secret uploadrecusam--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,TenantIde 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
- Comandos: a referência completa de comandos
- Segurança e operações destrutivas: o que pergunta primeiro e o que faz mais do que o nome diz
