Partilhar via

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

  • Artigo

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

Neste tutorial, você aprenderá a incorporar:

  • Um relatório do Power BI
  • Em uma incorporação para seu aplicativo da organização
  • Usando o .NET 5.0
  • Com a biblioteca (esta biblioteca também é suportada Microsoft.Identity.Web no .NET Core)

Nota

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

Pré-requisitos

Recursos

Neste tutorial, você usa:

  • API de Relatórios REST do Power BI - para incorporar a URL e recuperar o token de incorporação.
  • Biblioteca de autenticação do Microsoft Identity Web.
  • APIs de cliente de análise incorporada do Power BI - para incorporar o relatório.

Método

Para incorporar conteúdo do Power BI em uma solução incorporada para sua organização , siga estas etapas:

  1. Configurar seu aplicativo Microsoft Entra
  2. Obter os valores dos parâmetros de incorporação
  3. Adicionar os pacotes NuGet necessários
  4. Habilitar autenticação do lado do servidor
  5. Crie o lado do cliente do seu aplicativo
  6. Execute seu aplicativo

Etapa 1 - Configurar seu aplicativo 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 incorporar itens do Power BI, como relatórios, painéis ou blocos.

Se você não tiver um aplicativo Microsoft Entra, crie um usando as instruções em Registrar um aplicativo 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 dos parâmetros de incorporação

Para incorporar seu relatório, você precisa dos seguintes valores:

ID do domínio e do inquilino

Se não souber o seu domínio ou ID de inquilino, consulte Localizar o ID de inquilino do Microsoft Entra e o nome de domínio principal.

Nota

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

ID de 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 por Registos de aplicações e selecione a ligação Registos de aplicações.

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

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

Segredo do cliente

Para obter o segredo do cliente, siga estes passos:

  1. Faça logon no Microsoft Azure.

  2. Pesquise por Registos de aplicações e selecione a ligação Registos de aplicações.

  3. Selecione o aplicativo Microsoft Entra que você está usando para incorporar 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 pop-up Adicionar um segredo do cliente, forneça uma descrição para o 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 secreto do cliente é o ID do cliente.

Nota

Certifique-se de copiar o valor secreto do cliente quando ele aparecer pela primeira vez. Depois de navegar para fora desta página, o segredo do cliente será oculto e você não poderá recuperar seu valor.

ID da área de trabalho

Para obter o GUID do ID do espaço de trabalho, siga estas etapas:

  1. Iniciar sessão no serviço Power BI.

  2. Abra o relatório que pretende incorporar.

  3. Copie o GUID do 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

Nota

Para obter a ID do espaço de trabalho programaticamente, use a API Obter Grupos .

ID do relatório

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

  1. Iniciar sessão no serviço Power BI.

  2. Abra o relatório que pretende incorporar.

  3. Copie o GUID do 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

Nota

Para obter a ID do relatório programaticamente, use a API Obter relatórios em grupo .

Etapa 3 - Adicionar os pacotes NuGet necessários

Antes de começar, você precisa adicionar os Microsoft.Identity.Webpacotes e Microsoft.PowerBI.Api NuGet ao seu 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é Tools>NuGet Package Manager Package Manager>Console 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 seu aplicativo usado Microsoft.AspNetCore anteriormente para autenticar, remova este pacote do seu projeto digitando:

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

Etapa 4 - Habilitar a autenticação no servidor

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

Ficheiro Utilizar
Startup.cs Inicializar o Microsoft.Identity.Web serviço de autenticação
appsettings.json Detalhes de autenticação
PowerBiServiceApi.cs Obter o token do Microsoft Entra e incorporar metadados
HomeController.cs Passar dados incorporados como um modelo para a exibição

Configure seu arquivo de inicialização para oferecer suporte Microsoft.Identity.Web

Modifique o código na inicialização.cs para inicializar corretamente o serviço de autenticação fornecido pelo Microsoft.Identity.Web.

Adicione o seguinte trecho de código ao arquivo Startup.cs do seu aplicativo.

