Del via

Selvstudium: Integrer en Power BI-rapport i et program til din organisation

  • Artikel

I dette selvstudium forklares det, hvordan du integrerer en Power BI-rapport i et .NET 5.0-program som en del af løsningen til integrering for din organisation (også kaldet brugeren ejer data). I en løsning til integrering for din organisation skal appbrugerne godkende i forhold til Power BI med deres egne legitimationsoplysninger.

I dette selvstudium lærer du, hvordan du integrerer:

  • En Power BI-rapport
  • I en integrering for din organisationsapp
  • Brug af .NET 5.0
  • Med biblioteket Microsoft.Identity.Web (dette bibliotek understøttes også i .NET Core)

Bemærk

Den komplette løsning, der bruges i dette selvstudium, er tilgængelig fra GitHub-lageret DOTNET5-UserOwnsData-Tutorial .

Forudsætninger

Ressourcer

I dette selvstudium skal du bruge:

Metode

Hvis du vil integrere Power BI-indhold i en løsning til integrering for din organisation , skal du følge disse trin:

  1. Konfigurer din Microsoft Entra-app
  2. Hent integreringsparameterværdierne
  3. Tilføj de påkrævede NuGet-pakker
  4. Aktivér godkendelse på serversiden
  5. Byg din apps klientside
  6. Kør dit program

Trin 1 – Konfigurer din Microsoft Entra-app

Når din webapp kalder Power BI, skal den bruge et Microsoft Entra-token for at kunne kalde REST API'er til Power BI og integrere Power BI-elementer, f.eks. rapporter, dashboards eller felter.

Hvis du ikke har en Microsoft Entra-app, kan du oprette en ved hjælp af vejledningen i Registrer et Microsoft Entra-program, der skal bruges sammen med Power BI.

Hvis du vil konfigurere din Microsoft Entra-app, skal du følge vejledningen i Konfigurer din Microsoft Entra-app.

Trin 2 – Hent parameterværdierne for integrering

Hvis du vil integrere din rapport, skal du bruge følgende værdier:

Domæne- og lejer-id

Hvis du ikke kender dit domæne eller lejer-id, skal du se Find Microsoft Entra-lejer-id'et og det primære domænenavn.

Bemærk

Hvis du vil integrere indhold for en bruger på en anden lejer (en gæstebruger), skal du justere authorityUri parameteren.

Client ID

Hvis du vil hente guid'et for klient-id'et (også kaldet program-id), skal du følge disse trin:

  1. Log på Microsoft Azure.

  2. Søg efter Appregistreringer, og vælg linket Appregistreringer .

  3. Vælg den Microsoft Entra-app, du bruger til at integrere dit Power BI-indhold.

  4. Kopiér GUID'et for program-id'et (klient) i afsnittet Oversigt.

Klienthemmelighed

Følg disse trin for at hente klienthemmeligheden:

  1. Log på Microsoft Azure.

  2. Søg efter Appregistreringer, og vælg linket Appregistreringer .

  3. Vælg den Microsoft Entra-app, du bruger til at integrere dit Power BI-indhold.

  4. Under Administrer skal du vælge Certifikater & hemmeligheder.

  5. Under Klienthemmeligheder skal du vælge Ny klienthemmelighed.

  6. I pop op-vinduet Tilføj en klienthemmelighed skal du angive en beskrivelse af programhemmeligheden, vælge, hvornår programhemmeligheden udløber, og vælge Tilføj.

  7. I afsnittet Klienthemmeligheder skal du kopiere strengen i kolonnen Value for den nyoprettede programhemmelighed. Værdien for klienthemmeligheden er dit klient-id.

Bemærk

Sørg for at kopiere værdien for klienthemmeligheden, første gang den vises. Når du har navigeret væk fra denne side, skjules klienthemmeligheden, og du kan ikke hente dens værdi.

Id for arbejdsområde

Følg disse trin for at hente GUID'et for arbejdsområdets id:

  1. Log på Power BI-tjenesten.

  2. Åbn den rapport, du vil integrere.

  3. Kopiér GUID'et fra URL-adressen. GUID'et er tallet mellem /groups/ og /reports/.

    Et skærmbillede, der viser GUID for arbejdsområde-id'et i URL-adressen til Power BI-tjeneste

