Tutorial: Einbetten von Power BI-Berichten in eine Anwendung für Ihre Kunden

In diesem Tutorial erfahren Sie, wie Sie einen Power BI-Bericht im Rahmen von Einbetten für Ihre Kunden (auch bekannt als eine App-Owns-Data-Lösung) in eine .NET 5.0-Anwendung einbetten. Benutzer müssen sich weder bei Power BI anmelden noch über eine Power BI-Lizenz verfügen, um Ihre Lösung des Typs Einbetten für Ihre Kunden verwenden zu können.

In diesem Tutorial lernen Sie, wie Folgendes eingebettet wird:

  • ein Power BI-Bericht
  • in einer App des Typs 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 Projektmappe, die in diesem Tutorial verwendet wird, ist im GitHub-Repository DOTNET5-AppOwnsData-Tutorial verfügbar.

Voraussetzungen

Ressourcen

In diesem Tutorial verwenden Sie diese Ressourcen:

Methode

Führen Sie die folgenden Schritte aus, um Power BI-Inhalte in einer Einbetten für Ihre Kunden-Lösung einzubetten:

  1. Konfigurieren Sie Ihre Azure AD-App und den Dienstprinzipal.

  2. Rufen Sie die Werte für den Einbettungsparameter ab.

  3. Fügen Sie die erforderlichen NuGet-Pakete hinzu.

  4. Aktivieren der serverseitigen Authentifizierung.

  5. Erstellen der Clientseite Ihrer App.

  6. Führen Sie Ihre Anwendung aus.

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, mit der Sie ein Azure AD-Token generieren können. Mit dem Azure AD-Token kann Ihre Web-App Power BI REST-APIs aufrufen und Power BI-Elemente wie Berichte, Dashboards oder Kacheln einbetten.

Befolgen Sie die Anweisungen des Dienstprinzipals, um eine Azure AD-App zu erstellen und dem Dienstprinzipal der App die Arbeit mit Ihren Power BI-Inhalten zu ermöglichen.

Schritt 2: Abrufen der Werte für den Einbettungsparameter

Zum Einbetten Ihres 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 in einem anderen Mandanten (einem 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:

  1. Melden Sie sich bei Microsoft Azure an.

  2. Suchen Sie nach App-Registrierungen, und wählen Sie den Link App-Registrierungen aus.

  3. Wählen Sie die Azure AD-App aus, die Sie zum Einbetten von Power BI-Inhalten verwenden.

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

  1. Melden Sie sich bei Microsoft Azure an.

  2. Suchen Sie nach App-Registrierungen, und wählen Sie den Link App-Registrierungen aus.

  3. Wählen Sie die Azure AD-App aus, die Sie zum Einbetten von Power BI-Inhalten verwenden.

  4. Wählen Sie unter Verwalten die Option Zertifikate und Geheimnisse aus.

  5. Wählen Sie unter Geheime Clientschlüssel die Option Neuer geheimer Clientschlüssel.

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

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

  1. Melden Sie sich beim Power BI-Dienst an.

  2. Öffnen Sie den Bericht, den Sie einbetten möchten.

  3. Kopieren Sie den eindeutigen Bezeichner aus der URL. Der eindeutige Bezeichner ist die Zahl zwischen /groups/ und /reports/ .

    Screenshot: Eindeutiger Bezeichner der Arbeitsbereichs-ID in der URL zum Power BI-Dienst

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:

  1. Melden Sie sich beim Power BI-Dienst an.

  2. Öffnen Sie den Bericht, den Sie einbetten möchten.

  3. Kopieren Sie den eindeutigen Bezeichner aus der URL. Der eindeutige Bezeichner ist die Zahl zwischen /reports/ und /ReportSection/ .

    Screenshot: Eindeutiger Bezeichner der Berichts-ID in der URL zum Power BI-Dienst

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 Ihrer App die NuGet-Pakete Microsoft.Identity.Web und Microsoft.PowerBI.Api hinzufügen.

Fügen Sie Ihrer App die unten aufgeführten NuGet-Pakete hinzu:

  • Öffnen Sie in VS Code ein Terminal, und geben Sie den Code unten ein.

  • Navigieren Sie in Visual Studio zu Tools > NuGet Paket-Manager > Paket-Manager-Konsole, und geben Sie den Code unten 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 Tabelle unten erstellen oder ändern.

Datei Zweck
Startup.cs Initialisieren des Microsoft.Identity.Web-Authentifizierungsdiensts
appsettings.json 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 den Codeausschnitt unten der Datei Startup.cs Ihrer App hinzu.

Hinweis

Der Code in ConfigureServices vollbringt mehrere wichtige Dinge:

  1. Durch den Aufruf von AddMicrosoftWebAppCallsWebApi wird die Microsoft-Authentifizierungsbibliothek für den Abruf von Zugriffstoken (Azure AD Token) konfiguriert.
  2. Durch den Aufruf von AddInMemoryTokenCaches wird ein Tokencache konfiguriert, der von der Microsoft-Authentifizierungsbibliothek für die Zwischenspeicherung von Zugriffstoken und die Aktualisierung von Token hinter den Kulissen verwendet wird.
  3. Der Aufruf von services.AddScoped(typeof(PowerBiServiceApi)) konfiguriert die PowerBiServiceApi-Klasse als Dienstklasse, die anderen Klassen mithilfe von Abhängigkeitseinschleusung 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 may 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. Beim Einbetten in Ihre Anwendung sollten Sie eine sicherere Methode – z. B. Azure Key Vault – für die Aufbewahrung dieser Informationen in Betracht ziehen.

  1. Erstellen Sie in Ihrem Projekt eine neue Datei, und geben Sie ihr den Namen appsettings.json.

  2. 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": "*"
    }
    
  3. Setzen Sie die Werte für den Einbettungsparameter ein, die Sie in Schritt 2: Abrufen der Werte für den Einbettungsparameter erhalten haben.

