Partekatu honen bidez:

Tutorial: Inserción de un informe de Power BI en una aplicación para los clientes

  • Artikulua

En este tutorial, descubrirá cómo insertar un informe de Power BI en una aplicación de .NET 5.0, como parte de la solución de inserción para los clientes (también conocida como datos en posesión de la aplicación). En una solución de inserción para los clientes, los usuarios de la aplicación no necesitan iniciar sesión en Power BI ni disponer de una licencia de Power BI.

En este tutorial, obtendrá información sobre cómo insertar lo siguiente:

  • Un informe de Power BI.
  • En una aplicación de inserción para los clientes.
  • Mediante una entidad de servicio.
  • Mediante .NET 5.0.
  • Con la biblioteca Microsoft.Identity.Web (esta biblioteca también se admite en .NET Core).

Nota

La solución completa que se usa en este tutorial está disponible en el repositorio de GitHub DOTNET5-AppOwnsData-Tutorial.

Requisitos previos

Recursos

En este tutorial, utilizará:

Método

Para insertar contenido de Power BI en una solución de inserción para los clientes, siga estos pasos:

  1. Configure la aplicación y la entidad de servicio de Microsoft Entra.

  2. Obtener los valores de parámetro de la inserción

  3. Agregar los paquetes NuGet necesarios.

  4. Habilitar la autenticación del lado servidor

  5. Compilar el lado cliente de la aplicación

  6. Ejecutar la aplicación.

Paso 1: Configurar la aplicación y la entidad de servicio de Microsoft Entra

En este tutorial, se utiliza una entidad de servicio para autenticar una aplicación web en Microsoft Entra ID. También necesita una aplicación de Microsoft Entra, lo que permite generar un token de Microsoft Entra. El uso del token de Microsoft Entra, permite a la aplicación web llamar a las API REST de Power BI e insertar elementos de Power BI, tales como informes, paneles e iconos.

Siga las instrucciones de la entidad de servicio para crear una aplicación de Microsoft Entra y habilitar la entidad de servicio de la aplicación para que funcione con el contenido de Power BI.

Paso 2: Obtener los valores de parámetro de la inserción

Para insertar el informe, necesita los valores siguientes:

Id. de dominio e inquilino

Si no sabe cuál es el identificador de dominio o de inquilino, consulte Búsqueda del nombre de dominio principal y del identificador del inquilino de Microsoft Entra.

Nota:

Si desea insertar contenido para un usuario en un inquilino diferente (usuario invitado), debe ajustar el parámetro authorityUri.

Id. de cliente

Para obtener el GUID del identificador de cliente (también conocido como id. de la aplicación), haga lo siguiente:

  1. Inicie sesión en Microsoft Azure.

  2. Busque Registros de aplicaciones y seleccione el vínculo Registros de aplicaciones.

  3. Seleccione la aplicación de Microsoft Entra que usa para insertar el contenido de Power BI.

  4. En la sección Información general, copie el GUID del identificador de la aplicación (cliente) .

Secreto del cliente

Para obtener el secreto de cliente, haga lo siguiente:

  1. Inicie sesión en Microsoft Azure.

  2. Busque Registros de aplicaciones y seleccione el vínculo Registros de aplicaciones.

  3. Seleccione la aplicación de Microsoft Entra que usa para insertar el contenido de Power BI.

  4. En Administrar, seleccione Certificados y secretos.

  5. En Secretos de cliente, seleccione Nuevo secreto de cliente.

  6. En la ventana emergente Agregar un secreto de cliente, escriba una descripción del secreto de la aplicación, seleccione cuándo expira el secreto de la aplicación y seleccione Agregar.

  7. En la sección Secretos de cliente, copie la cadena de la columna Valor del secreto de aplicación recién creado. El valor del secreto de cliente es el identificador de cliente.

Nota

Asegúrese de copiar el valor de secreto de cliente cuando aparezca por primera vez. Después de salir de esta página, el secreto de cliente se ocultará y no podrá recuperar su valor.

Id. del área de trabajo