Bemærk

Hvis du vil hente arbejdsområde-id'et programmatisk, skal du bruge API'en Hent grupper .

Rapport-id

Følg disse trin for at hente GUID'et for rapport-id'et:

  1. Log på Power BI-tjenesten.

  2. Åbn den rapport, du vil integrere.

  3. Kopiér GUID'et fra URL-adressen. GUID'et er tallet mellem /reports/ og /ReportSection.

    Et skærmbillede, der viser GUID for rapport-id'et i Power BI-tjenestenS

Bemærk

Hvis du vil hente rapport-id'et programmeringsmæssigt, skal du bruge API'en Hent rapporter i gruppe .

Trin 3 – Tilføj de påkrævede NuGet-pakker

Før du starter, skal du føje pakkerne Microsoft.Identity.Web, og Microsoft.PowerBI.Api NuGet til din app.

Føj følgende NuGet-pakker til din app:

  • Åbn en terminal i VS Code, og skriv følgende kode.

  • I Visual Studio skal du gå til Tools>NuGet Pakkestyring> Pakkestyring Console og skrive følgende kode.

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

Hvis din app tidligere blev godkendt Microsoft.AspNetCore , skal du fjerne denne pakke fra projektet ved at skrive:

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

Trin 4 – Aktivér godkendelse på serversiden

Aktivér godkendelse på serversiden i din app ved at oprette eller ændre filerne i følgende tabel.

Filer Bruge
Startup.cs Initialiser godkendelsestjenesten Microsoft.Identity.Web
appsettings.json Godkendelsesoplysninger
PowerBiServiceApi.cs Hent Microsoft Entra-tokenet og integreringsmetadata
HomeController.cs Overfør integreringsdata som en model til visningen

Konfigurer startfilen til at understøtte Microsoft.Identity.Web

Rediger koden i Startup.cs for at initialisere godkendelsestjenesten, der leveres af Microsoft.Identity.Web.

Føj følgende kodestykke til din apps Startup.cs-fil .

Bemærk

Koden i ConfigureServices udfører flere vigtige ting:

  1. Kaldet til at AddMicrosoftWebAppCallsWebApi konfigurere Microsoft Authentication Library til at hente adgangstokens (Microsoft Entra-tokens).
  2. Kaldet til at AddInMemoryTokenCaches konfigurere en tokencache, som Microsoft Authentication Library bruger til at cachelagre adgangstokens og opdatere tokens i baggrunden
  3. Kaldet til at services.AddScoped(typeof(PowerBiServiceApi)) konfigurere PowerBiServiceApi klassen som en tjenesteklasse, der kan føjes til andre klasser ved hjælp af afhængighedsinjektion.
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();

    }
  }
}

Opret en fil med godkendelsesoplysninger

I dette selvstudium appsettings.json indeholder filen følsomme oplysninger, f.eks . klient-id og klienthemmelighed. Af sikkerhedsmæssige årsager anbefaler vi ikke, at du beholder disse oplysninger i indstillingsfilen. Når du integrerer i dit program, skal du overveje en mere sikker metode, f.eks . Azure Key Vault , for at bevare disse oplysninger.

  1. Opret en ny fil i projektet, og kald den appsettings.json.

  2. Føj følgende kode til 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. Udfyld de integreringsparameterværdier, der er hentet fra trin 2 – Hent parameterværdierne for integrering.

Bemærk

I det forrige kodestykke PowerBi:ServiceRootUrl tilføjes parameteren som en brugerdefineret konfigurationsværdi for at spore den grundlæggende URL-adresse til Power BI-tjeneste. Når du programmerer i forhold til Power BI-tjeneste i Microsofts offentlige cloudmiljø, er https://api.powerbi.com/URL-adressen . Rod-URL-adressen til Power BI-tjeneste vil dog være anderledes i andre cloudmiljøer, f.eks. Government Cloud. Derfor gemmes denne værdi som en konfigurationsværdi for projektet, så den er nem at ændre, når det er nødvendigt.

Hent Microsoft Entra-adgangstokenet, og kald Power BI-tjeneste

Hvis du vil integrere Power BI-indhold (f.eks. rapporter og dashboards), skal din app have et Microsoft Entra-token. Hvis du vil hente tokenet, skal du bruge et konfigurationsobjekt.

