Tutorial: Inserir um relatório do Power BI em um aplicativo para a organização

  • Artigo

Este tutorial explica como inserir um relatório do Power BI em um aplicativo .NET 5.0, como parte da solução de inserção para sua organização (também conhecida como o usuário possui dados). Em uma solução inserir para a organização, os usuários do aplicativo precisam se autenticar no Power BI com as próprias credenciais.

Neste tutorial, você aprenderá a inserir:

  • Um relatório do Power BI
  • Em um aplicativo inserir para a organização
  • Usando o .NET 5.0
  • Com a biblioteca Microsoft.Identity.Web (essa biblioteca também tem suporte no .NET Core)

Observação

A solução completa usada neste tutorial está disponível no repositório do GitHub DOTNET5-UserOwnsData-Tutorial.

Pré-requisitos

Recursos

Neste tutorial, você usará:

Método

Para inserir conteúdo do Power BI em uma solução inserir para a organização, siga estas etapas:

  1. Configurar seu aplicativo do Microsoft Entra
  2. Obter os valores de parâmetro de inserção
  3. Adicionar os pacotes NuGet necessários
  4. Habilitar a autenticação do lado do servidor
  5. Criar o lado do cliente do aplicativo
  6. Executar seu aplicativo

Etapa 1 - Configurar seu aplicativo do Microsoft Entra

Quando seu aplicativo Web chama o Power BI, ele precisa de um token do Microsoft Entra para chamar APIs REST do Power BI e inserir itens do Power BI, como relatórios, painéis ou blocos.

Se você não tem um aplicativo do Microsoft Entra, crie um usando as instruções em Registrar um aplicativo do Microsoft Entra para usar com o Power BI.

Para configurar o aplicativo do Microsoft Entra, siga as instruções em Configurar seu aplicativo do Microsoft Entra.

Etapa 2 – Obter os valores do parâmetro de inserção

Para inserir o relatório, você precisará dos seguintes valores:

ID de locatário e domínio

Se não souber qual é sua ID de locatário ou domínio, confira Localizar a ID de locatário e o nome de domínio primário do Microsoft Entra.

Observação

Para inserir conteúdo para um usuário em um locatário diferente (um usuário convidado), você precisará ajustar o parâmetro authorityUri.

ID do Cliente

Para obter o GUID da ID do cliente (também conhecido como ID do aplicativo), siga estas etapas:

  1. Entre no Microsoft Azure.

  2. Pesquise Registros de aplicativo e selecione o link Registros de aplicativo.

  3. Selecione o aplicativo do Microsoft Entra que você está usando para inserir o seu conteúdo do Power BI.

  4. Na seção Visão geral, copie o GUID da ID do aplicativo (cliente) .

Segredo do cliente

Para obter o segredo do cliente, siga estas etapas:

  1. Entre no Microsoft Azure.

  2. Pesquise Registros de aplicativo e selecione o link Registros de aplicativo.

  3. Selecione o aplicativo do Microsoft Entra que você está usando para inserir o seu conteúdo do Power BI.

  4. Em Gerenciar, selecione Certificados e segredos.

  5. Em Segredos do cliente, selecione Novo segredo do cliente.

  6. Na janela pop-up Adicionar um segredo do cliente, forneça uma descrição do segredo do aplicativo, selecione quando o segredo do aplicativo expira e selecione Adicionar.

  7. Na seção Segredos do cliente, copie a cadeia de caracteres na coluna Valor do segredo do aplicativo recém-criado. O valor do segredo do cliente é a sua ID do cliente.

Observação

Copie o valor do segredo do cliente quando aparecer pela primeira vez. Depois de navegar para fora dessa página, o segredo do cliente ficará oculto e você não poderá recuperar seu valor.

ID do workspace

Para obter o GUID da ID do workspace, siga estas etapas:

  1. Entre no serviço do Power BI.

  2. Abra o relatório que deseja inserir.

  3. Copie o GUID da URL. O GUID é o número entre /groups/ e /reports/ .

    A screenshot showing workspace ID GUID in the Power B I service U R L

Observação

Para obter a ID do workspace de maneira programática, use a API Obter Grupos.

ID do Relatório

Para obter o GUID da ID do relatório, siga estas etapas:

  1. Entre no serviço do Power BI.

  2. Abra o relatório que deseja inserir.

  3. Copie o GUID da URL. O GUID é o número entre /reports/ e /ReportSection.

    A screenshot showing report ID GUID in the Power B I service U R L

Observação

Para obter a ID do relatório de maneira programática, use a API Obter Relatórios no Grupo.

Etapa 3 – Adicionar os pacotes NuGet necessários

