Pular para o conteúdo principal
A família de comandos playfab service-principal é Experimental. Sua interface de CLI pode mudar ou ser removida com base em comentários. Um pipeline de integração contínua (CI) ou outro trabalho autônomo entra como uma entidade de serviço do Microsoft Entra ID; consulte Autenticação de automação (entidade de serviço). O PlayFab aceita a entidade de serviço somente depois que uma pessoa concede acesso a ela em um estúdio do PlayFab. Estes comandos gerenciam essas concessões. Somente uma pessoa conectada com a permissão Admin no estúdio pode executar estes comandos. Eles se recusam a ser executados quando XBOX_AUTHENTICATION__MODE seleciona um modo de entidade de serviço; portanto, entre com xbox auth login. list aceita --output table; os outros comandos não. list retorna uma página: quando houver mais, o ContinuationToken da resposta será definido, e executar list novamente com --continuation-token definido com esse valor obtém a próxima página.

Identificadores

  • --studio-id nomeia o estúdio proprietário das concessões. Estes comandos não aceitam um título do PlayFab; portanto, --playfab-title-id e o contexto salvo não se aplicam.
  • --principal-tenant-id e --principal-object-id identificam a entidade de serviço: o locatário do Entra ID dela e a ID de objeto do aplicativo empresarial dela, e não do registro de aplicativo dela. xbox auth status a informa como objectId quando conectado como a entidade de serviço.
  • Você não passa a ID do aplicativo (cliente). O PlayFab a registra com base no primeiro token da entidade de serviço, e list e get a informam como ClientId.
  • As opções globais --tenant-id e --client-id configuram sua própria entrada, e não a entidade de serviço à qual você está concedendo acesso.

Arquivo de concessões

set substitui todas as concessões da entidade de serviço pelo conteúdo de --grants-file e remove qualquer permissão de estúdio ou título que o arquivo omita.
Comece com base nas concessões atuais, em vez de escrever um arquivo do zero. Salve a saída de get, edite os StudioPermissions e TitleGrants dela e passe-a para set, com a Version dela como --expected-version:
Um arquivo de concessões pode ser a saída inteira de get, o data dela, o objeto ServicePrincipal dentro dele ou somente as concessões:
  • Ambas as propriedades são obrigatórias. Uma lista vazia não concede nada desse tipo.
  • Cada título precisa de pelo menos uma permissão. Para remover a concessão de um título, omita o título.
  • Os nomes das propriedades não diferenciam maiúsculas de minúsculas. Uma propriedade não reconhecida é um erro; assim, um TitleGrants digitado incorretamente não pode remover todas as concessões de título.
  • TenantId, ObjectId e DisplayName do arquivo, quando presentes, devem corresponder a --principal-tenant-id, --principal-object-id e --display-name. Para renomear a entidade de serviço, altere também DisplayName no arquivo ou remova-o.

Versão esperada

Cada alteração nas concessões de uma entidade de serviço atribui a elas uma nova Version, que get e set retornam. Com --expected-version, set não altera nada, a menos que as concessões ainda estejam nessa versão; assim, ele não pode desfazer uma alteração que alguém fez depois que você as leu. --expected-version 0 exige que a entidade de serviço ainda não tenha acesso. Sem --expected-version, set substitui as concessões, quaisquer que sejam elas no momento. Quando o arquivo de concessões tem uma Version, --expected-version é obrigatória e deve ser igual a ela. Se forem diferentes, execute get novamente e refaça suas edições na saída dele. Para substituir as concessões de qualquer forma, remova Version do arquivo e omita --expected-version.

Se set falhar

Se set falhar, a entidade de serviço poderá ficar sem acesso no estúdio até que um set seja bem-sucedido, o que pode interromper um pipeline.
Uma falha não informa se as concessões foram alteradas; portanto, não execute set novamente com a versão antiga. Execute get, verifique as concessões e a Version e, se elas não forem o que você pretendia definir, edite essa saída e passe-a para set com a Version dela como --expected-version.

Exemplos

Listar as entidades de serviço de um estúdio e mostrar as concessões de uma delas:
Substituir as concessões da entidade de serviço pelas que estão em grants.json, que você salvou de get e editou:
Remover a entidade de serviço e as concessões dela do estúdio:
Depois de revoke, a próxima solicitação da entidade de serviço ao PlayFab no estúdio falha. revoke também é bem-sucedido quando a entidade de serviço já não tem acesso. Para restaurar o acesso, execute set com o conjunto completo de concessões.
Última modificação em 19 de novembro de 2026