Nota

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

  1. A chamada para configurar a Biblioteca de Autenticação da Microsoft para AddMicrosoftWebAppCallsWebApi adquirir tokens de acesso (tokens do Microsoft Entra).
  2. A chamada para configurar um cache de token que a Biblioteca de Autenticação da Microsoft usará para AddInMemoryTokenCaches armazenar tokens de acesso em cache e atualizar tokens nos bastidores
  3. A chamada para services.AddScoped(typeof(PowerBiServiceApi)) configurar a classe como uma classe de serviço que pode ser adicionada a PowerBiServiceApi outras classes usando 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 contém informações confidenciais, como ID do cliente e segredo doappsettings.json cliente. Por motivos de segurança, não recomendamos manter essas informações no arquivo de configurações. Ao incorporar em seu aplicativo, considere um método mais seguro, como o Azure Key Vault , para manter essas informações.

  1. Em seu projeto, crie um novo arquivo e chame-o de 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 dos parâmetros de incorporação obtidos na Etapa 2 - Obter os valores dos parâmetros de incorporação.

Nota

No trecho de código anterior, o parâmetro é adicionado como um valor de configuração personalizado para controlar a URL base para o PowerBi:ServiceRootUrl serviço do Power BI. Ao programar com base no serviço 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 do governo. Portanto, esse valor é armazenado como um valor de configuração do projeto para que seja fácil de alterar quando necessário.

Obtenha o token de acesso do Microsoft Entra e chame o serviço do Power BI

Para incorporar conteúdo do Power BI (como relatórios e painéis), 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 tempo de execução do .NET Core cuida de passar a instância de serviço em tempo de execução. Nesse caso, o construtor está injetando uma instância do serviço de configuração .NET Core usando o parâmetro, que é usado para recuperar o IConfigurationPowerBi:ServiceRootUrl valor de configuração de appsettings.json. O ITokenAcquisition parâmetro, que é nomeado tokenAcquisition , contém uma referência ao serviço de autenticação da Microsoft fornecido pela Microsoft.Identity.Web biblioteca 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 suportadas pela API de serviço do Power BI. Quando seu aplicativo chama pela rede para adquirir um token do Microsoft Entra, passa esse conjunto de permissões delegadas para que o ID do Microsoft Entra possa incluí-las no token de acesso retornado.

Nota

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

  1. No projeto do seu 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ê usa a injeção de dependência. Como você registrou a PowerBiServiceApi classe como um serviço chamando services.AddScoped o ConfigureServices método. Você pode adicionar um PowerBiServiceApi parâmetro ao construtor, e o tempo de execução do .NET Core cuida de criar uma PowerBiServiceApi instância e passá-la para o construtor.

Na pasta Controllers , abra o arquivo HomeController.cs e adicione-o ao seguinte trecho 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 - Crie o lado do cliente do seu aplicativo

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

Ficheiro Utilizar
incorporar.js Contém o código JavaScript do lado do cliente
Incorporar.cshtml Contém o DOM (modelo de objeto de documento) do aplicativo e um DIV para incorporar o relatório

Criar um contêiner para seu relatório incorporado

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

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

  2. Adicione o seguinte trecho de código 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>
}

Adicione JavaScript do lado do cliente para incorporar seu relatório

Para incorporar 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 Incorporar um relatório.

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

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

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

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

  2. Adicione o seguinte trecho de código ao arquivo .js incorporação.

    $(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 seu aplicativo

Depois de fazer todos os ajustes listados neste tutorial, você estará pronto para executar seu aplicativo. Execute seu aplicativo e experimente a maneira como seu relatório do Power BI é incorporado. Você pode usar as APIs de cliente de análise incorporada do Power BI para aprimorar seu aplicativo usando APIs do lado do cliente.

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

Conteúdos relacionados

Tokens de aplicativos de análise incorporados

Mova seu aplicativo incorporado para a produção

Capacidade e SKUs na análise incorporada do Power BI

Planejamento de capacidade na análise incorporada do Power BI