Antes de começar, você precisará adicionar os pacotes NuGet Microsoft.Identity.Web e Microsoft.PowerBI.Api ao aplicativo.

Adicione os seguintes pacotes NuGet ao seu aplicativo:

  • No VS Code, abra um terminal e digite o código a seguir.

  • No Visual Studio, navegue até Ferramentas>Gerenciador de Pacote NuGet>Console de Gerenciamento de Pacotes e digite o código a seguir.

dotnet add package Microsoft.Identity.Web -v 0.3.0-preview
dotnet add package Microsoft.Identity.Web.UI -v 0.3.0-preview
dotnet add package Microsoft.PowerBI.Api

Se o aplicativo usou Microsoft.AspNetCore para se autenticar, remova esse pacote do projeto digitando:

dotnet remove package Microsoft.AspNetCore.Authentication.AzureAD.UI

Etapa 4 – Habilitar a autenticação no lado do servidor

Habilite a autenticação do lado do servidor em seu aplicativo criando ou modificando os arquivos na tabela a seguir.

Arquivo Uso
Startup.cs Inicializar o serviço de autenticação Microsoft.Identity.Web
appsettings.json Detalhes de autenticação
PowerBiServiceApi.cs Obter o token do Microsoft Entra e inserir metadados
HomeController.cs Transmitir dados de inserção como um modelo para a exibição

Configurar o arquivo de inicialização para dar suporte a Microsoft.Identity.Web

Modifique o código em Startup.cs para inicializar corretamente o serviço de autenticação fornecido por Microsoft.Identity.Web.

Adicione o snippet de código a seguir ao arquivo Startup.cs do aplicativo.

Observação

O código em ConfigureServices realiza várias coisas importantes:

  1. A chamada para AddMicrosoftWebAppCallsWebApi configura a Biblioteca de Autenticação da Microsoft para adquirir tokens de acesso (tokens do Microsoft Entra).
  2. A chamada para AddInMemoryTokenCaches configura um cache de token que será usado pela Biblioteca de Autenticação da Microsoft para armazenar em cache os tokens de acesso e atualizar tokens nos bastidores
  3. A chamada para services.AddScoped(typeof(PowerBiServiceApi)) configura a classe PowerBiServiceApi como uma classe de serviço que pode ser adicionada a outras classes usando a injeção de dependência.
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Identity.Web.UI;
using UserOwnsData.Services;

namespace UserOwnsData {

  public class Startup {

    public Startup (IConfiguration configuration) {
      Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices (IServiceCollection services) {

      services
        .AddMicrosoftIdentityWebAppAuthentication(Configuration)
        .EnableTokenAcquisitionToCallDownstreamApi(PowerBiServiceApi.RequiredScopes)
        .AddInMemoryTokenCaches();

      services.AddScoped (typeof (PowerBiServiceApi));

      var mvcBuilder = services.AddControllersWithViews (options => {
        var policy = new AuthorizationPolicyBuilder()
          .RequireAuthenticatedUser()
          .Build();
        options.Filters.Add (new AuthorizeFilter (policy));
      });

      mvcBuilder.AddMicrosoftIdentityUI();

      services.AddRazorPages();

    }
  }
}

Criar um arquivo de detalhes de autenticação

Neste tutorial, o arquivo appsettings.json contém informações confidenciais, como a ID do cliente e o segredo do cliente. Por motivos de segurança, não recomendamos manter essas informações no arquivo de configurações. Ao inserir no aplicativo, considere um método mais seguro, como o Azure Key Vault, para manter essas informações.

  1. No projeto, crie um arquivo e dê a ele o nome appsettings.json.

  2. Adicione o seguinte código a appsettings.json:

