Mostrar relatório no seu sistema
Como obter a Chave de API para autenticação as requisições
O primeiro passo, é obter a chave da API na tela de configurações para autenticar:
Com essa chave, você já consegue autenticar as requisições utilizando a API.
Método 1: Utilizar o endpoint Identity/URL
Para retornar a URL que você irá utilizar para acessar o portal de relatórios de forma transparente, sem passar pela tela de login, utilize a chamada POST abaixo:
O cabeçalho X-API-Key deve ser informado, passando como valor, o token da API gerado acima pela tela de configurações.
O corpo da requisição (body) possui os seguintes valores possíveis:
Parâmetros gerais
userEmail: Único campo obrigatório na requisição. Deve ser informado o email da pessoa que está logada no seu sistema. Esse usuário que será gravado nas auditorias e os relatórios que esse usuário tem acesso que serão mostrados na tela. Caso o relatório tenha RLS, este será aplicado automaticamente, utilizando as regras de filtragem desse usuário informado.
baseUrl: Neste campo, você deve preencher com a informação do subdomínio configurado. É obrigatório informar esse dado para que toda a experiência seja personalizada, inclusive no caso de expiração do token.
Quando os parâmetros de organizationId e reportId NÃO são informados, o portal de visualização completo será renderizado no seu sistema, assim como quando você acessa no modo tradicional (sem API), mostrando apenas os relatórios que o usuário informado possui acesso. O usuário poderá navegar livremente nos relatórios que ele possui acesso.
Parâmetros para controle de exibição
hideMenu: Oculta a barra de menus quando o relatório é aberto.
hideNavbar: Oculta a barra de navegação quando o relatório é aberto.
hideSidebar: Oculta a barra lateral na tela de navegação.
embed: É um parâmetro atalho que pode ser utilizado para definir todas as propriedades de exibição acima de uma única vez.
Parâmetros para exibição de um relatório apenas
Caso você queira exibir um relatório específico, você precisará informar, obrigatoriamente, os 2 parâmetros abaixo:
organizationId: É o ID único da sua organização no sistema. Esse ID é fixo e nunca é alterado. Esse ID você pode obter na URL da tela de “Configurações"
reportId: É o ID do relatório, onde cada relatório tem o seu ID único (é o mesmo reportId do relatório no Power BI serviço). Para obter o ID do relatório, capture o ID que fica na URL da tela de edição do relatório:
Retorno da API
O retorno da API é uma URL que só pode ser acessada uma única vez e caso não tenha acesso, irá expirar em 5 minutos:
Caso você tenha informado os outros parâmetros, como organizationId e reportId (para mostrar apenas 1 relatório) e os parâmetros de exibição, a requisição terá esse formato:
E a URL retornada será algo assim:
Com essa URL gerada, você só precisa criar um iframe utilizando ela como o exemplo abaixo:
E com isso, você já consegue mostrar os relatórios do Power BI na sua aplicação, através do Power Embedded, de forma transparente e segura.
Como o token da URL é de uso ÚNICO, essa URL só pode ser acessada uma única vez. Caso você queira mostrar o relatório novamente, terá que executar essa requisição novamente.
Como o token é para o usuário específico, ao acessar um relatório, o Power Embedded sabe quem é o usuário que está acessando e faz as devidas validações se esse usuário possui acesso ao relatório que está sendo mostrado e aplica as regras de RLS, caso o relatório possua.
Método 2: Utilizando o endpoint Identity/Token
Para conseguir gerar o token de acesso e renderizar os relatórios na sua aplicação, você deverá primeiro obter o token usando a chamada abaixo:
E o servidor irá retornar o token de uso ÚNICO para chamar as API’s (cada requisição deverá solicitar um novo token):
Agora podemos fazer a chamada da API que renderiza o relatório, informando como parâmetros:
A URL base do portal de visualização (Ex: https://relatorios.powerembedded.com.br – Aqui você utiliza o seu domínio personalizado, como https://bi.suaempresa.com.br/, por exemplo)
O token gerado no passo anterior (Ex: 2506b719-5a7e-789b-812f-c64013cc617f)
O ID da organização (ID fixo para cliente do Power Embedded – Está na URL da tela de configurações – Ex: 12201800-1a46-491a-bfe3-6ee5590e372e)
O ID do relatório que será embeddado (Ex: a4ee7a1e-6c65-44e7-9a38-06dd8514483c)
Com isso, você irá abrir um iframe com a seguinte URL: https://bi.suaempresa.com.br/integration/tokenauth?token={token_gerado}&embed=true&returnUrl=/Organization/{Id_da_Organizacao}/Report/{Id_Relatorio}
Exemplo com as variáveis preenchidas: https://bi.suaempresa.com.br/integration/tokenauth?token=98b6e796-3b1f-4f2f-abfe-aa2a8a1eadb8&embed=true&returnUrl=/Organization/12201800-1a46-491a-bfe3-6ee5590e372e/Report/a4ee7a1e-6c65-44e7-9a38-06dd8514483c
Como o token é de uso ÚNICO, essa URL só pode ser acessada uma única vez.
Caso você queira embeddar o relatório novamente, terá que gerar um novo token de acesso para o e-mail informado.
Como o token é para o usuário específico, ao acessar um relatório, o Power Embedded sabe quem é o usuário que está acessando e faz as devidas validações se esse usuário possui acesso ao relatório que está sendo embeddado e aplica as regras de RLS, caso o relatório possua.
Documentação
Documentação completa da API: Swagger UI (powerembedded.com.br)
Página de demonstração da API para Embeddar os relatórios: Demo – PowerPortal.IntegrationDemo (powerembedded.com.br)
Atualizado
