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

  • Artikel

In diesem Tutorial erfahren Sie, wie Sie einen Power BI-Bericht im Rahmen von Einbetten für Ihre Organisation (auch bekannt als User-Owns-Data-Lösung) in eine .NET 5.0-Anwendung einbetten. In einer Einbetten für Ihre Organisation-Lösung müssen sich Ihre App-Benutzer bei Power BI mit eigenen Anmeldeinformationen authentifizieren.

In diesem Tutorial lernen Sie, wie Folgendes eingebettet wird:

  • ein Power BI-Bericht
  • in einer App vom Typ Einbetten für Ihre Organisation
  • 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-UserOwnsData-Tutorial verfügbar.

Voraussetzungen

Ressourcen

In diesem Tutorial gehen Sie wie folgt vor:

Methode

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

  1. Konfigurieren Ihrer Microsoft Entra-App
  2. Rufen Sie die Werte für den Einbettungsparameter ab
  3. Hinzufügen der erforderlichen NuGet-Pakete
  4. Aktivieren der serverseitigen Authentifizierung
  5. Erstellen der Clientseite Ihrer App
  6. Ausführen der Anwendung

Schritt 1: Konfigurieren Ihrer Microsoft Entra-App

Wenn Ihre Web-App Power BI aufruft, benötigt sie ein Microsoft Entra-Token zum Aufrufen der Power BI REST-APIs und zum Einbetten von Power BI-Elementen wie Berichten, Dashboards oder Kacheln.

Wenn Sie nicht über eine Microsoft Entra-App verfügen, erstellen Sie eine anhand der Anweisungen unter Registrieren einer Microsoft Entra-Anwendung für die Verwendung mit Power BI.

Zum Konfigurieren Ihrer Microsoft Entra-App folgen Sie den Anweisungen unter Konfigurieren Ihrer Microsoft Entra-App.

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 Mandant*inen-ID nicht kennen, lesen Sie Suchen der Microsoft Entra Mandant*inen-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 Microsoft Entra-App aus, die Sie zum Einbetten Ihrer Power BI-Inhalte 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 Microsoft Entra-App aus, die Sie zum Einbetten Ihrer Power BI-Inhalte 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/ .

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

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

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

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 die folgenden NuGet-Pakete zu Ihrer App hinzu:

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

  • Navigieren Sie in Visual Studiozu Extras>NuGet Paket-Manager>Paket-Manager-Konsole, und geben Sie den Code unten ein.

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

Wenn Ihre App zuvor Microsoft.AspNetCore für die Authentifizierung verwendet hat, entfernen Sie dieses Paket aus Ihrem Projekt, indem Sie Folgendes eingeben:

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

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 Verwendung
Startup.cs Initialisieren des Microsoft.Identity.Web-Authentifizierungsdiensts
appsettings.json Authentifizierungsdetails
PowerBiServiceApi.cs Abrufen des Microsoft Entra-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 Codeschnipsel 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 (Microsoft Entra-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 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();

    }
  }
}

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 ist es nicht empfehlenswert, 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": "",
        "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 vorherigen Codeausschnitt 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 Microsoft Entra-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 Microsoft Entra-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 Microsoft Entra ID 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 Microsoft Entra-Tokens übergibt sie diesen Satz delegierter Berechtigungen, sodass Microsoft Entra ID sie in das zurückgegebene Zugriffstoken einschließen kann.

Hinweis

Vergewissern Sie sich, dass Ihre Microsoft Entra-App mit den Bereichen konfiguriert ist, die für Ihre Web-App erforderlich sind. Weitere Informationen finden Sie unter Ändern der Berechtigungen Ihrer Microsoft Entra-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 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()
   };
  }

 }

}

Ä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 sie dem folgenden Codeausschnitt hinzu:

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

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

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

});

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.

Zugehöriger Inhalt

Anwendungstoken für eingebettete Analysen

Verschieben Ihrer eingebetteten App in die Produktion

Kapazität und SKUs in Power BI Embedded Analytics

Planen der Kapazität in Power BI Embedded Analytics