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 de token de geração usa uma única identidade (um usuário mestre ou entidade de serviço) para gerar um token para um usuário individual, dependendo das credenciais desse usuário no aplicativo (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. É preferível às APIs herdadas da versão 1. Para painéis e blocos, use os painéis V1 GenerateTokenInGroup e Tiles GenerateTokenInGroup.

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 token gerar, a seção GenerateTokenRequest descreve as permissões de token.

Nível de Acesso

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

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

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 abaixo 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    		 Você deve fornecer o seguinte:
  • 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 as seguintes informações:

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

    DirectQuery para modelos semânticos do Power BI

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

    • No portal do Power BI, defina o ponto de extremidade XMLA como Somente Leitura ou Gravação de Leitura, conforme descrito em habilitar leitura-gravação para uma capacidade Premium. Você só precisa fazer isso uma vez por capacidade.
    • Gerar um token de incorporação de vários recursos
      • Especifique todos os IDs do conjunto de dados na solicitação.
      • Defina como XmlaPermissionsSomente leitura para cada modelo semântico na solicitação.
      • Para cada fonte de dados habilitada para SSO (Single Sign-on), forneça o blob de identidade para a fonte de dados no DatasourceIdentity.

    Renovar tokens antes que eles expirem

    Os tokens vêm com um limite de tempo. Isso significa que, 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 será menor 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.

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

    Conteúdos relacionados