Zelfstudie: Een Power BI-rapport insluiten in een toepassing voor uw organisatie

  • Artikel

In deze zelfstudie wordt uitgelegd hoe u een Power BI-rapport insluit in een .NET 5.0-toepassing, als onderdeel van de insluiting voor uw organisatie (ook wel bekend als gebruiker is eigenaar van gegevens). In een insluiting voor uw organisatieoplossing moeten uw app-gebruikers zich verifiëren bij Power BI met hun eigen referenties.

In deze zelfstudie leert u hoe u het volgende insluit:

  • Een Power BI-rapport
  • Insluiten voor uw organisatie-app
  • .NET 5.0 gebruiken
  • Met de Microsoft.Identity.Web bibliotheek (deze bibliotheek wordt ook ondersteund in .NET Core)

Notitie

De volledige oplossing die in deze zelfstudie wordt gebruikt, is beschikbaar in de GitHub-opslagplaats DOTNET5-UserOwnsData-Tutorial .

Vereisten

Resources

In deze zelfstudie gebruikt u:

Wijze

Voer de volgende stappen uit om Power BI-inhoud in te sluiten in een insluiting voor uw organisatieoplossing :

  1. Uw Microsoft Entra-app configureren
  2. De parameterwaarden voor insluiten ophalen
  3. De vereiste NuGet-pakketten toevoegen
  4. Verificatie aan serverzijde inschakelen
  5. De clientzijde van uw app bouwen
  6. Uw toepassing uitvoeren

Stap 1: uw Microsoft Entra-app configureren

Wanneer uw web-app Power BI aanroept, heeft deze een Microsoft Entra-token nodig om Power BI REST API's aan te roepen en Power BI-items, zoals rapporten, dashboards of tegels, in te sluiten.

Als u geen Microsoft Entra-app hebt, maakt u er een met behulp van de instructies in Een Microsoft Entra-toepassing registreren voor gebruik met Power BI.

Volg de instructies in Uw Microsoft Entra-app configureren om uw Microsoft Entra-app te configureren.

Stap 2: de parameterwaarden voor insluiten ophalen

Als u uw rapport wilt insluiten, hebt u de volgende waarden nodig:

Domein- en tenant-id

Als u uw domein- of tenant-id niet weet, raadpleegt u De Microsoft Entra-tenant-id en de primaire domeinnaam zoeken.

Notitie

Als u inhoud wilt insluiten voor een gebruiker in een andere tenant (een gastgebruiker), moet u de authorityUri parameter aanpassen.

Client ID

Voer de volgende stappen uit om de GUID van de client-id (ook wel toepassings-id genoemd) op te halen:

  1. Meld u aan bij Microsoft Azure.

  2. Zoek App-registraties en selecteer de koppeling App-registraties.

  3. Selecteer de Microsoft Entra-app die u gebruikt voor het insluiten van uw Power BI-inhoud.

  4. Kopieer in de sectie Overzicht de GUID van de toepassings-id (client).

Clientgeheim

Voer de volgende stappen uit om het clientgeheim op te halen:

  1. Meld u aan bij Microsoft Azure.

  2. Zoek App-registraties en selecteer de koppeling App-registraties.

  3. Selecteer de Microsoft Entra-app die u gebruikt voor het insluiten van uw Power BI-inhoud.

  4. Selecteer onder Beheren de optie Certificaten en geheimen.

  5. Selecteer onder Clientgeheimen het nieuwe clientgeheim.

  6. Geef in het pop-upvenster Een clientgeheim toevoegen een beschrijving op voor uw toepassingsgeheim, selecteer wanneer het toepassingsgeheim verloopt en selecteer Toevoegen.

  7. Kopieer in de sectie Clientgeheimen de tekenreeks in de kolom Waarde van het zojuist gemaakte toepassingsgeheim. De waarde van het clientgeheim is uw client-id.

Notitie

Zorg ervoor dat u de waarde van het clientgeheim kopieert wanneer deze voor het eerst wordt weergegeven. Nadat u van deze pagina bent verwijderd, wordt het clientgeheim verborgen en kunt u de waarde ervan niet ophalen.

Werkruimte-id

Voer de volgende stappen uit om de GUID van de werkruimte-id op te halen:

  1. Aanmelden bij Power BI-service.

  2. Open het rapport dat u wilt insluiten.

  3. Kopieer de GUID uit de URL. De GUID is het getal tussen /groups/ en /reports/.

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

Notitie

