Condividi tramite

Esercitazione: Incorporare un report di Power BI in un'applicazione per l'organizzazione

  • Articolo

Questa esercitazione illustra come incorporare un report di Power BI in un'applicazione .NET 5.0, come parte della soluzione di incorporamento per l'organizzazione (nota anche come i dati sono di proprietà dell'utente). In una soluzione di incorporamento per l'organizzazione, gli utenti dell'app devono eseguire l'autenticazione con Power BI con le proprie credenziali.

In questa esercitazione viene illustrato come incorporare:

  • Report di Power BI
  • In un'app con incorporamento per l'organizzazione
  • Usando .NET 5.0
  • Con la libreria Microsoft.Identity.Web (questa libreria è supportata anche in .NET Core)

Nota

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

Prerequisiti

Risorse

In questa esercitazione si userà:

metodo

Per incorporare contenuto di Power BI in una soluzione di incorporamento per l'organizzazione, seguire questa procedura:

  1. Configurare l'app Microsoft Entra
  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

Quando l'app Web chiama Power BI, è necessario un token Microsoft Entra per chiamare le API REST di Power BI e incorporare elementi di Power BI, ad esempio report, dashboard o riquadri.

Se non si ha un'app Microsoft Entra, crearne una usando le istruzioni riportate in Registrare un'applicazione Microsoft Entra da usare con Power BI.

Per configurare l'app Microsoft Entra, seguire le istruzioni riportate in Configurare l'app Microsoft Entra.

Passaggio 2 - Ottenere i valori dei parametri di incorporamento

Per incorporare il report, sono necessari i valori seguenti:

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.

Nota

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

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.

Nota

Accertarsi di copiare il valore del segreto client quando compare per la prima volta. Dopo la chiusura di 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 che si vuole incorporare.

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

    Screenshot che mostra il GUID dell'ID dell'area di lavoro nell'URL di servizio Power BI

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

    Screenshot che mostra il GUID dell'ID del report nell'URL del servizio Power BI

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 pacchetti NuGet Microsoft.Identity.Web e Microsoft.PowerBI.Api all'app.

Aggiungere i pacchetti NuGet seguenti all'app:

  • In VS Code aprire un terminale e digitare 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 -v 0.3.0-preview
dotnet add package Microsoft.Identity.Web.UI -v 0.3.0-preview
dotnet add package Microsoft.PowerBI.Api

Se l'app ha usato Microsoft.AspNetCore in precedenza per l'autenticazione, rimuovere questo pacchetto dal progetto digitando:

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

Passaggio 4: Abilitare l'autenticazione lato server

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

file Utilizzo
Startup.cs Inizializzare il servizio di autenticazione Microsoft.Identity.Web
appsettings.json Dettagli di autenticazione
PowerBiServiceApi.cs Ottenere il token di Microsoft Entra e l'incorporamento dei metadati
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 frammento di 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 che Microsoft Authentication Library userà 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 classe PowerBiServiceApi come classe di servizio che può essere aggiunta ad altre classi usando l'inserimento delle dipendenze.
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();

    }
  }
}

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 un metodo più sicuro, ad esempio Azure Key Vault, per conservare queste informazioni.

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

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

Nota

Nel frammento di codice precedente il parametro PowerBi:ServiceRootUrl 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 sarà diverso in altri cloud, ad esempio il cloud per enti pubblici. Pertanto, questo valore viene archiviato come valore di configurazione del progetto in modo che sia facile da modificare quando necessario.

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

Per incorporare contenuto di Power BI (ad esempio 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 e 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 e 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.

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 Servizi creare un nuovo file denominato PowerBiServiceApi.cs.

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

 }

}

Modificare il file HomeController.cs

In questo esempio di codice si usa l'inserimento delle dipendenze. Durante la registrazione della classe PowerBiServiceApi come servizio chiamando services.AddScoped nel metodo ConfigureServices. È possibile aggiungere un parametro PowerBiServiceApi al costruttore e il runtime di .NET Core si occupa della creazione di un'istanza PowerBiServiceApi e del passaggio al costruttore.

Dalla cartella Controllers aprire il file HomeController.cs e aggiungerlo al frammento di codice seguente:

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

Passaggio 5: Creare il lato client dell'app

Per l'implementazione lato client, è necessario creare o modificare i file 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

Creare il file Embed.cshtml con un elemento div usato come contenitore per il report incorporato e tre script.

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

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

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 sezione viene creato un file JavaScript denominato embed.js con un oggetto di configurazione per l'incorporamento del report usando la variabile models.

models viene inizializzato 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 frammento di codice seguente al file embed.js.

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

});

Passaggio 6: Eseguire l'applicazione

Dopo aver apportato tutte le modifiche elencate in questa esercitazione, si è pronti per eseguire l'applicazione. 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