    {
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "Domain": "",
        "TenantId": "",
        "ClientId": "",
        "ClientSecret": "",
        "CallbackPath": "/signin-oidc",
        "SignedOutCallbackPath": "/signout-callback-oidc"
    },
    "PowerBi": {
        "ServiceRootUrl": "https://api.powerbi.com"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

  3. Preencha os valores do parâmetro de inserção obtidos na Etapa 2 – Obter os valores do parâmetro de inserção.

Observação

No snippet de código anterior, o parâmetro PowerBi:ServiceRootUrl é adicionado como um valor de configuração personalizado para acompanhar a URL de base para o serviço do Power BI. Quando você está programando em um serviço do Power BI na nuvem pública da Microsoft, a URL é https://api.powerbi.com/. No entanto, a URL raiz para o serviço do Power BI será diferente em outras nuvens, como a nuvem governamental. Portanto, esse valor é armazenado como um valor de configuração do projeto, de modo que é fácil alterá-lo sempre que necessário.

Obter o token de acesso do Microsoft Entra e chamar o serviço do Power BI

Para inserir conteúdo do Power BI (como relatórios e dashboards), seu aplicativo precisa obter um token do Microsoft Entra. Para obter o token, você precisará de um objeto de configuração.

O código nesta seção usa o padrão de injeção de dependência do .NET Core. Quando sua classe precisa usar um serviço, você pode adicionar um parâmetro de construtor para esse serviço e o runtime do .NET Core cuida da transmissão da instância de serviço no tempo de execução. Nesse caso, o construtor está injetando uma instância do serviço de configuração do .NET Core usando o parâmetro IConfiguration, que é usado para recuperar o valor de configuração PowerBi:ServiceRootUrl de appsettings.json. O parâmetro ITokenAcquisition, que é nomeado tokenAcquisition, contém uma referência ao serviço de autenticação da Microsoft fornecido pela biblioteca Microsoft.Identity.Web e é usado para adquirir tokens de acesso do Microsoft Entra ID.

O campo RequiredScopes contém uma matriz de cadeia de caracteres que contém um conjunto de permissões delegadas com suporte da API de serviço do Power BI. Quando seu aplicativo chama a rede para adquirir um token do Microsoft Entra, ele passa esse conjunto de permissões delegadas para que o Microsoft Entra ID possa incluí-las no token de acesso retornado.

Observação

Verifique se o aplicativo do Microsoft Entra está configurado com os escopos exigidos pelo aplicativo Web. Para obter mais informações, confira Alterar as permissões de aplicativo do Microsoft Entra.

  1. No projeto do aplicativo, crie uma pasta chamada Services.

  2. Na pasta Services, crie um arquivo intitulado PowerBiServiceApi.cs.

  3. Adicione o código a seguir a PowerBiServiceApi.cs.

    using Microsoft.Identity.Web;
using Microsoft.PowerBI.Api;
using Microsoft.PowerBI.Api.Models;
using Microsoft.Rest;
using Newtonsoft.Json;

namespace UserOwnsData.Services {

  // A view model class to pass the data needed to embed a single report.
  public class EmbeddedReportViewModel {
     public string Id;
     public string Name;
     public string EmbedUrl;
     public string Token;
  }

public class PowerBiServiceApi {
     private ITokenAcquisition tokenAcquisition { get; }
     private string urlPowerBiServiceApiRoot { get; }

     public PowerBiServiceApi(IConfiguration configuration, ITokenAcquisition tokenAcquisition) {
         this.urlPowerBiServiceApiRoot = configuration["PowerBi:ServiceRootUrl"];
         this.tokenAcquisition = tokenAcquisition;
     }

     public static readonly string[] RequiredScopes = new string[] {
         "https://analysis.windows.net/powerbi/api/Report.Read.All"
     };

    // A method to get the Azure AD token (also known as 'access token')
     public string GetAccessToken() {
         return this.tokenAcquisition.GetAccessTokenForUserAsync(RequiredScopes).Result;
     }

     public PowerBIClient GetPowerBiClient() {
         var tokenCredentials = new TokenCredentials(GetAccessToken(), "Bearer");
         return new PowerBIClient(new Uri(urlPowerBiServiceApiRoot), tokenCredentials);
     }

     public async Task<EmbeddedReportViewModel> GetReport(Guid WorkspaceId, Guid ReportId) {
         PowerBIClient pbiClient = GetPowerBiClient();
         // Call the Power BI Service API to get embedding data
   var report = await pbiClient.Reports.GetReportInGroupAsync(WorkspaceId, ReportId);

   // Return report embedding data to caller
   return new EmbeddedReportViewModel {
    Id = report.Id.ToString(),
    EmbedUrl = report.EmbedUrl,
    Name = report.Name,
    Token = GetAccessToken()
   };
  }

 }

}

Modificar o arquivo HomeController.cs

Neste exemplo de código, você usará a injeção de dependência. Como você registrou a classe PowerBiServiceApi como um serviço chamando services.AddScoped no método ConfigureServices, Você pode adicionar um parâmetro PowerBiServiceApi ao construtor, e o runtime do .NET Core cuida de criar uma instância PowerBiServiceApi e passá-la para o construtor.

Na pasta Controllers, abra o arquivo HomeController.cs e adicione a ele o seguinte snippet de código:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using UserOwnsData.Models;
using UserOwnsData.Services;

namespace UserOwnsData.Controllers {
    [Authorize]
    public class HomeController : Controller {

        private PowerBiServiceApi powerBiServiceApi;

        public HomeController (PowerBiServiceApi powerBiServiceApi) {
            this.powerBiServiceApi = powerBiServiceApi;
        }

        [AllowAnonymous]
        public IActionResult Index() {
            return View();
        }

        public async Task<IActionResult> Embed() {
            Guid workspaceId = new Guid("11111111-1111-1111-1111-111111111111");
            Guid reportId = new Guid("22222222-2222-2222-2222-222222222222");
            var viewModel = await powerBiServiceApi.GetReport(workspaceId, reportId);
            return View(viewModel);
        }

        [AllowAnonymous]
        [ResponseCache (Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
        public IActionResult Error() {
            return View (new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
        }
    }
}

Etapa 5 – Criar o lado do cliente do aplicativo

Para implementação do lado do cliente, você precisa criar ou modificar os arquivos na tabela a seguir.

Arquivo Uso
embed.js Contém o código JavaScript do lado do cliente
Embed.cshtml Contém o DOM (modelo de objeto do documento) do aplicativo e um DIV para inserir o relatório

Criar um contêiner para o relatório inserido

Crie o arquivo Embed.cshtml, que tem um elemento div usado como um contêiner para o relatório inserido e três scripts.

  1. Na pasta View>Home, crie um arquivo chamado Embed.cshtml.

  2. Adicione o snippet de código a seguir ao arquivo Embed.cshtml.

    @model UserOwnsData.Services.EmbeddedReportViewModel;

<div id="embed-container" style="height:800px;"></div>

@section Scripts {

    <!-- powerbi.min.js is the JavaScript file that loads the client-side Power BI JavaScript API library.
    Make sure that you're working with the latest library version.
    You can check the latest library available in https://cdnjs.com/libraries/powerbi-client -->
    <script src="https://cdn.jsdelivr.net/npm/powerbi-client@2.21.0/dist/powerbi.min.js"></script>

    <!-- This script creates a JavaScript object named viewModel which is accessible to the JavaScript code in embed.js. -->
    <script> 
        var viewModel = {
            reportId: "@Model.Id",
            embedUrl: "@Model.EmbedUrl",
            token: "@Model.Token"
        }; 
    </script>

    <!-- This script specifies the location of the embed.js file -->
    <script src="~/js/embed.js"></script>
}

Adicionar JavaScript do lado do cliente para inserir o relatório

Para inserir conteúdo do Power BI, você precisa criar um objeto de configuração. Para saber mais sobre como criar o objeto de configuração, confira Inserir um relatório.

Nesta seção, você criará um arquivo JavaScript chamado embed.js com um objeto de configuração para inserir seu relatório, usando a variável models.

models é inicializado usando uma chamada para window['powerbi-client'].models. A variável models é usada para definir valores de configuração como models.Permissions.All, models.TokenType.Aad e models.ViewMode.View.

A função powerbi.embed usa o objeto de configuração models para inserir o relatório.

  1. Na pasta wwwroot>js, crie um arquivo chamado embed.js.

  2. Adicione o snippet de código a seguir ao arquivo embed.js.

    $(function(){
    // 1 - Get DOM object for div that is report container
    let reportContainer = document.getElementById("embed-container");

    // 2 - Get report embedding data from view model
    let reportId = window.viewModel.reportId;
    let embedUrl = window.viewModel.embedUrl;
    let token = window.viewModel.token

    // 3 - Embed report using the Power BI JavaScript API.
    let models = window['powerbi-client'].models;
    let config = {
        type: 'report',
        id: reportId,
        embedUrl: embedUrl,
        accessToken: token,
        permissions: models.Permissions.All,
        tokenType: models.TokenType.Aad,
        viewMode: models.ViewMode.View,
        settings: {
            panes: {
                filters: { expanded: false, visible: true },
                pageNavigation: { visible: false }
            }
        }
    };

    // Embed the report and display it within the div container.
    let report = powerbi.embed(reportContainer, config);

    // 4 - Add logic to resize embed container on window resize event
    let heightBuffer = 12;
    let newHeight = $(window).height() - ($("header").height() + heightBuffer);
    $("#embed-container").height(newHeight);
    $(window).resize(function() {
        var newHeight = $(window).height() - ($("header").height() + heightBuffer);
        $("#embed-container").height(newHeight);
    });

});

Etapa 6 – Executar o aplicativo

Depois de fazer todos os ajustes listados neste tutorial, você estará pronto para executar o aplicativo. Execute o aplicativo e experimente com a maneira como o relatório do Power BI é inserido. Use as APIs de Cliente de análise integrada do Power BI para aprimorar o aplicativo usando APIs do lado do cliente.

Quando o aplicativo estiver pronto, você poderá mover o aplicativo inserido para produção.

Conteúdo relacionado

Tokens do aplicativo de análise incorporados

Mover o seu aplicativo inserido para produção

Capacidade e SKUs em análises integradas do Power BI

Planejamento da capacidade em análise integrada do Power BI