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

  • Articolo

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 soluzione app-owns-data). In una soluzione di incorporamento per i clienti, gli utenti dell'app non devono accedere a Power BI o avere una licenza di Power BI.

In questa esercitazione si apprenderà come incorporare:

  • Report di Power BI.
  • In un'app embed-for-your-customers.
  • Usando un'entità servizio.
  • Usando .NET 5.0.
  • Con la Microsoft.Identity.Web libreria (questa libreria è supportata anche in .NET Core).

Nota

La soluzione completa usata in questa esercitazione è disponibile nel repository GitHub DOTNET5-AppOwnsData-Tutorial .

Prerequisiti

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:

ID dominio e 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.

Nota

Per incorporare il contenuto per un utente in un tenant diverso (utente guest), è necessario modificare il authorityUri parametro.

Client ID

Per ottenere il GUID ID client (noto anche come ID 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 usata per incorporare il contenuto di Power BI.

  4. Nella 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 usata 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 quando scade il segreto dell'applicazione e selezionare Aggiungi.

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

Nota

Assicurarsi di copiare il valore del segreto client quando viene visualizzato per la prima volta. Dopo lo spostamento da questa pagina, il segreto client verrà nascosto e non sarà possibile recuperarne il valore.

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 da incorporare.

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

    A screenshot showing workspace ID GUID in the Power B I service U R L

Nota

Per ottenere l'ID dell'area di lavoro a livello di codice, usare l'API Recupera gruppi .

ID report

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

  1. Accedi al servizio Power BI.

  2. Aprire il report da incorporare.

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

    A screenshot showing report ID GUID in the Power B I service U R L

Nota

Per ottenere l'ID report a livello di codice, usare l'API Recupera report in gruppo .

Passaggio 3: Aggiungere i pacchetti NuGet necessari

Prima di iniziare, è necessario aggiungere i Microsoft.Identity.Webpacchetti e Microsoft.PowerBI.Api NuGet 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>NuGet Gestione pacchetti> Gestione pacchetti Console 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.

file Utilizzo
Startup.cs Inizializzare il Microsoft.Identity.Web servizio di autenticazione
appsettings.json Configurare i dettagli di autenticazione
PowerBiServiceApi.cs Ottenere il token e l'incorporamento dei metadati di Microsoft Entra
HomeController.cs Passare i dati di incorporamento come modello alla visualizzazione

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.

Nota

Il codice in ConfigureServices esegue diverse operazioni importanti:

  1. La chiamata a AddMicrosoftWebAppCallsWebApi configura Microsoft Authentication Library per acquisire i token di accesso (token Microsoft Entra).
  2. La chiamata a AddInMemoryTokenCaches configura una cache dei token usata da Microsoft Authentication Library per memorizzare nella cache i token di accesso e i token di aggiornamento in background.
  3. La chiamata a services.AddScoped(typeof(PowerBiServiceApi)) configura la PowerBiServiceApi classe come classe di servizio che può essere aggiunta ad altre classi usando l'inserimento delle dipendenze.
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 appsettings.json contiene informazioni riservate, ad esempio ID client e 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 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. Compilare i valori dei parametri di incorporamento ottenuti dal passaggio 2 : ottenere i valori dei parametri di incorporamento.

Nota

Nel codice precedente il PowerBi:ServiceRootUrl parametro viene aggiunto come valore di configurazione personalizzato per tenere traccia dell'URL di base al servizio Power BI. Quando si esegue il programma per il servizio Power BI nel cloud pubblico Microsoft, l'URL è https://api.powerbi.com/. Tuttavia, l'URL radice per il servizio Power BI è diverso in altri cloud, ad esempio il cloud per enti pubblici. Di conseguenza, il valore di configurazione personalizzato viene archiviato come valore di configurazione del progetto, in modo da poterlo modificare in base alle esigenze.

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 IConfiguration parametro , usato per recuperare il PowerBi:ServiceRootUrl valore di configurazione da appsettings.json. Il ITokenAcquisition parametro , denominato tokenAcquisition, contiene un riferimento al servizio di autenticazione Microsoft fornito dalla Microsoft.Identity.Web libreria. Il ITokenAcquisition parametro viene usato per acquisire i token di accesso da Microsoft Entra ID.

Il RequiredScopes campo contiene una matrice di stringhe che contiene un set di autorizzazioni delegate supportate dall'API 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 includerli nel token di accesso restituito.

Nota

Verificare che l'app Microsoft Entra sia configurata con gli ambiti richiesti dall'app Web. Per altre informazioni, vedere Modificare le autorizzazioni dell'app Microsoft Entra.

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

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

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

    }
}

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 PowerBiServiceApi classe come servizio è stata configurata chiamando services.AddScoped nel ConfigureServices metodo . Con questo codice si aggiunge un PowerBiServiceApi parametro 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:

file Utilizzo
embed.js Contiene il codice JavaScript sul lato client
Embed.cshtml Contiene il modello DOM (Document Object Model) dell'app e un DIV per l'incorporamento del report

Creare un contenitore per il report incorporato

In questa esercitazione viene creato il file Embed.cshtml con un div elemento 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 incorporare il report che usa la variabile models.

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

La powerbi.embed funzione usa l'oggetto models di configurazione 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.

Importante

Se sono stati usati token di valutazione gratuiti per lo sviluppo, è necessario acquistare una capacità per la produzione. Fino a quando non viene acquistata una capacità, il banner versione di valutazione gratuita continua a essere visualizzato nella parte superiore del report incorporato.

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 nell'ambiente di produzione

Capacità e SKU nell'analisi incorporata di Power BI

Pianificazione della capacità nell'analisi incorporata di Power BI