Compartilhar via

Gerar um token de inserção

  • Artigo

APLICA-SE A: Os dados pertencem ao aplicativo Os dados pertencem ao usuário

Gerar token é uma API REST que permite gerar um token para incorporar um relatório ou um modelo semântico do Power BI em um aplicativo Web ou um portal. Ela 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 em relação ao serviço do Power BI.

A API Gerar token usa uma única identidade (um usuário mestre ou uma entidade de serviço) a fim de gerar um token para um usuário individual, dependendo das credenciais do usuário no aplicativo (identidade efetiva).

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

Observação

Gerar token é a API de versão 2 mais recente que funciona para relatórios e modelos semânticos e itens únicos ou múltiplos. É preferível em relação às APIs herdadas da versão 1. Para dashboards e blocos, use os Dashboards GenerateTokenInGroup da V1 e fBlocos GenerateTokenInGroup.

Proteger os dados

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

É recomendável usar o isolamento baseado em workspace com perfis, mas se você quiser usar a abordagem RLS, examine a Seção do RLS no final deste artigo.

Permissões de token e segurança

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

Nível de acesso

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

  • Adicione a ID do workspace ao token de inserção para permitir que o usuário crie novos relatórios (SalvarComo ou Criar) nesse workspace.

Segurança em nível de linha

Com a RLS (Segurança em Nível de Linha), a identidade usada pode ser diferente daquela da entidade de serviço ou do usuário mestre com a qual você está gerando o token. Ao usar identidades diferentes, você pode exibir informações incorporadas de acordo com o usuário para o qual você está direcionando. Por exemplo, em seu aplicativo, você pode solicitar que os usuários entrem e exibam um relatório que contenha apenas informações de vendas caso o usuário conectado seja um funcionário de vendas.

Se você usar RLS poderá, em alguns casos, deixar de incluir 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ões para exibir o modelo semântico inteiro. No entanto, não é possível 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 RLS.

Tipo de RLS Posso gerar um token de inserção sem especificar a ID de usuário efetiva? Considerações e limitações
RLS de nuvem (Segurança em Nível de Linha de Nuvem) ✔ Usuário mestre
✖ Entidade de serviço
RDL (relatórios paginados) ✖ Usuário mestre
✔ Entidade de serviço		 Não é possível usar um usuário mestre a fim de gerar um token de inserção para RDL.
Conexão dinâmica do AS (Analysis Services) ✔ Usuário mestre
✖ Entidade de serviço		 O usuário que gera o token de inserçã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 dinâmica do Azure AS (Analysis Services) ✔ Usuário mestre
    ✖ Entidade de serviço    		 A identidade do usuário que está gerando o token de inserção não pode ser substituída. Os dados personalizados podem ser usados para implementar a RLS dinâmica ou a filtragem segura.

    Observação: a entidade de serviço deve fornecer sua ID de objeto como a identidade efetiva (nome de usuário de RLS).
    SSO (logon único) ✔ Usuário mestre
    ✖ Entidade de serviço    		 Uma identidade explícita (SSO) pode ser fornecida usando a propriedade de blob de identidade em um objeto de identidade efetiva
    SSO e RLS de nuvem ✔ Usuário mestre
    ✖ Entidade de serviço    		 Você deve fornecer o seguinte:
  • Uma identidade explícita (SSO) na propriedade de blob de identidade em um objeto de identidade efetiva
  • Identidade (RLS) efetiva (nome de usuário)
    		•

    Observação

    As entidades de serviço sempre devem fornecer as seguintes informações:

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

    Modelos semânticos do DirectQuery para Power BI

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

    Renovação dos tokens antes de expirar

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

    Dashboards e blocos

    Gerar token funciona para relatórios e modelos semânticos. Para gerar um token de inserção para um dashboard ou bloco, use APIs de Dashboards GenerateTokenInGroup ou Blocos GenerateTokenInGroup da versão 1. Essas APIs geram tokens para apenas um item por vez. Não é possível gerar um token para vários itens.

    Para essas APIs:

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

      • Exibir – conceda permissões de exibição ao usuário.

      • Editar – conceda permissões de exibição e edição ao usuário (aplica-se somente ao gerar um token de inserção para um relatório).

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

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

    Considerações e limitações

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

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

    • Não é possível criar um token de inserção para Meu workspace.

    Conteúdo relacionado