Esercitazione: Incorporare un report di Power BI in un'applicazione per l'organizzazione
Questa esercitazione illustra come incorporare un report di Power BI in un'applicazione .NET 5.0, come parte della soluzione incorporamento per l'organizzazione (nota anche come dati 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 si apprenderà come incorporare:
- Un report di Power BI
- In un incorporamento per l'app dell'organizzazione
- Uso di .NET 5.0
- Con la
Microsoft.Identity.Weblibreria (questa libreria è supportata anche in .NET Core)
Nota
La soluzione completa usata in questa esercitazione è disponibile nel repository GitHub DOTNET5-UserOwnsData-Tutorial .
Prerequisiti
Una licenza power BI Pro o Premium per utente (PPU).
Nota
L'incorporamento per la soluzione dell'organizzazione non è supportato nelle capacità basate su SKU A . Uno SKU A può essere usato solo per la soluzione di incorporamento per i clienti .
Un'area di lavoro di Power BI con un report.
Il proprio tenant di 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). È consigliabile usare uno degli ambienti seguenti:
- 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 di incorporamento per l'organizzazione , seguire questa procedura:
- Configurare l'app Microsoft Entra
- Ottenere i valori dei parametri di incorporamento
- Aggiungere i pacchetti NuGet necessari
- Abilitare l'autenticazione lato server
- Creare il lato client dell'app
- 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:
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 (un utente guest), è necessario modificare il authorityUri parametro.
Client ID
Per ottenere il GUID ID client (noto anche come ID applicazione), seguire questa procedura:
Accedere a Microsoft Azure.
Cercare Registrazioni app e selezionare il collegamento Registrazioni app.
Selezionare l'app Microsoft Entra usata per incorporare il contenuto di Power BI.
Nella sezione Panoramica copiare il GUID ID applicazione (client).
Segreto client
Per ottenere il segreto client, seguire questa procedura:
Accedere a Microsoft Azure.
Cercare Registrazioni app e selezionare il collegamento Registrazioni app.
Selezionare l'app Microsoft Entra usata per incorporare il contenuto di Power BI.
In Gestisci, selezionare Certificati e segreti.
In Segreti client, selezionare Nuovo segreto client.
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.
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:
Accedi al servizio Power BI.
Aprire il report da incorporare.
Copiare il GUID dall'URL. Il GUID è il numero tra /groups/ e /reports/.
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:
Accedi al servizio Power BI.
Aprire il report da incorporare.
Copiare il GUID dall'URL. Il GUID è il numero tra /reports/ e /ReportSection.
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 seguenti all'app:
In VS Code aprire un terminale e digitare 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 -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 è stata usata 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 Microsoft.Identity.Web servizio di autenticazione |
| appsettings.json | 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 frammento di codice seguente al file Startup.cs dell'app.
Nota
Il codice in ConfigureServices esegue diverse operazioni importanti:
- La chiamata a
AddMicrosoftWebAppCallsWebApiconfigura Microsoft Authentication Library per acquisire i token di accesso (token Microsoft Entra). - La chiamata a
AddInMemoryTokenCachesconfigura una cache dei token usata da Microsoft Authentication Library per memorizzare nella cache i token di accesso e i token di aggiornamento in background - La chiamata a
services.AddScoped(typeof(PowerBiServiceApi))configura la classe come classe di servizio che può essere aggiunta ad altre classi usando l'inserimentoPowerBiServiceApidelle 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 appsettings.json file contiene informazioni riservate, ad esempio ID client e segreto client. Per motivi di sicurezza, non è consigliabile mantenere queste informazioni nel file delle impostazioni. Quando si incorpora nell'applicazione, prendere in considerazione un metodo più sicuro, ad esempio Azure Key Vault , per mantenere queste informazioni.
Nel progetto creare un nuovo file e chiamarlo appsettings.json.
Aggiungere il codice seguente a 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": "*" }Compilare i valori dei parametri di incorporamento ottenuti dal passaggio 2 : ottenere i valori dei parametri di incorporamento.
Domain- ID dominio e tenantTenantId- ID dominio e tenantClientId- ID clientClientSecret- Segreto client
Nota
Nel frammento di 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 la programmazione del 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 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 e viene usato per acquisire i token di accesso da Microsoft Entra ID.
Il RequiredScopes campo contiene una matrice di stringhe contenente 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.
Nel progetto dell'app creare una nuova cartella denominata Servizi.
Nella cartella Services creare un nuovo file denominato PowerBiServiceApi.cs.
Aggiungere il codice seguente a 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 PowerBiServiceApi classe come servizio chiamando services.AddScoped nel ConfigureServices metodo . È possibile aggiungere un PowerBiServiceApi parametro 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 div elemento usato come contenitore per il report incorporato e tre script.
Nella cartella Visualizza>home creare un file denominato Embed.cshtml.
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 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.
Nella cartella wwwroot>js creare un file denominato embed.js.
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 sperimentare 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
Commenti e suggerimenti
In arrivo: Nel corso del 2024 verranno ritirati i problemi di GitHub come meccanismo di feedback per il contenuto e verranno sostituiti con un nuovo sistema di feedback. Per altre informazioni, vedi: https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per