Esercitazione: Incorporare un report di Power BI in un'applicazione per i clienti

In questa esercitazione si apprenderà come incorporare un report di Power BI in un'applicazione .NET 5.0, come parte della soluzione embed-for-your-customers (nota anche come app-owns-data). In una soluzione embed-for-your-customers, gli utenti dell'app non devono accedere a Power BI o avere una licenza di Power BI.

In questa esercitazione viene illustrato come incorporare:

Prerequisiti

• Una licenza Power BI Pro o Premium per utente (PPU)

• Un'area di lavoro di Power BI con un report

• Il proprio tenant di Microsoft Entra

• Un'app Microsoft Entra

• Un'app MVC (Model View Controller) di .NET Core 5

• .NET Core 5 SDK o versione successiva

• Un ambiente di sviluppo integrato (IDE, Integrated Development Environment). Si consiglia una delle seguenti IDE:

  • Visual Studio.

  • Visual Studio Code con l'estensione C#

Risorse

In questa esercitazione si userà:

• API report REST di Power BI, per incorporare l'URL e recuperare il token di incorporamento.

• Libreria di autenticazione Web di Microsoft Identity.

• API client di analisi incorporata di Power BI, per incorporare il report.

metodo

Per incorporare contenuto di Power BI in una soluzione embed-for-your-customers, seguire questa procedura:

1. Configurare l'app Microsoft Entra e l'entità servizio.

2. Ottenere i valori dei parametri di incorporamento.

3. Aggiungere i pacchetti NuGet necessari.

4. Abilitare l'autenticazione lato server.

5. Creare il lato client dell'app.

6. Eseguire l'applicazione.

Passaggio 1: Configurare l'app Microsoft Entra e l'entità servizio

In questa esercitazione si usa un'entità servizio per autenticare l'app Web con l'ID Microsoft Entra. È necessaria anche un'app Microsoft Entra, che consente di generare un token Microsoft Entra. Usando il token Microsoft Entra, l'app Web può chiamare le API REST di Power BI e incorporare elementi di Power BI, ad esempio report, dashboard e riquadri.

Seguire le istruzioni dell'entità servizio per creare un'app Microsoft Entra e abilitare l'entità servizio dell'app per usare il contenuto di Power BI.

Passaggio 2 - Ottenere i valori dei parametri di incorporamento

Per incorporare il report, sono necessari i valori seguenti:

• Dominio
• ID tenant
• ID client
• Segreto client
• ID area di lavoro
• ID report

Dominio e ID tenant

Se non si conosce il dominio o l'ID tenant, vedere Trovare l'ID tenant di Microsoft Entra e il nome di dominio primario.

ID client

Per ottenere il GUID dell'ID del client (noto anche come ID dell'applicazione), seguire questa procedura:

1. Accedere a Microsoft Azure.

2. Cercare Registrazioni app e selezionare il collegamento Registrazioni app.

3. Selezionare l'app Microsoft Entra utilizzata per incorporare il contenuto di Power BI.

4. Dalla sezione Panoramica copiare il GUID ID applicazione (client).

Segreto client

Per ottenere il segreto client, seguire questa procedura:

1. Accedere a Microsoft Azure.

2. Cercare Registrazioni app e selezionare il collegamento Registrazioni app.

3. Selezionare l'app Microsoft Entra utilizzata per incorporare il contenuto di Power BI.

4. In Gestisci, selezionare Certificati e segreti.

5. In Segreti client, selezionare Nuovo segreto client.

6. Nella finestra popup Aggiungi un segreto client specificare una descrizione per il segreto dell'applicazione, selezionare la scadenza del segreto dell'applicazione e quindi selezionare Aggiungi.

7. Dalla sezione Segreti client copiare la stringa nella colonna Valore del segreto dell'applicazione appena creato. Il valore del segreto client è l'ID del client.

ID area di lavoro

Per ottenere il GUID dell'ID dell'area di lavoro, seguire questa procedura:

1. Accedi al servizio Power BI.

2. Aprire il report che si vuole incorporare.

3. Copiare il GUID dall'URL. Il GUID è il numero tra /groups/ e /reports/.

   

ID report

Per ottenere il GUID dell'ID del report, seguire questa procedura:

1. Accedi al servizio Power BI.

2. Aprire il report che si vuole incorporare.

3. Copiare il GUID dall'URL. Il GUID è il numero tra /reports/ e /ReportSection.

   

Passaggio 3: Aggiungere i pacchetti NuGet necessari

Prima di iniziare, è necessario aggiungere i pacchetti NuGet Microsoft.Identity.Web e Microsoft.PowerBI.Api all'app.

Aggiungere i pacchetti NuGet necessari all'app:

• In VS Code aprire un terminale e immettere il codice seguente.

• In Visual Studio passare a Strumenti>Gestione pacchetti NuGet>Console di gestione pacchetti e digitare il codice seguente.

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

Passaggio 4: Abilitare l'autenticazione lato server

Attivare l'autenticazione lato server nell'app creando o modificando i file nella tabella seguente.

Configurare il file di avvio per il supporto Microsoft.Identity.Web