Para obtener el GUID del identificador del área de trabajo, haga lo siguiente:

  1. Inicie sesión en el servicio Power BI.

  2. Abra el informe que quiera insertar.

  3. Copie el GUID de la dirección URL. El GUID es el número que hay entre /groups/ y /reports/ .

    Captura de pantalla que muestra el GUID del identificador del área de trabajo en la dirección URL de servicio Power BI

Nota:

Para obtener el id. del área de trabajo mediante programación, use la API Get Groups.

Report ID (Id. de informe)

Para obtener el GUID del id. del informe, haga lo siguiente:

  1. Inicie sesión en el servicio Power BI.

  2. Abra el informe que quiera insertar.

  3. Copie el GUID de la dirección URL. El GUID es el número que hay entre /reports/ y /ReportSection.

    Captura de pantalla que muestra el GUID del identificador del informe en la dirección URL del servicio Power BI

Nota

Para obtener el identificador de informe mediante programación, use la API Get Reports In Group.

Paso 3: Agregar los paquetes NuGet necesarios

Para empezar, necesita agregar los paquetes NuGet Microsoft.Identity.Web y Microsoft.PowerBI.Api a la aplicación.

Agregue los paquetes NuGet necesarios a su aplicación:

  • En VS Code, abra un terminal y escriba el código siguiente.

  • En Visual Studio, vaya a Herramientas>Administrador de paquetes NuGet>Consola del Administrador de paquetes y escriba el código siguiente.

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api

Paso 4: Habilitar la autenticación del lado servidor

Active la autenticación del lado servidor en la aplicación mediante la creación o modificación de los archivos de la tabla siguiente.

Archivo Uso
Startup.cs Inicializar el servicio de autenticación Microsoft.Identity.Web
appsettings.json Configuración de los detalles de autenticación
PowerBiServiceApi.cs Obtener el token de Microsoft Entra y los metadatos de inserción
HomeController.cs Pasar los datos de inserción como modelo a la vista

Configuración del archivo de inicio para admitir Microsoft.Identity.Web

Modifique el código de Startup.cs para inicializar correctamente el servicio de autenticación que proporciona Microsoft.Identity.Web.

Agregue el código siguiente al archivo Startup.cs de la aplicación.

Nota

El código de ConfigureServices logra varias cosas importantes:

  1. La llamada a AddMicrosoftWebAppCallsWebApi configura MSAL para que adquiera tokens de acceso (tokens de Microsoft Entra).
  2. La llamada a AddInMemoryTokenCaches configura una caché de tokens que MSAL usa para almacenar en caché los tokens de acceso y actualizar los tokens en segundo plano.
  3. La llamada a services.AddScoped(typeof(PowerBiServiceApi)) configura la clase PowerBiServiceApi como una clase de servicio que se puede agregar a otras clases mediante la inserción de dependencias.
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();
            });
        }
    }
}

Creación de un archivo de detalles de autenticación

En este tutorial, el archivo appsettings.json contiene información confidencial, como el identificador de cliente y el secreto del cliente. Por motivos de seguridad, no se recomienda mantener esta información en el archivo de configuración. Al realizar una inserción en la aplicación, considere la posibilidad de usar una herramienta más segura, como Azure Key Vault, para proteger la información confidencial.

  1. En el proyecto, cree un archivo y asígnele el nombre appsettings.json.

  2. Agregue el código siguiente 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. Rellene los valores de parámetro de inserción obtenidos en Paso 2: Obtener los valores de parámetro de la inserción.

Nota

En el código anterior, el parámetro PowerBi:ServiceRootUrl se agrega como un valor de configuración personalizado para realizar el seguimiento de la dirección URL base al servicio Power BI. Cuando programa con el servicio Power BI en la nube pública de Microsoft, la dirección URL es https://api.powerbi.com/. Sin embargo, la dirección URL raíz del servicio Power BI es diferente en otras nubes, como la nube gubernamental. Por lo tanto, el valor de configuración personalizado se almacena como un valor de configuración del proyecto, por lo que puede cambiarlo cuando sea necesario.

Obtención del token de acceso de Microsoft Entra y llamada al servicio Power BI

Para insertar contenido de Power BI, como informes y paneles, la aplicación debe obtener un token de Microsoft Entra. Para obtener el token, necesita un objeto de configuración.

