Partilhar via

Gerar um token de incorporação

  • Artigo

APLICA-SE A: App possui dados O usuário possui dados

Gerar token é uma API REST que permite gerar um token para incorporar um relatório ou modelo semântico do Power BI em um aplicativo Web ou portal. Ele pode gerar um token para um único item ou para vários relatórios ou modelos semânticos. O token é usado para autorizar sua solicitação no serviço do Power BI.

A API Gerar token utiliza uma única identidade (um utilizador mestre ou principal de serviço) para gerar um token para um utilizador individual, dependendo das credenciais desse utilizador na aplicação (identidade efetiva).

Após a autenticação bem-sucedida, o acesso aos dados relevantes é concedido.

Nota

Gerar token é a API mais recente, versão 2, que funciona para relatórios e modelos semânticos e itens únicos ou múltiplos. Para painéis e blocos, use o V1 Dashboards GenerateTokenInGroup e o TilesGenerateTokenInGroup.

Proteger os seus dados

Se você estiver lidando com dados de vários clientes, há duas abordagens principais para proteger seus dados: isolamento baseado em espaço de trabalho e isolamento baseado em segurança em nível de linha. Você pode encontrar uma comparação detalhada entre eles em perfis de entidade de serviço e segurança em nível de linha.

Recomendamos o uso do isolamento baseado em espaço de trabalho com perfis, mas se você quiser usar a abordagem RLS, revise a seção RLS no final deste artigo.

Permissões e segurança de token

Nas APIs de Gerar Token, a seção GenerateTokenRequest descreve as permissões do token.

Nível de Acesso

  • Para conceder ao usuário permissões de visualização ou edição, use o parâmetro allowEdit.

  • Para permitir que o usuário crie novos relatórios (SaveAs ou CreateNew) nesse espaço de trabalho, adicione o ID do espaço de trabalho ao token de incorporação.

Segurança ao Nível da Linha

Com a RLS (Segurança de Nível de Linha), a identidade que você usa pode ser diferente da identidade da entidade de serviço ou do usuário mestre que você está usando para gerar o token. Usando identidades diferentes, você pode exibir informações incorporadas de acordo com o usuário que você está segmentando. Por exemplo, em seu aplicativo, você pode solicitar que os usuários entrem e, em seguida, exibir um relatório que contenha apenas informações de vendas se o usuário conectado for um funcionário de vendas.

Se você estiver usando RLS, às vezes pode deixar de fora a identidade do usuário (o parâmetro EffectiveIdentity ). Quando você não usa o parâmetro EffectiveIdentity , o token tem acesso a todo o banco de dados. Esse método pode ser usado para conceder acesso a usuários como administradores e gerentes, que têm permissão para exibir todo o modelo semântico. No entanto, você não pode usar esse método em todos os cenários. A tabela a seguir lista os diferentes tipos de RLS e mostra qual método de autenticação pode ser usado sem especificar a identidade de um usuário.

A tabela também mostra as considerações e limitações aplicáveis a cada tipo de SPI.

Tipo RLS Posso gerar um token de incorporação sem especificar o ID de usuário efetivo? Considerações e limitações
Segurança ao nível da linha na nuvem (Cloud RLS) ✔ Utilizador principal
✖ Entidade de serviço
RDL (relatórios paginados) ✖ Utilizador principal
✔ Entidade de serviço		 Não é possível usar um usuário mestre para gerar um token de incorporação para RDL.
Analysis Services (AS) em conexão ao vivo local ✔ Utilizador principal
✖ Entidade de serviço		 O usuário que gera o token de incorporação também precisa de uma das seguintes permissões:
  • Permissões de administrador do gateway
  • Permissão de representação da fonte de dados (ReadOverrideEffectiveIdentity)
    		•
    Conexão ao vivo do Analysis Services (AS) Azure ✔ Utilizador principal
    ✖ Entidade de serviço    		 A identidade do usuário que gera o token de incorporação não pode ser substituída. Os dados personalizados podem ser usados para implementar RLS dinâmico ou filtragem segura.

    Nota: A entidade de serviço deve fornecer seu ID de objeto como a identidade efetiva (nome de usuário RLS).
    Logon único (SSO) ✔ Utilizador principal
    ✖ Entidade de serviço    		 Uma identidade explícita (SSO) pode ser fornecida usando a propriedade identity blob em um objeto de identidade efetivo
    SSO e RLS na nuvem ✔ Utilizador principal
    ✖ Entidade de serviço    		 Deve fornecer:
  • Identidade explícita (SSO) na propriedade de blob de identidade em um objeto de identidade efetivo
  • Identidade efetiva (RLS) (nome de usuário)
    		•

    Nota

    As entidades de serviço devem sempre fornecer:

    • Uma identidade para qualquer item com um modelo semântico RLS
    • Uma identidade RLS eficaz com a identidade contextual (SSO) definida (Para um modelo semântico SSO)

    DirectQuery para modelos semânticos do Power BI

    Para incorporar um relatório do Power BI que tenha um modelo semântico com uma conexão de Consulta Direta a outro modelo semântico do Power BI:

    Renovar tokens antes que eles expirem

    Os tokens vêm com um limite de tempo. Portanto, depois de incorporar um item do Power BI, você tem um tempo limitado para interagir com ele. Para oferecer aos usuários uma experiência contínua, renove (ou atualize) o token antes que ele expire.

    Painéis e blocos

    O token Gerar funciona para relatórios e modelos semânticos. Para gerar um token de incorporação para um painel ou bloco, use as APIs GenerateTokenInGroup ou Tiles GenerateTokenInGroup da versão 1. Essas APIs geram tokens para apenas um item de cada vez. Não é possível gerar um token para vários itens.

    Para estas APIs:

    • Use o parâmetro accessLevel para determinar o nível de acesso do usuário.

      • Exibir - Conceda permissões de visualização ao usuário.

      • Editar - Conceda ao usuário permissões de visualização e edição (aplica-se apenas ao gerar um token de incorporação para um relatório).

      • Criar - Conceda ao usuário permissões para criar um novo relatório (só se aplica ao gerar um token de incorporação para criar um relatório). Para a criação de relatórios, você também deve fornecer o parâmetro datasetId .

    • Use o booleano allowSaveAs para permitir que os usuários salvem o relatório como um novo relatório. Essa configuração é definida como false por padrão e só se aplica ao gerar um token de incorporação para um relatório.

    Considerações e limitações

    • Por motivos de segurança, o tempo de vida do token de incorporação é definido como o tempo de vida restante do token do Microsoft Entra usado para chamar a GenerateToken API. Portanto, se você usar o mesmo token do Microsoft Entra para gerar vários tokens de incorporação, o tempo de vida dos tokens de incorporação gerados ficará mais curto a cada chamada.

    • Se o modelo semântico e o item a ser incorporado estiverem em dois espaços de trabalho diferentes, a entidade de serviço ou o usuário mestre deverá ser pelo menos um membro de ambos os espaços de trabalho.

    • Incorporar itens usando o Data Lake Storage (DLS) requer V2 da API Gerar token .

    • Não é possível criar um token de incorporação para Meu espaço de trabalho.

    Conteúdos relacionados