Modificare il codice in Startup.cs per inizializzare correttamente il servizio di autenticazione fornito da Microsoft.Identity.Web.

Aggiungere il codice seguente al file Startup.cs dell'app.

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

Creare un file dei dettagli di autenticazione

In questa esercitazione il file di appsettings.json contiene informazioni riservate, ad esempio l'ID client e il segreto client. Per motivi di sicurezza, non è consigliabile conservare queste informazioni nel file delle impostazioni. Quando si incorpora nell'applicazione, prendere in considerazione uno strumento più sicuro, ad esempio Azure Key Vault, per proteggere le informazioni riservate.

1. Nel progetto creare un nuovo file e denominarlo appsettings.json.

2. Aggiungere il codice seguente ad 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. Compilare i valori dei parametri di incorporamento ottenuti dal Passaggio 2: ottenere i valori dei parametri di incorporamento.

   • Domain - Dominio e ID tenant
   • TenantId - Dominio e ID tenant
   • ClientId - ID client
   • ClientSecret - Segreto client

Ottenere il token di accesso di Microsoft Entra e chiamare il servizio Power BI

Per incorporare contenuto di Power BI come report e dashboard, l'app deve ottenere un token Microsoft Entra. Per ottenere il token, è necessario un oggetto di configurazione.

Il codice in questa sezione usa il modello di inserimento delle dipendenze di .NET Core. Quando la classe deve usare un servizio, è possibile aggiungere un parametro del costruttore per tale servizio. Il runtime di .NET Core si occupa del passaggio dell'istanza del servizio in fase di esecuzione. In questo caso, il costruttore inserisce un'istanza del servizio di configurazione .NET Core usando il parametro IConfiguration, usato per recuperare il valore di configurazione PowerBi:ServiceRootUrl da appsettings.json. Il parametro ITokenAcquisition, denominato tokenAcquisition, contiene un riferimento al servizio di autenticazione Microsoft fornito dalla libreria Microsoft.Identity.Web. Il parametro ITokenAcquisition viene usato per acquisire i token di accesso da Microsoft Entra ID.

Il campo RequiredScopes contiene una matrice di stringhe contenente un set di autorizzazioni delegate supportate dall'API del servizio Power BI. Quando l'applicazione chiama attraverso la rete per acquisire un token Microsoft Entra, passa questo set di autorizzazioni delegate in modo che Microsoft Entra ID possa includerle nel token di accesso restituito.

1. Nel progetto dell'app creare una nuova cartella denominata Servizi.

2. Nella cartella Servizi creare un nuovo file denominato PowerBiServiceApi.cs.

3. Aggiungere il codice seguente per 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
               };
           }
   
       }
   }
   

Modificare il file HomeController.cs

In questo esempio di codice si usa l'inserimento delle dipendenze per modificare il file HomeController.cs. Seguendo un passaggio precedente, la classe PowerBiServiceApi come servizio è stata configurata chiamando services.AddScoped nel metodo ConfigureServices. Con questo codice si aggiunge un parametro PowerBiServiceApi al costruttore e il runtime .NET Core crea un'istanza PowerBiServiceApi e la passa al costruttore.

Dalla cartella Controllers aprire il file HomeController.cs e aggiungervi il codice seguente:

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

Passaggio 5: Creare il lato client dell'app

Per l'implementazione lato client, è necessario creare o modificare i file elencati nella tabella seguente:

Creare un contenitore per il report incorporato

In questa esercitazione viene creato il file Embed.cshtml con un elemento div che è un contenitore per il report incorporato e tre script.

1. Nella cartella Visualizza/Home creare un file denominato Embed.cshtml.

2. Aggiungere il codice seguente al file 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>
   }
   

Aggiungere JavaScript sul lato client per incorporare il report

Per incorporare il contenuto di Power BI, è necessario creare un oggetto di configurazione. Per altre informazioni sulla creazione dell'oggetto di configurazione, vedere Incorporare un report.

In questa esercitazione viene creato un file JavaScript denominato embed.js con un oggetto di configurazione per l'incorporamento del report che usa la variabile models.

È possibile inizializzare models usando una chiamata a window['powerbi-client'].models. La variabile models viene usata per impostare i valori di configurazione, ad esempio models.Permissions.All, models.TokenType.Aad e models.ViewMode.View.

La funzione powerbi.embed usa l'oggetto di configurazione models per incorporare il report.

1. Nella cartella wwwroot/js creare un file denominato embed.js.

2. Aggiungere il codice seguente al file 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);
       });
   
     });
   

Passaggio 6: Eseguire l'applicazione

Dopo aver seguito tutti i passaggi precedenti, si è pronti per eseguire l'applicazione. Provare a eseguire l'applicazione e provare a usare il modo in cui è incorporato il report di Power BI. È possibile usare le API client di analisi incorporata di Power BI per migliorare l'app usando le API lato client.

Quando l'app è pronta, è possibile spostare l'app incorporata nell'ambiente di produzione.

Contenuto correlato

• Token dell'applicazione di analisi incorporata
• Spostare l'app incorporata in produzione
• Capacità e SKU per le funzionalità di analisi incorporata di Power BI
• Pianificazione della capacità per le funzionalità di analisi incorporata di Power BI