Compartilhar via

Tutorial: Inserir um relatório do Power BI em um aplicativo para seus clientes

  • Artigo

Neste tutorial, você aprenderá a inserir um relatório do Power BI em um aplicativo .NET 5.0 como parte da solução inserir para seus clientes (também conhecida como solução aplicativo possui dados). Em uma solução do tipo inserir para seus clientes, os usuários do aplicativo não precisarão entrar no Power BI ou ter uma licença do Power BI.

Neste tutorial, você aprenderá a inserir:

  • Um relatório do Power BI.
  • Em um aplicativo do tipo inserir para seus clientes.
  • Usando uma entidade de serviç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-AppOwnsData-Tutorial.

Pré-requisitos

Recursos

Neste tutorial, você usará:

Método

Para inserir conteúdo do Power BI em uma solução do tipo inserir para seus clientes, siga estas etapas:

  1. Configurar seu aplicativo do Microsoft Entra e a entidade de serviço.

  2. Obtenha os valores de parâmetro de inserção.

  3. Adicionar os pacotes NuGet necessários.

  4. Habilitar a autenticação no lado do servidor.

  5. Criar o lado do cliente do aplicativo.

  6. Executar seu aplicativo.

Etapa 1 - Configurar seu aplicativo do Microsoft Entra e a entidade de serviço

Neste tutorial, você usará uma entidade de serviço para autenticar seu aplicativo Web no Microsoft Entra ID. Você também precisa de um aplicativo do Microsoft Entra, que possibilita gerar um token do Microsoft Entra. Usando o token do Microsoft Entra, seu aplicativo Web pode chamar APIs REST do Power BI e inserir itens do Power BI, como relatórios, dashboards e blocos.

Siga as instruções da entidade de serviço para criar um aplicativo do Microsoft Entra e habilitar a entidade de serviço de aplicativos para trabalhar com seu conteúdo do Power BI.

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

    Uma captura de tela mostrando o GUID da ID do workspace na URL do serviço do Power BI

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.

    Uma captura de tela que mostra o GUID da ID do relatório na URL do serviço do Power BI

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 pacotes NuGet necessários ao aplicativo:

  • No VS Code, abra um terminal e insira 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
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api

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

Ative a autenticação no lado do servidor no 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 Configurar os detalhes da 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 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 System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.HttpsPolicy;
using Microsoft.AspNetCore.Mvc.Authorization;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using AppOwnsData.Services;

namespace AppOwnsData
{
    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()
            .AddInMemoryTokenCaches();

            services.AddScoped(typeof(PowerBiServiceApi));

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

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Home/Error");
                // The default HSTS value is 30 days. You might want to change this for production scenarios. See https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }
            app.UseHttpsRedirection();
            app.UseStaticFiles();

            app.UseRouting();

            app.UseAuthentication();
            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllerRoute(
                    name: "default",
                    pattern: "{controller=Home}/{action=Index}/{id?}");
                endpoints.MapRazorPages();
            });
        }
    }
}

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 uma ferramenta mais segura, como o Azure Key Vault, para proteger informações confidenciais.

  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": "yourtenant.onMicrosoft.com",
   "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 código anterior, o parâmetro PowerBi:ServiceRootUrl é adicionado como um valor de configuração personalizado para rastrear a URL base para o serviço do Power BI. Quando você programa 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 é diferente em outras nuvens, como a nuvem governamental. Portanto, o valor de configuração personalizado é armazenado como um valor de configuração do projeto para que você possa alterá-lo conforme 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 Azure AD. 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 precisar usar um serviço, você poderá adicionar um parâmetro de construtor para o serviço. O runtime do .NET Core cuida da passagem da instância de serviço em tempo de execução. Nesse caso, o construtor injeta 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 se chama tokenAcquisition, contém uma referência ao serviço de autenticação da Microsoft fornecido pela biblioteca Microsoft.Identity.Web. O parâmetro ITokenAcquisition é 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 o aplicativo chamar pela rede para adquirir um token do Azure AD, ele passará esse conjunto de permissões delegadas para que o Azure AD 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 System;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.Extensions.Configuration;
using Microsoft.Identity.Web;
using Microsoft.Rest;
using Microsoft.PowerBI.Api;
using Microsoft.PowerBI.Api.Models;
using Newtonsoft.Json;

namespace AppOwnsData.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 const string powerbiApiDefaultScope = "https://analysis.windows.net/powerbi/api/.default";

        // A method to get the Azure AD token (also known as 'access token')
        public string GetAccessToken() {
            return this.tokenAcquisition.GetAccessTokenForAppAsync(powerbiApiDefaultScope).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 the embedding data.
            var report = await pbiClient.Reports.GetReportInGroupAsync(WorkspaceId, ReportId);

            // Generate a read-only embed token for the report.
            var datasetId = report.DatasetId;
            var tokenRequest = new GenerateTokenRequest(TokenAccessLevel.View, datasetId);
            var embedTokenResponse = await pbiClient.Reports.GenerateTokenAsync(WorkspaceId, ReportId, tokenRequest);
            var embedToken = embedTokenResponse.Token;

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

    }
}

Modificar o arquivo HomeController.cs

Neste exemplo de código, você usa a injeção de dependência para modificar o arquivo HomeController.cs. Seguindo uma etapa anterior, você configurou a PowerBiServiceApi classe como um serviço chamando services.AddScoped no método ConfigureServices. Com esse código, você adiciona um parâmetro PowerBiServiceApi ao construtor e o runtime do .NET Core cria uma instância PowerBiServiceApi e a passa para o construtor.

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

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using AppOwnsData.Models;
using AppOwnsData.Services;

namespace AppOwnsData.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() {

            // Replace these two GUIDs with the workspace ID and report ID you recorded earlier.
            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 a implementação do lado do cliente, você precisará criar ou modificar os arquivos listados na seguinte tabela:

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

Neste tutorial, você cria o arquivo Embed.cshtml, que tem um elemento div que é 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 código a seguir ao arquivo Embed.cshtml.

    @model AppOwnsData.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.18.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.

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

Você pode inicializar models 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 código a seguir ao arquivo embed.js.

    $(function () {

    // 1 - Get DOM object for the div that's the report container.
    var reportContainer = document.getElementById("embed-container");

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

    // 3 - Embed the report by using the Power BI JavaScript API.
    var models = window['powerbi-client'].models;

    var config = {
      type: 'report',
      id: reportId,
      embedUrl: embedUrl,
      accessToken: token,
      permissions: models.Permissions.All,
      tokenType: models.TokenType.Embed,
      viewMode: models.ViewMode.View,
      settings: {
        panes: {
          filters: { expanded: false, visible: true },
          pageNavigation: { visible: false }
        }
      }
    };

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

    // 4 - Add logic to resize the embed container on a window resize event.
    var heightBuffer = 12;
    var 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 seguir todas as etapas anteriores, você estará pronto para executar o aplicativo. Tente executar 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.

Importante

Se você usou tokens de avaliação de inserção gratuitos para desenvolvimento, precisará comprar uma capacidade para produção. Até que uma capacidade seja adquirida, a faixa de versão de avaliação gratuita continuará a aparecer na parte superior do relatório inserido.

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

Conteúdo relacionado