Gebruik de API Groepen ophalen om de werkruimte-id programmatisch op te halen.

Rapport-id

Voer de volgende stappen uit om de GUID van de rapport-id op te halen:

  1. Aanmelden bij Power BI-service.

  2. Open het rapport dat u wilt insluiten.

  3. Kopieer de GUID uit de URL. De GUID is het getal tussen /reports/ en /ReportSection.

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

Notitie

Als u de rapport-id programmatisch wilt ophalen, gebruikt u de API Rapporten ophalen in groep .

Stap 3: de vereiste NuGet-pakketten toevoegen

Voordat u begint, moet u de Microsoft.Identity.Weben Microsoft.PowerBI.Api NuGet-pakketten toevoegen aan uw app.

Voeg de volgende NuGet-pakketten toe aan uw app:

  • Open in VS Code een terminal en typ de volgende code.

  • Navigeer in Visual Studio naar Tools>NuGet Pakketbeheer> Pakketbeheer Console en typ de volgende code.

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

Als uw app eerder is gebruikt Microsoft.AspNetCore voor verificatie, verwijdert u dit pakket uit uw project door het volgende te typen:

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

Stap 4: verificatie aan serverzijde inschakelen

Schakel verificatie aan de serverzijde in uw app in door de bestanden in de volgende tabel te maken of te wijzigen.

Bestand Gebruik
Startup.cs De Microsoft.Identity.Web verificatieservice initialiseren
appsettings.json Verificatiedetails
PowerBiServiceApi.cs Het Microsoft Entra-token ophalen en metagegevens insluiten
HomeController.cs Gegevens als model doorgeven aan de weergave

Uw opstartbestand configureren ter ondersteuning Microsoft.Identity.Web

Wijzig de code in Startup.cs om de verificatieservice Microsoft.Identity.Webvan Start.cs correct te initialiseren.

Voeg het volgende codefragment toe aan het bestand Startup.cs van uw app.

Notitie

Met de code worden ConfigureServices verschillende belangrijke dingen gerealiseerd:

  1. De aanroep voor AddMicrosoftWebAppCallsWebApi het configureren van de Microsoft Authentication Library voor het verkrijgen van toegangstokens (Microsoft Entra-tokens).
  2. De aanroep voor AddInMemoryTokenCaches het configureren van een tokencache die door de Microsoft Authentication Library wordt gebruikt om toegangstokens in de cache op te cachen en tokens achter de schermen te vernieuwen
  3. De aanroep voor services.AddScoped(typeof(PowerBiServiceApi)) het configureren van de PowerBiServiceApi klasse als een serviceklasse die kan worden toegevoegd aan andere klassen met behulp van afhankelijkheidsinjectie.
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();

    }
  }
}

Een verificatiedetailsbestand maken

In deze zelfstudie bevat het appsettings.json bestand gevoelige informatie, zoals client-id en clientgeheim. Om veiligheidsredenen raden we u niet aan deze informatie in het instellingenbestand te bewaren. Overweeg bij het insluiten van inhoud in uw toepassing een veiligere methode, zoals Azure Key Vault , voor het bewaren van deze informatie.

  1. Maak in uw project een nieuw bestand en noem het appsettings.json.

  2. Voeg de volgende code toe aan 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. Vul de insluitparameterwaarden in die u hebt verkregen uit stap 2: haal de parameterwaarden voor insluiten op.

Notitie

In het vorige codefragment wordt de PowerBi:ServiceRootUrl parameter toegevoegd als een aangepaste configuratiewaarde om de basis-URL naar de Power BI-service bij te houden. Wanneer u programmeert op basis van de Power BI-service in de openbare Cloud van Microsoft, is https://api.powerbi.com/de URL. De hoofd-URL voor de Power BI-service is echter anders in andere clouds, zoals de overheidscloud. Daarom wordt deze waarde opgeslagen als een projectconfiguratiewaarde, zodat deze eenvoudig kan worden gewijzigd wanneer dat nodig is.

Haal het Microsoft Entra-toegangstoken op en roep de Power BI-service

Als u Power BI-inhoud (zoals rapporten en dashboards) wilt insluiten, moet uw app een Microsoft Entra-token ophalen. U hebt een configuratieobject nodig om het token op te halen.

