Selvstudium: Integrer en Power BI-rapport i et program til dine kunder

  • Artikel

I dette selvstudium lærer du, hvordan du integrerer en Power BI-rapport i et .NET 5.0-program som en del af løsningen embed-for-your-customers (også kaldet en app-owns-data). I en løsning til integrering for dine kunder behøver dine appbrugere ikke at logge på Power BI eller have en Power BI-licens.

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

  • En Power BI-rapport.
  • I en app til integrering for dine kunder.
  • Ved hjælp af en tjenesteprincipal.
  • Ved hjælp 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-AppOwnsData-Tutorial .

Forudsætninger

Ressourcer

I dette selvstudium skal du bruge:

Metode

Hvis du vil integrere Power BI-indhold i en løsning, der er integreret til dine kunder, skal du følge disse trin:

  1. Konfigurer din Microsoft Entra-app og tjenesteprincipal.

  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 og tjenesteprincipal

I dette selvstudium skal du bruge en tjenesteprincipal til at godkende din webapp i forhold til Microsoft Entra ID. Du skal også bruge en Microsoft Entra-app, hvilket gør det muligt at generere et Microsoft Entra-token. Ved hjælp af Microsoft Entra-tokenet kan din webapp kalde REST API'er til Power BI og integrere Power BI-elementer, f.eks. rapporter, dashboards og felter.

Følg vejledningen til tjenesteprincipalen for at oprette en Microsoft Entra-app og aktivere appens tjenesteprincipal for at arbejde med dit Power BI-indhold.

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

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

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.

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

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 kan starte, skal du føje pakkerne Microsoft.Identity.Web, og Microsoft.PowerBI.Api NuGet til din app.

Føj de påkrævede NuGet-pakker til din app:

  • Åbn en terminal i VS Code, og angiv 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
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api

Trin 4 – Aktivér godkendelse på serversiden

Slå servergodkendelse til i din app ved at oprette eller ændre filerne i følgende tabel.

Filer Bruge
Startup.cs Initialiser godkendelsestjenesten Microsoft.Identity.Web
appsettings.json Konfigurer 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, så den godkendelsestjeneste, der leveres af , initialiseres korrekt.Microsoft.Identity.Web

Føj følgende kode til appens 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 klassen PowerBiServiceApi som en tjenesteklasse, der kan føjes til andre klasser ved hjælp af afhængighedsinjektion.
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();
            });
        }
    }
}

Opret en fil med godkendelsesoplysninger

I dette selvstudium indeholder filen appsettings.json følsomme oplysninger, f.eks . klient-id og klienthemmelighed. Af sikkerhedsmæssige årsager anbefaler vi ikke, at du gemmer disse oplysninger i indstillingsfilen. Når du integrerer i dit program, skal du overveje et mere sikkert værktøj, f.eks . Azure Key Vault, for at sikre følsomme oplysninger.

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

  2. Føj følgende kode til appsettings.json:

    {
 "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. Udfyld de integreringsparameterværdier, der er hentet fra trin 2 – Hent parameterværdierne for integrering.

Bemærk

I den foregående kode 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 for Power BI-tjeneste er dog anderledes i andre cloudmiljøer, f.eks. government-cloudmiljøet. Derfor gemmes den brugerdefinerede konfigurationsværdi som en konfigurationsværdi for projektet, så du kan ændre den efter behov.

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

Hvis du vil integrere Power BI-indhold som rapporter og dashboards, skal din app hente 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. .NET Core-kørsel tager sig af at overføre tjenesteforekomsten på kørselstidspunktet. I dette tilfælde indsætter konstruktøren en forekomst af .NET Core-konfigurationstjenesten ved hjælp IConfiguration af parameteren , som bruges til at hente PowerBi:ServiceRootUrl konfigurationsværdien fra appsettings.json. Parameteren ITokenAcquisition , der hedder tokenAcquisition, indeholder en reference til den Microsoft-godkendelsestjeneste, der leveres af Microsoft.Identity.Web biblioteket. Parameteren ITokenAcquisition 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ører det 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 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
            };
        }

    }
}

Rediger filen HomeController.cs

I dette kodeeksempel bruger du en afhængighedsinjektion til at ændre filen HomeController.cs . Ved at følge et forrige trin har du konfigureret PowerBiServiceApi klassen som en tjeneste ved at kalde services.AddScoped metoden ConfigureServices . Med denne kode føjer du en PowerBiServiceApi parameter til konstruktøren, og .NET Core-kørslen opretter en PowerBiServiceApi forekomst og sender den til konstruktøren.

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

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

Trin 5 – Byg din apps klientside

I forbindelse med implementering på klientsiden skal du oprette eller redigere de filer, der er angivet 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

I dette selvstudium skal du oprette filen Embed.cshtml , som indeholder et div element, der er en objektbeholder til din integrerede rapport, og tre scripts.

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

  2. Føj følgende kode til filen Embed.cshtml .

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

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 selvstudium skal du oprette en JavaScript-fil med navnet embed.js med et konfigurationsobjekt til integrering af din rapport, der bruger variablen models.

Du kan initialisere models 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 kode til filen embed.js .

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

  });

Trin 6 – Kør dit program

Når du har fulgt alle tidligere trin, er du klar til at køre dit program. Prøv at køre 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.

Vigtigt

Hvis du har brugt gratis integreringstokens til udvikling, skal du købe en kapacitet til produktion. Indtil der er købt en kapacitet, vises banneret Gratis prøveversion fortsat øverst i den integrerede rapport.

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

Relateret indhold

Tokens til program til integreret analyse

Flyt din integrerede app til produktion

Kapacitet og SKU'er i en integreret Power BI-analyse

Kapacitetsplanlægning i en integreret Power BI-analyse