Koden i dette afsnit bruger .NET Core-afhængighedsinjektionsmønsteret. Når din klasse skal bruge en tjeneste, kan du tilføje en konstruktørparameter for den pågældende tjeneste, og .NET Core-kørslen sørger for at overføre tjenesteforekomsten på kørselstidspunktet. I dette tilfælde indsætter konstruktøren en forekomst af .NET Core-konfigurationstjenesten ved hjælp af IConfiguration parameteren , som bruges til at hente PowerBi:ServiceRootUrl konfigurationsværdien fra appsettings.json. Parameteren ITokenAcquisition , som kaldes tokenAcquisition , indeholder en reference til den Microsoft-godkendelsestjeneste, der leveres af Microsoft.Identity.Web biblioteket, og den bruges til at hente adgangstokens fra Microsoft Entra ID.

Feltet RequiredScopes indeholder en strengmatrix, der indeholder et sæt delegerede tilladelser, der understøttes af api'en til Power BI-tjeneste. Når dit program kalder på tværs af netværket for at hente et Microsoft Entra-token, overføres dette sæt delegerede tilladelser, så Microsoft Entra ID kan inkludere dem i det adgangstoken, det returnerer.

Bemærk

Kontrollér, at din Microsoft Entra-app er konfigureret med de områder, der kræves af din webapp. Du kan få flere oplysninger under Skift tilladelserne til din Microsoft Entra-app.

  1. Opret en ny mappe med titlen Tjenester i appens projekt.

  2. Opret en ny fil med titlen PowerBiServiceApi.cs i mappen Tjenester.

  3. Føj følgende kode til 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()
   };
  }

 }

}

Rediger filen HomeController.cs

I dette kodeeksempel bruger du afhængighedsinjektion. Da du registrerede PowerBiServiceApi klassen som en tjeneste ved at kalde services.AddScoped metoden ConfigureServices . Du kan føje en PowerBiServiceApi parameter til konstruktøren, og .NET Core-kørslen tager sig af at oprette en PowerBiServiceApi forekomst og overføre den til konstruktøren.

Åbn filen HomeController.cs i mappen Controllers, og føj den til følgende kodestykke:

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

Trin 5 – Byg din apps klientside

I forbindelse med implementering på klientsiden skal du oprette eller redigere filerne i følgende tabel.

Filer Bruge
embed.js Indeholder JavaScript-koden på klientsiden
Embed.cshtml Indeholder appens dokumentobjektmodel (DOM) og et DIV til integrering af rapporten

Opret en objektbeholder til din integrerede rapport

Opret filen Embed.cshtml, som indeholder et div element, der bruges som objektbeholder for din integrerede rapport, og tre scripts.

  1. Opret en fil med navnet Embed.cshtml i mappen Vis>startside.

  2. Føj følgende kodestykke til filen 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>
}

Tilføj JavaScript på klientsiden for at integrere din rapport

Hvis du vil integrere Power BI-indhold, skal du oprette et konfigurationsobjekt. Du kan få mere at vide om oprettelse af konfigurationsobjektet under Integrer en rapport.

I dette afsnit skal du oprette en JavaScript-fil med navnet embed.js med et konfigurationsobjekt til integrering af rapporten ved hjælp af variablen models.

models initialiseres ved hjælp af et kald til window['powerbi-client'].models. Variablen models bruges til at angive konfigurationsværdier som models.Permissions.All, models.TokenType.Aadog models.ViewMode.View.

Funktionen powerbi.embed bruger konfigurationsobjektet models til at integrere din rapport.

  1. Opret en fil med navnet embed.js i mappen wwwroot>js.

  2. Føj følgende kodestykke til filen 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);
    });

});

Trin 6 – Kør dit program

Når du har foretaget alle de justeringer, der er angivet i dette selvstudium, er du klar til at køre dit program. Udfør dit program, og eksperimentér med den måde, din Power BI-rapport integreres på. Du kan bruge klient-API'er til integreret analyse i Power BI til at forbedre din app ved hjælp af api'er på klientsiden.

Når din app er klar, kan du flytte din integrerede app til produktion.

Relateret indhold