De code in deze sectie maakt gebruik van het patroon .NET Core-afhankelijkheidsinjectie. Wanneer uw klasse een service moet gebruiken, kunt u een constructorparameter voor die service toevoegen en de .NET Core-runtime zorgt ervoor dat het service-exemplaar tijdens runtime wordt doorgegeven. In dit geval injecteert de constructor een exemplaar van de .NET Core-configuratieservice met behulp van de IConfiguration parameter, die wordt gebruikt om de PowerBi:ServiceRootUrl configuratiewaarde op te halen uit appsettings.json. De ITokenAcquisition parameter, die een naam tokenAcquisition heeft, bevat een verwijzing naar de Microsoft-verificatieservice die wordt geleverd door de Microsoft.Identity.Web bibliotheek en wordt gebruikt voor het verkrijgen van toegangstokens van Microsoft Entra ID.

Het RequiredScopes veld bevat een tekenreeksmatrix met een set gedelegeerde machtigingen die worden ondersteund door de Power BI-service-API. Wanneer uw toepassing in het netwerk aanroept om een Microsoft Entra-token te verkrijgen, geeft u deze set gedelegeerde machtigingen door, zodat de Microsoft Entra-id deze kan opnemen in het toegangstoken dat wordt geretourneerd.

Notitie

Controleer of uw Microsoft Entra-app is geconfigureerd met de bereiken die vereist zijn voor uw web-app. Zie De machtigingen van uw Microsoft Entra-app wijzigen voor meer informatie.

  1. Maak in het project van uw app een nieuwe map met de titel Services.

  2. Maak in de map Services een nieuw bestand met de naam PowerBiServiceApi.cs.

  3. Voeg de volgende code toe aan 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()
   };
  }

 }

}

Het bestand HomeController.cs wijzigen

In dit codevoorbeeld gebruikt u afhankelijkheidsinjectie. Terwijl u de PowerBiServiceApi klasse als een service hebt geregistreerd door de ConfigureServices methode aan te roepenservices.AddScoped. U kunt een PowerBiServiceApi parameter toevoegen aan de constructor en de .NET Core-runtime zorgt ervoor dat een PowerBiServiceApi exemplaar wordt gemaakt en doorgegeven aan de constructor.

Open vanuit de map Controllers het bestand HomeController.cs en voeg het toe aan het volgende codefragment:

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

Stap 5: de clientzijde van uw app bouwen

Voor implementatie aan de clientzijde moet u de bestanden in de volgende tabel maken of wijzigen.

Bestand Gebruik
embed.js Bevat de JavaScript-code aan de clientzijde
Embed.cshtml Bevat het documentobjectmodel van uw app (DOM) en een DIV voor het insluiten van het rapport

Een container maken voor uw ingesloten rapport

Maak het embed.cshtml-bestand , dat een div element bevat dat wordt gebruikt als een container voor uw ingesloten rapport en drie scripts.

  1. Maak in de map Startweergave> een bestand met de naam Embed.cshtml.

  2. Voeg het volgende codefragment toe aan het bestand 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>
}

JavaScript aan clientzijde toevoegen om uw rapport in te sluiten

Als u Power BI-inhoud wilt insluiten, moet u een configuratieobject maken. Zie Een rapport insluiten voor meer informatie over het maken van het configuratieobject.

In deze sectie maakt u een JavaScript-bestand met de naam embed.js met een configuratieobject voor het insluiten van uw rapport met behulp van de variabele models.

models wordt geïnitialiseerd met behulp van een aanroep naar window['powerbi-client'].models. De models variabele wordt gebruikt om configuratiewaarden zoals models.Permissions.All, models.TokenType.Aaden models.ViewMode.View.

De powerbi.embed functie gebruikt het models configuratieobject om uw rapport in te sluiten.

  1. Maak in de map wwwroot>js een bestand met de naam embed.js.

  2. Voeg het volgende codefragment toe aan het embed.js-bestand .

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

});

Stap 6: Uw toepassing uitvoeren

Nadat u alle wijzigingen in deze zelfstudie hebt aangebracht, bent u klaar om uw toepassing uit te voeren. Voer uw toepassing uit en experimenteer met de manier waarop uw Power BI-rapport is ingesloten. U kunt de client-API's voor ingesloten analyses van Power BI gebruiken om uw app te verbeteren met behulp van API's aan de clientzijde.

Wanneer uw app klaar is, kunt u uw ingesloten app verplaatsen naar productie.

Gerelateerde inhoud

Toepassingstokens voor ingesloten analyses

Uw ingesloten app verplaatsen naar productie

Capaciteit en SKU's in ingesloten analyses in Power BI

Capaciteitsplanning in ingesloten analyses in Power BI