Hinweis

Im Codeausschnitt oben wird der PowerBi:ServiceRootUrl-Parameter als benutzerdefinierter Konfigurationswert hinzugefügt, um die Basis-URL für den Power BI-Dienst nachzuverfolgen. Wenn Sie mit dem -Power BI-Dienst für die öffentliche Microsoft-Cloud programmieren, lautet die URL https://api.powerbi.com/. Die Stamm-URL für die Power BI-Dienst in anderen Clouds, z. B. die Government Cloud, weicht jedoch ab. Daher wird dieser Wert als Projektkonfigurationswert gespeichert, sodass er bei Bedarf leicht geändert werden kann.

Rufen Sie das Azure AD-Zugriffstoken ab, und rufen Sie die Power BI-Dienst auf.

Zum Einbetten von Power BI-Inhalten (wie etwa Berichten und Dashboards) 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, dann übernimmt die .NET Core-Runtime die Übergabe der Dienstinstanz zur Laufzeit. In diesem Fall schleust der Konstruktor eine Instanz des .NET Core-Konfigurationsdiensts mithilfe des IConfiguration-Parameters ein, der verwendet wird, um den PowerBi:ServiceRootUrl-Konfigurationswert aus appsettings.json abzurufen. Der ITokenAcquisition-Parameter mit dem Namen tokenAcquisition enthält einen Verweis auf den Microsoft-Authentifizierungsdienst, der von der Microsoft.Identity.Web-Bibliothek bereitgestellt und zum Abrufen von Zugriffstoken bei Azure AD verwendet wird.

Das RequiredScopes-Feld enthält einen Zeichenfolgenarray, der eine Reihe von delegierten Berechtigungen enthält, die von der Power BI-Dienst-API unterstützt werden. Bei Aufrufen Ihrer Anwendung über das Netzwerk zum Abrufen eines Azure AD-Tokens ü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.

  1. Erstellen Sie im Projekt Ihrer App einen neuen Ordner mit dem Namen Services (Dienste).

  2. Erstellen Sie im Ordner Services eine neue Datei mit dem Titel PowerBiServiceApi.cs.

  3. 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 Abhängigkeitseinschleusung. Sie haben die Klasse PowerBiServiceApi durch Aufrufen von services.AddScoped in der Methode ConfigureServices als Dienst registriert. Sie können dem Konstruktor einen PowerBiServiceApi-Parameter hinzufügen, und die .NET Core-Runtime übernimmt die Erstellung einer PowerBiServiceApi-Instanz und ihre Übergabe an den Konstruktor.

Öffnen Sie im Ordner Controllers die Datei HomeController.cs, und fügen Sie ihr den folgenden Codeausschnitt 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 in der folgenden Tabelle erstellen oder ändern.

Datei Zweck
embed.js Enthält den clientseitigen JavaScript-Code
Embed.cshtml Enthält das Dokumentobjektmodell (DOM) Ihrer App und einen DIV zum Einbetten des Berichts.

Erstellen eines Containers für ihren eingebetteten Bericht

Erstellen Sie die Datei Embed.cshtml, die über ein div-Element verfügt, das als Container für Ihren eingebetteten Bericht verwendet wird, und drei Skripts.

  1. Erstellen Sie im Ordner Ansicht > Start eine Datei mit dem Namen Embed.cshtml.

  2. Fügen Sie der Datei Embed.cshtml den folgenden Codeausschnitt 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 mithilfe der Variable models.

models wird mithilfe eines Aufrufs von window['powerbi-client'].models initialisiert. Die Variable models wird zum Festlegen von Konfigurationswerten wie models.Permissions.All, models.TokenType.Aad und models.ViewMode.View verwendet.

Die Funktion powerbi.embed verwendet das models-Konfigurationsobjekt zum Einbetten des Berichts.

  1. Erstellen Sie im Ordner wwwroot > js eine Datei mit dem Namen embed.js.

  2. Fügen Sie der Datei embed.js den folgenden Codeausschnitt hinzu.

    $(function () {
    
        // 1 - Get DOM object for div that is report container 
        var reportContainer = document.getElementById("embed-container");
    
        // 2 - Get report embedding data from view model
        var reportId = window.viewModel.reportId;
        var embedUrl = window.viewModel.embedUrl;
        var token = window.viewModel.token
    
        // 3 - Embed report 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 embed container on 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 in diesem Tutorial aufgeführten Anpassungen vorgenommen haben, können Sie Ihre Anwendung ausführen. Führen Sie Ihre Anwendung aus, und experimentieren Sie mit der Art und Weise,wie Ihr Power BI Bericht eingebettet ist. Sie können die Power BI Embedded Analytics-Client-APIs verwenden, um Ihre App mit clientseitigen APIs zu erweitern.

Wenn Ihre App bereit ist, können Sie Ihre eingebettete App in die Produktionsumgebung verschieben.

Nächste Schritte