El código de esta sección usa el patrón de inserción de dependencias de .NET Core. Cuando la clase necesita usar un servicio, puede agregar un parámetro de constructor para ese servicio. El entorno de ejecución de .NET Core se encarga de pasar la instancia de servicio en tiempo de ejecución. En este caso, el constructor inyecta una instancia del servicio de configuración de .NET Core mediante el parámetro IConfiguration, que se utiliza para recuperar el valor de configuración PowerBi:ServiceRootUrl de appsettings.json. El parámetro ITokenAcquisition, que se denomina tokenAcquisition, contiene una referencia al servicio de autenticación de Microsoft que proporciona la biblioteca Microsoft.Identity.Web. El parámetro ITokenAcquisition se utiliza para adquirir tokens de acceso de Microsoft Entra ID.

El campo RequiredScopes contiene una matriz de cadenas que incluye un conjunto de permisos delegados compatible con la API del servicio Power BI. Cuando la aplicación realiza una llamada a través de la red para adquirir un token de Microsoft Entra, pasa este conjunto de permisos delegados para que Microsoft Entra ID pueda incluirlos en el token de acceso que devuelve.

Nota:

Compruebe que la aplicación de Azure AD está configurada con los ámbitos que requiere su aplicación web. Para más información, consulte Cambio de los permisos de una aplicación de Microsoft Entra.

  1. En el proyecto de la aplicación, cree una carpeta con el nombre Services.

  2. En la carpeta Services, cree un archivo con el nombre PowerBiServiceApi.cs.

  3. Agregue el código siguiente 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
            };
        }

    }
}

Modificación del archivo HomeController.cs

En este ejemplo de código, usa la inserción de dependencias para modificar el archivo HomeController.cs. Siguiendo un paso anterior, ha configurado la clase PowerBiServiceApi como servicio llamando a services.AddScoped en el método ConfigureServices. Con este código, agrega un parámetro PowerBiServiceApi al constructor, y el entorno de ejecución de .NET Core crea una instancia PowerBiServiceApi y la pasa al constructor.

En la carpeta Controllers, abra el archivo HomeController.cs y agréguele el código siguiente:

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 });
        }
    }
}

Paso 5: Compilar el lado cliente de la aplicación

Para la implementación en el lado cliente, debe crear o modificar los archivos que aparecen en la tabla siguiente:

Archivo Uso
embed.js Contiene el código JavaScript del lado cliente.
Embed.cshtml Contiene el modelo de objetos de documento (DOM) de la aplicación y un elemento DIV para insertar el informe.

Creación de un contenedor para el informe insertado

En este tutorial, crea el archivo Embed.cshtml, que tiene un elemento div que es un contenedor para el informe insertado y tres scripts.

  1. En la carpeta View/Home, cree un archivo denominado Embed.cshtml.

  2. Agregue el código siguiente al archivo 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>
}

Incorporación de JavaScript del lado cliente para insertar el informe

Para insertar contenido de Power BI, debe crear un objeto de configuración. Para obtener más información sobre cómo crear el objeto de configuración, vea Inserción de un informe.

En este tutorial, crea un archivo JavaScript denominado embed.js con un objeto de configuración para insertar el informe que utiliza la variable models.

Puede inicializar models mediante una llamada a window['powerbi-client'].models. La variable models se usa para establecer valores de configuración, como models.Permissions.All, models.TokenType.Aad y models.ViewMode.View.

La función powerbi.embed usa el objeto de configuración models para insertar el informe.

  1. En la carpeta wwwroot/js, cree un archivo denominado embed.js.

  2. Agregue el código siguiente al archivo 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);
    });

  });

Paso 6: Ejecutar la aplicación

Después de seguir todos los pasos anteriores, está listo para ejecutar la aplicación. Intente ejecutar la aplicación y experimente con la forma en que se inserta el informe de Power BI. Puede usar las API de cliente de análisis integrado de Power BI para mejorar la aplicación mediante las API del lado cliente.

Importante

Si ha usado tokens de prueba de inserción gratuitos para el desarrollo, deberá comprar una capacidad para producción. Hasta que compre una capacidad, el banner Versión de evaluación gratuita seguirá apareciendo en la parte superior del informe insertado.

Cuando esté lista, puede mover la aplicación insertada a producción.

Contenido relacionado