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

Este tutorial explica como incorporar um relatório do Power BI em um aplicativo .NET 5.0, como parte da incorporação para sua organização (também conhecido como user owns data). Em uma integração para a solução da sua organização, os usuários do aplicativo precisam se autenticar com suas próprias credenciais no Power BI.

Neste tutorial, você aprenderá a inserir:

Pré-requisitos

• Uma licença Power BI Pro ou PPU (Premium por Usuário).

  Observação

  A solução inserir para a organização não tem suporte em capacidades baseadas em SKUs A. Um SKU A pode ser usado somente para a solução inserir para os clientes.

• Um workspace do Power BI com um relatório.

• Seu próprio locatário do Microsoft Entra.

• Um aplicativo do Microsoft Entra.

• Um aplicativo MVC (Model-View-Controller) do .NET Core 5.

• SDK do .NET Core 5 (ou superior).

• Um IDE (ambiente de desenvolvimento integrado). É recomendável usar um dos seguintes ambientes:

  • Visual Studio.
  • Visual Studio Code (com a extensão C#).

Recursos

Neste tutorial, você usará:

• API de Relatórios REST do Power BI – para inserir a URL e recuperar o token de inserção.
• Biblioteca de autenticação da Microsoft Identity Web.
• APIs de cliente de análise integrada do Power BI – para inserir o relatório.

Método

Para incorporar conteúdo do Power BI em uma incorporação para a solução da sua organização, siga as seguintes etapas:

1. Configurar seu aplicativo 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. Construa a parte cliente do seu 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, dashboards ou blocos.

Se você não tiver 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 seu aplicativo Microsoft Entra, siga as instruções em Configurar seu aplicativo Microsoft Entra.

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

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

• Domínio
• ID do locatário
• ID do cliente
• Segredo do cliente
• Workspace ID
• ID do relatório

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.

ID do Cliente

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

1. Faça logon 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. Faça logon 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 &segredos.

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

6. Na janela Adicionar um segredo do cliente (pop-up), forneça uma descrição para o segredo do aplicativo, escolha quando o segredo do aplicativo vence 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 é seu ID do cliente.

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/.

   

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.

   

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 Pacotes NuGet>Console do Gerenciador 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.

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 trecho de código a seguir no arquivo Startup.cs do aplicativo.

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 appsettings.json arquivo contém informações confidenciais, como ID do cliente e segredo do cliente. Por motivos de segurança, não recomendamos manter essas informações no arquivo de configurações. Ao inserir em seu 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 ao 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 de parâmetro de inserção obtidos da Etapa 2 – Obter os valores de parâmetro de inserção.

   • Domain - ID de domínio e locatário
   • TenantId - ID de domínio e locatário
   • ClientId - ID do cliente
   • ClientSecret - Segredo do cliente

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ê precisa 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 IConfiguration parâmetro, que é usado para recuperar o PowerBi:ServiceRootUrl valor de configuração 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 RequiredScopes campo contém uma matriz de cadeia de caracteres que contém um conjunto de permissões delegadas com suporte pela 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.

1. No projeto do aplicativo, crie uma nova pasta intitulada Serviços.

2. Na pasta Serviços , crie um novo arquivo intitulado PowerBiServiceApi.cs.

3. Adicione o seguinte código 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 Controladores , abra o arquivo HomeController.cs e adicione-o ao 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.

Criar um contêiner para o relatório inserido

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

1. Na pasta Exibir>Página Inicial , 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, consulte 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. Você pode usar as APIs de cliente de análise integrada do Power BI para aprimorar seu aplicativo usando APIs do lado do cliente.

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

Conteúdo relacionado

• Tokens de aplicativos de análises integradas
• Mova seu aplicativo embutido para produção
• Capacidade e SKUs na análise integrada do Power BI
• Planejamento de capacidade na análise integrada do Power BI