Tutorial: Einbetten von Power BI-Berichten in eine Anwendung für Ihre Kunden
In diesem Tutorial erfahren Sie, wie Sie einen Power BI-Bericht als Teil der Lösung embed-for-your-customers (auch als App-owns-data bezeichnet) in eine .NET 5.0-Anwendung einbetten. In einer Lösung zum Einbetten für Ihre Kunden müssen sich Ihre App-Benutzer nicht bei Power BI anmelden oder über eine Power BI-Lizenz verfügen.
In diesem Tutorial erfahren Sie, wie Sie Folgendes einbetten:
- Ein Power BI-Bericht.
- In einer App zum Einbetten für Ihre Kunden.
- Mithilfe eines Dienstprinzipals.
- Mithilfe von .NET 5.0.
- Mit der
Microsoft.Identity.Web
Bibliothek (diese Bibliothek wird auch in .NET Core unterstützt).
Hinweis
Die vollständige Lösung, die in diesem Tutorial verwendet wird, ist im GitHub-Repository DOTNET5-AppOwnsData-Tutorial verfügbar.
Voraussetzungen
Eine Power BI Pro- oder Premium-Einzelbenutzerlizenz (PPU)
Ein Power BI-Arbeitsbereich mit einem Bericht
Ihr eigener Azure Active Directory-Mandant (Azure AD)
Eine Azure AD-App
Eine .NET Core 5-Modellansichtscontroller-App (MVC)
.NET Core 5 SDK oder höher
Eine integrierte Entwicklungsumgebung (IDE). Es wird eine der folgenden IDEs empfohlen:
Ressourcen
In diesem Tutorial verwenden Sie Folgendes:
Power BI-REST-Berichts-API, um die URL einzubetten und das Einbettungstoken abzurufen.
Power BI Embedded Analytics-Client-APIs, um den Bericht einzubetten.
Methode
Führen Sie die folgenden Schritte aus, um Power BI-Inhalte in eine Lösung zum Einbetten für Ihre Kunden einzubetten:
Schritt 1: Konfigurieren Sie Ihre Azure AD-App und den Dienstprinzipal
In diesem Tutorial verwenden Sie einen Dienstprinzipal, um Ihre Web-App bei Azure AD zu authentifizieren. Außerdem benötigen Sie eine Azure AD-App, die das Generieren eines Azure AD-Tokens ermöglicht. Mithilfe des Azure AD-Tokens kann Ihre Web-App Power BI-REST-APIs aufrufen und Power BI-Elemente wie Berichte, Dashboards und Kacheln einbetten.
Befolgen Sie die Dienstprinzipalanweisungen , um eine Azure AD-App zu erstellen und den Dienstprinzipal der App für die Arbeit mit Ihren Power BI-Inhalten zu aktivieren.
Schritt 2: Abrufen der Werte für den Einbettungsparameter
Zum Einbetten des Berichts benötigen Sie die folgenden Werte:
Domäne und Mandanten-ID
Wenn Sie Ihre Domäne oder Ihre Mandanten-ID nicht kennen, lesen Sie Suchen der Microsoft Azure AD Mandanten-ID und des primären Domänennamens.
Hinweis
Zum Einbetten von Inhalten für einen Benutzer auf einem anderen Mandanten (Gastbenutzer) müssen Sie den authorityUri
Parameter anpassen.
Client-ID
Gehen Sie wie folgt vor, um den eindeutigen Bezeichner der Client-ID (auch als Anwendungs-ID bezeichnet) abzurufen:
Melden Sie sich bei Microsoft Azure an.
Suchen Sie nach App-Registrierungen, und wählen Sie den Link App-Registrierungen aus.
Wählen Sie die Azure AD-App aus, die Sie zum Einbetten von Power BI-Inhalten verwenden.
Kopieren Sie im Abschnitt Übersicht den eindeutigen Bezeichner Anwendungs-ID (Client) .
Geheimer Clientschlüssel
Gehen Sie wie folgt vor, um den geheimen Clientschlüssel abzurufen:
Melden Sie sich bei Microsoft Azure an.
Suchen Sie nach App-Registrierungen, und wählen Sie den Link App-Registrierungen aus.
Wählen Sie die Azure AD-App aus, die Sie zum Einbetten von Power BI-Inhalten verwenden.
Wählen Sie unter Verwalten die Option Zertifikate und Geheimnisse aus.
Wählen Sie unter Geheime Clientschlüssel die Option Neuer geheimer Clientschlüssel.
Geben Sie im Popupfenster Geheimen Clientschlüssel hinzufügen eine Beschreibung für den geheimen Anwendungsschlüssel ein, wählen Sie für den geheimen Anwendungsschlüssel ein Ablaufdatum aus, und klicken Sie auf Hinzufügen.
Kopieren Sie im Abschnitt Geheime Clientschlüssel die Zeichenfolge in der Spalte Wert des neu erstellten geheimen Anwendungsschlüssels. Der Wert des geheimen Clientschlüssels ist die Client-ID.
Hinweis
Stellen Sie sicher, dass Sie den Wert des geheimen Clientschlüssels kopieren, wenn er zum ersten Mal angezeigt wird. Wenn Sie diese Seite verlassen, wird der geheime Clientschlüssel ausgeblendet, und Sie können den Wert nicht mehr abrufen.
Arbeitsbereichs-ID
Gehen Sie wie folgt vor, um den eindeutigen Bezeichner der Arbeitsbereichs-ID abzurufen:
Melden Sie sich beim Power BI-Dienst an.
Öffnen Sie den Bericht, den Sie einbetten möchten.
Kopieren Sie den eindeutigen Bezeichner aus der URL. Der eindeutige Bezeichner ist die Zahl zwischen /groups/ und /reports/ .
Hinweis
Zum programmgesteuerten Abrufen der Arbeitsbereichs-ID verwenden Sie die Gruppen abrufen-API.
Berichts-ID
Gehen Sie wie folgt vor, um den eindeutigen Bezeichner der Berichts-ID abzurufen:
Melden Sie sich beim Power BI-Dienst an.
Öffnen Sie den Bericht, den Sie einbetten möchten.
Kopieren Sie den eindeutigen Bezeichner aus der URL. Der eindeutige Bezeichner ist die Zahl zwischen /reports/ und /ReportSection/ .
Hinweis
Zum programmgesteuerten Abrufen der Berichts-ID verwenden Sie die Berichte in Gruppe abrufen-API.
Schritt 3: Hinzufügen der erforderlichen NuGet-Pakete
Bevor Sie beginnen können, müssen Sie der App die Microsoft.Identity.Web
NuGet-Pakete und Microsoft.PowerBI.Api
hinzufügen.
Fügen Sie Der App die erforderlichen NuGet-Pakete hinzu:
Öffnen Sie in VS Code ein Terminal, und geben Sie den folgenden Code ein.
Navigieren Sie in Visual Studio zu Extras> NuGet-Paket-Manager-Paket-Manager-Paket-Manager-Konsole>, und geben Sie den folgenden Code ein.
dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api
Schritt 4: Aktivieren der serverseitigen Authentifizierung
Aktivieren Sie die serverseitige Authentifizierung in Ihrer App, indem Sie die Dateien in der folgenden Tabelle erstellen oder ändern.
Datei | Zweck |
---|---|
Startup.cs | Initialisieren des Microsoft.Identity.Web -Authentifizierungsdiensts |
appsettings.json | Konfigurieren von Authentifizierungsdetails |
PowerBiServiceApi.cs | Abrufen des Azure AD-Tokens und Einbetten von Metadaten |
HomeController.cs | Übergeben von Einbettungsdaten als Modell an die Ansicht |
Konfigurieren Ihrer Startdatei für die Unterstützung von Microsoft.Identity.Web
Ändern Sie den Code in Startup.cs, um den von Microsoft.Identity.Web
bereitgestellten Authentifizierungsdienst ordnungsgemäß zu initialisieren.
Fügen Sie der Datei Startup.cs Ihrer App den folgenden Code hinzu.
Hinweis
Der Code in ConfigureServices
vollbringt mehrere wichtige Dinge:
- Durch den Aufruf von
AddMicrosoftWebAppCallsWebApi
wird die Microsoft-Authentifizierungsbibliothek für den Abruf von Zugriffstoken (Azure AD Token) konfiguriert. - Der Aufruf von konfiguriert
AddInMemoryTokenCaches
einen Tokencache, den die Microsoft Authentifizierungsbibliothek verwendet, um Zugriffstoken zwischenzuspeichern und Token im Hintergrund zu aktualisieren. - Der Aufruf von konfiguriert
services.AddScoped(typeof(PowerBiServiceApi))
diePowerBiServiceApi
-Klasse als Dienstklasse, die mithilfe der Abhängigkeitsinjektion anderen Klassen hinzugefügt werden kann.
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();
});
}
}
}
Erstellen einer Datei mit Authentifizierungsdetails
In diesem Tutorial enthält die Datei appsettings.json vertrauliche Informationen wie die Client-ID und den geheimen Clientschlüssel. Aus Sicherheitsgründen wird davon abgeraten, diese Informationen in der Einstellungsdatei zu speichern. Ziehen Sie beim Einbetten in Ihre Anwendung ein sichereres Tool in Betracht, z. B. Azure Key Vault, um vertrauliche Informationen zu schützen.
Erstellen Sie in Ihrem Projekt eine neue Datei, und nennen Sie sie appsettings.json.
Fügen Sie appsettings.json den folgenden Code hinzu:
{ "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": "*" }
Setzen Sie die Werte für den Einbettungsparameter ein, die Sie in Schritt 2: Abrufen der Werte für den Einbettungsparameter erhalten haben.
Domain
- Domäne und Mandanten-IDTenantId
- Domäne und Mandanten-IDClientId
- Client-IDClientSecret
- Geheimer Clientschlüssel
Hinweis
Im vorherigen Code wird der PowerBi:ServiceRootUrl
Parameter als benutzerdefinierter Konfigurationswert hinzugefügt, um die Basis-URL dem Power BI-Dienst nachzuverfolgen. Wenn Sie mit dem Power BI-Dienst in der Microsoft öffentlichen Cloud programmieren, lautet https://api.powerbi.com/
die URL . Die Stamm-URL für die Power BI-Dienst unterscheidet sich jedoch in anderen Clouds, z. B. in der Government Cloud. Daher wird der benutzerdefinierte Konfigurationswert als Projektkonfigurationswert gespeichert, sodass Sie ihn bei Bedarf ändern können.
Rufen Sie das Azure AD-Zugriffstoken ab, und rufen Sie die Power BI-Dienst auf.
Um Power BI-Inhalte wie Berichte und Dashboards einzubetten, muss Ihre App ein Azure AD-Token abrufen. Zum Abrufen des Tokens benötigen Sie ein Konfigurationsobjekt.
Der Code in diesem Abschnitt verwendet das .NET Core-Abhängigkeitseinschleusungsmuster. Wenn Ihre Klasse einen Dienst verwenden muss, können Sie einen Konstruktorparameter für diesen Dienst hinzufügen. Die .NET Core-Runtime kümmert sich um das Übergeben der Dienstinstanz zur Laufzeit. In diesem Fall fügt der Konstruktor eine Instanz des .NET Core-Konfigurationsdiensts mithilfe des IConfiguration
Parameters ein, der zum Abrufen des PowerBi:ServiceRootUrl
Konfigurationswerts aus appsettings.json verwendet wird. Der ITokenAcquisition
Parameter mit dem Namen tokenAcquisition
enthält einen Verweis auf den von der Microsoft.Identity.Web
Bibliothek bereitgestellten Microsoft Authentifizierungsdienst. Der ITokenAcquisition
Parameter wird verwendet, um Zugriffstoken aus Azure AD abzurufen.
Das RequiredScopes
Feld enthält ein Zeichenfolgenarray, das einen Satz delegierter Berechtigungen enthält, die von der Power BI-Dienst-API unterstützt werden. Wenn Ihre Anwendung über das Netzwerk aufruft, um ein Azure AD-Token abzurufen, übergibt sie diesen Satz delegierter Berechtigungen, sodass Azure AD sie in das zurückgegebene Zugriffstoken einschließen kann.
Hinweis
Vergewissern Sie sich, dass Ihre Azure AD-App mit den Bereichen konfiguriert ist, die für Ihre Web-App erforderlich sind. Weitere Informationen finden Sie unter Ändern der Berechtigungen Ihrer Azure AD-App.
Erstellen Sie im Projekt Ihrer App einen neuen Ordner mit dem Namen Services (Dienste).
Erstellen Sie im Ordner Services eine neue Datei mit dem Titel PowerBiServiceApi.cs.
Fügen Sie PowerBiServiceApi.cs den folgenden Code hinzu.
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 }; } } }
Ändern der HomeController.cs-Datei
In diesem Codebeispiel verwenden Sie die Abhängigkeitsinjektion, um die Datei HomeController.cs zu ändern. Indem Sie einen vorherigen Schritt ausführen, haben Sie die PowerBiServiceApi
-Klasse als Dienst konfiguriert, indem Sie die ConfigureServices
-Methode aufrufenservices.AddScoped
. Mit diesem Code fügen Sie dem Konstruktor einen PowerBiServiceApi
Parameter hinzu, und die .NET Core-Runtime erstellt eine PowerBiServiceApi
Instanz und übergibt sie an den Konstruktor.
Öffnen Sie im Ordner Controller die Datei HomeController.cs , und fügen Sie ihr den folgenden Code hinzu:
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 });
}
}
}
Schritt 5: Erstellen der Clientseite Ihrer App
Für die clientseitige Implementierung müssen Sie die Dateien erstellen oder ändern, die in der folgenden Tabelle aufgeführt sind:
Datei | Zweck |
---|---|
embed.js | Enthält den clientseitigen JavaScript-Code |
Embed.cshtml | Enthält das Dokumentobjektmodell (DOM) Ihrer App und ein DIV zum Einbetten des Berichts. |
Erstellen eines Containers für ihren eingebetteten Bericht
In diesem Tutorial erstellen Sie die Datei Embed.cshtml mit einem div
Element, das einen Container für Ihren eingebetteten Bericht darstellt, und drei Skripts.
Erstellen Sie im Ordner Ansicht/Start eine Datei mit dem Namen Embed.cshtml.
Fügen Sie der Datei Embed.cshtml den folgenden Code hinzu.
@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> }
Hinzufügen von clientseitigem JavaScript zum Einbetten des Berichts
Zum Einbetten von Power BI-Inhalten müssen Sie ein Konfigurationsobjekt erstellen. Weitere Informationen zum Erstellen des Konfigurationsobjekts finden Sie unter Einbetten eines Berichts.
In diesem Tutorial erstellen Sie eine JavaScript-Datei namens embed.js mit einem Konfigurationsobjekt zum Einbetten Ihres Berichts, das die Variable models
verwendet.
Sie können initialisieren, models
indem Sie einen Aufruf von verwenden window['powerbi-client'].models
. Die models
Variable wird verwendet, um Konfigurationswerte wie models.Permissions.All
, models.TokenType.Aad
und models.ViewMode.View
festzulegen.
Die Funktion powerbi.embed
verwendet das models
-Konfigurationsobjekt zum Einbetten des Berichts.
Erstellen Sie im Ordner wwwroot/js eine Datei mit dem Namen embed.js.
Fügen Sie der dateiembed.js den folgenden Code hinzu.
$(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); }); });
Schritt 6: Ausführen der Anwendung
Nachdem Sie alle vorherigen Schritte ausgeführt haben, können Sie Ihre Anwendung ausführen. Versuchen Sie, Ihre Anwendung auszuführen, und experimentieren Sie mit der Einbettung Ihres Power BI-Berichts. Sie können die Power BI Embedded Analytics-Client-APIs verwenden, um Ihre App mithilfe clientseitiger APIs zu verbessern.
Wichtig
Wenn Sie kostenlose Testtoken für die Entwicklung verwendet haben, müssen Sie für die Produktion Kapazitäten erwerben. Bis eine Kapazität erworben wurde, wird das Banner der Kostenlosen Testversion weiterhin oben im eingebetteten Bericht angezeigt.
Wenn Ihre App bereit ist, können Sie Ihre eingebettete App in die Produktionsumgebung verschieben.