Opplæring: Bygge inn en Power BI-rapport i et program for kundene dine

  • Artikkel

I denne opplæringen lærer du hvordan du bygger inn en Power BI-rapport i et .NET 5.0-program, som en del av innebygging for kundene dine (også kjent som en app-eier-data)-løsning. I en innebyggingsløsning for kundene trenger ikke appbrukerne å logge på Power BI eller ha en Power BI-lisens.

I denne opplæringen lærer du hvordan du bygger inn:

  • En Power BI-rapport.
  • I en innebyggingsapp for kundene dine.
  • Ved hjelp av en tjenestekontohaver.
  • Ved hjelp av .NET 5.0.
  • Microsoft.Identity.Web Med biblioteket (dette biblioteket støttes også i .NET Core).

Merk

Den fullstendige løsningen som brukes i denne opplæringen , er tilgjengelig fra DOTNET5-AppOwnsData-Tutorial GitHub-repositoriet.

Forutsetning

Ressurser

I denne opplæringen bruker du:

Metode

Følg disse trinnene for å bygge inn Power BI-innhold i en innebyggingsløsning for kundene dine:

  1. Konfigurer Microsoft Entra-appen og tjenestekontohaveren.

  2. Hent parameterverdiene for innebygging.

  3. Legg til de nødvendige NuGet-pakkene.

  4. Aktiver godkjenning på serversiden.

  5. Bygg appens klientside.

  6. Kjør programmet.

Trinn 1 – Konfigurere Microsoft Entra-appen og tjenestekontohaveren

I denne opplæringen bruker du en tjenestekontohaver til å godkjenne nettappen mot Microsoft Entra ID. Du trenger også en Microsoft Entra-app, som gjør det mulig å generere et Microsoft Entra-token. Ved hjelp av Microsoft Entra-tokenet kan nettappen ringe Rest-API-er for Power BI og bygge inn Power BI-elementer, for eksempel rapporter, instrumentbord og fliser.

Følg instruksjonene for tjenestekontohaver for å opprette en Microsoft Entra-app og gjøre det mulig for appens tjenestekontohaver å arbeide med Power BI-innholdet.

Trinn 2 – Hent parameterverdiene for innebygging

Hvis du vil bygge inn rapporten, trenger du følgende verdier:

Domene- og leier-ID

Hvis du ikke kjenner domenet eller leier-ID-en din, kan du se Finne leier-ID-en for Microsoft Entra og det primære domenenavnet.

Merk

Hvis du vil bygge inn innhold for en bruker på en annen leier (gjestebruker),må du justere parameteren authorityUri .

Client ID

Følg disse trinnene for å få GUID-en for klient-ID (også kjent som program-ID):

  1. Logg på Microsoft Azure.

  2. Søk etter appregistreringer, og velg appregistreringskoblingen.

  3. Velg Microsoft Entra-appen du bruker til å bygge inn Power BI-innholdet.

  4. Kopier GUID-en for program-ID (klient) fra oversiktsdelen.

Klienthemmelighet

Følg disse trinnene for å få klienthemmeligheten:

  1. Logg på Microsoft Azure.

  2. Søk etter appregistreringer, og velg appregistreringskoblingen.

  3. Velg Microsoft Entra-appen du bruker til å bygge inn Power BI-innholdet.

  4. Velg Sertifikater og hemmeligheter under Administrer.

  5. Velg Ny klienthemmelighet under Klienthemmeligheter.

  6. Angi en beskrivelse for programhemmeligheten i popup-vinduet Legg til en klienthemmelighet , velg når programhemmeligheten utløper, og velg Legg til.

  7. Kopier strengen i Verdi-kolonnen for den nyopprettede programhemmeligheten fra delen Klienthemmeligheter. Klienthemmelighetsverdien er klient-ID-en din.

Merk

Kontroller at du kopierer den hemmelige klientverdien når den vises først. Når du har navigert bort fra denne siden, skjules klienthemmeligheten, og du kan ikke hente verdien.

Arbeidsområde-ID

Følg disse trinnene for å få GUID-en for arbeidsområde-ID:

  1. Logg på Power BI-tjenesten.

  2. Åpne rapporten du vil bygge inn.

  3. Kopier GUIDen fra URL-adressen. GUID-en er tallet mellom /groups/ og /reports/.

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

Merk

Bruk API-en Hent grupper for å få ID-en for arbeidsområdet programmatisk.

Rapport-ID

Følg disse trinnene for å få GUID-en for rapport-ID:

  1. Logg på Power BI-tjenesten.

  2. Åpne rapporten du vil bygge inn.

  3. Kopier GUIDen fra URL-adressen. GUID-en er tallet mellom /reports/ og /ReportSection.

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

Merk

Bruk API-en Hent rapporter i gruppe for å få rapport-ID-en programmatisk.

Trinn 3 – Legg til de nødvendige NuGet-pakkene

Før du kan begynne, må du legge Microsoft.Identity.Webtil , og Microsoft.PowerBI.Api NuGet-pakkene i appen.

Legg til de nødvendige NuGet-pakkene i appen:

  • Åpne en terminal i VS Code, og angi følgende kode.

  • Gå til Verktøy>NuGet Pakkebehandling> Pakkebehandling Konsoll i Visual Studio, og skriv inn følgende kode.

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api

Trinn 4 – Aktiver godkjenning på serversiden

Aktiver godkjenning på serversiden i appen ved å opprette eller endre filene i tabellen nedenfor.

Fil Bruk
Startup.cs Initialiser Microsoft.Identity.Web godkjenningstjenesten
appsettings.json Konfigurer godkjenningsdetaljer
PowerBiServiceApi.cs Få Microsoft Entra-tokenet og innebygging av metadata
HomeController.cs Sende innebyggingsdata som modell til visningen

Konfigurer oppstartsfilen til støtte Microsoft.Identity.Web

Endre koden i Startup.cs for å initialisere godkjenningstjenesten som leveres av Microsoft.Identity.Web.

Legg til følgende kode i appens Startup.cs-fil .

Merk

Koden i ConfigureServices oppnår flere viktige ting:

  1. Kallet for å AddMicrosoftWebAppCallsWebApi konfigurere Microsoft Authentication Library til å skaffe tilgangstokener (Microsoft Entra-tokener).
  2. Kallet til å AddInMemoryTokenCaches konfigurere en tokenbuffer som Microsoft Authentication Library bruker til å bufre tilgangstokener og oppdateringstokener bak kulissene.
  3. Kallet for å services.AddScoped(typeof(PowerBiServiceApi)) konfigurere klassen som en tjenesteklasse som kan legges til i andre klasser ved hjelp av avhengighetsinjeksjon PowerBiServiceApi .
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();
            });
        }
    }
}

Opprette en fil med godkjenningsdetaljer

I denne opplæringen inneholder appsettings.json-filen sensitiv informasjon, for eksempel klient-ID og klienthemmelighet. Av sikkerhetsgrunner anbefaler vi ikke at du beholder denne informasjonen i innstillingsfilen. Når du bygger inn i programmet, bør du vurdere et sikrere verktøy, for eksempel Azure Key Vault, for å sikre sensitiv informasjon.

  1. Opprett en ny fil i prosjektet, og gi den navnet appsettings.json.

  2. Legg til følgende kode i 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. Fyll ut parameterverdiene for innebygging hentet fra trinn 2 – Hent parameterverdiene for innebygging.

Merk

I den forrige koden legges parameteren PowerBi:ServiceRootUrl til som en egendefinert konfigurasjonsverdi for å spore den grunnleggende URL-adressen til Power Bi-tjeneste. Når du programmerer mot Power Bi-tjeneste i microsofts offentlige sky, er https://api.powerbi.com/nettadressen . Rotnettadressen for Power Bi-tjeneste er imidlertid forskjellig i andre skyer, for eksempel offentlig sky. Derfor lagres den egendefinerte konfigurasjonsverdien som en prosjektkonfigurasjonsverdi, slik at du kan endre den etter behov.

Hent tilgangstokenet for Microsoft Entra, og kall Power Bi-tjeneste

Hvis du vil bygge inn Power BI-innhold som rapporter og instrumentbord, må appen få et Microsoft Entra-token. Hvis du vil hente tokenet, trenger du et konfigurasjonsobjekt.

Koden i denne delen bruker injeksjonsmønsteret for .NET Core-avhengighet. Når klassen må bruke en tjeneste, kan du legge til en konstruktørparameter for denne tjenesten. .NET Core-kjøretiden tar seg av å sende tjenesteforekomsten ved kjøretid. I dette tilfellet setter konstruktøren inn en forekomst av .NET Core-konfigurasjonstjenesten ved hjelp av parameteren IConfiguration , som brukes til å hente PowerBi:ServiceRootUrl konfigurasjonsverdien fra appsettings.json. Parameteren ITokenAcquisition , som heter tokenAcquisition, inneholder en referanse til Microsoft-godkjenningstjenesten som leveres av Microsoft.Identity.Web biblioteket. Parameteren ITokenAcquisition brukes til å hente tilgangstokener fra Microsoft Entra ID.

Feltet RequiredScopes inneholder en strengmatrise som inneholder et sett med delegerte tillatelser som støttes av Power Bi-tjeneste API-en. Når programmet ringer over nettverket for å skaffe et Microsoft Entra-token, sender det dette settet med delegerte tillatelser, slik at Microsoft Entra ID kan inkludere dem i tilgangstokenet det returnerer.

Merk

Kontroller at Microsoft Entra-appen er konfigurert med omfangene som kreves av nettappen. Hvis du vil ha mer informasjon, kan du se Endre microsoft Entra-appens tillatelser.

  1. Opprett en ny mappe med tittelen Tjenester i appens prosjekt.

  2. Opprett en ny fil med tittelen PowerBiServiceApi.cs i Tjeneste-mappen.

  3. Legg til følgende kode i 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
            };
        }

    }
}

Endre HomeController.cs-filen

I dette kodeeksemplet bruker du avhengighetsinjeksjon til å endre HomeController.cs-filen . Ved å følge et tidligere trinn konfigurerte PowerBiServiceApi du klassen som en tjeneste ved å ringe services.AddScoped inn ConfigureServices metoden. Med denne koden legger du til en PowerBiServiceApi parameter i konstruktøren, og .NET Core runtime oppretter en PowerBiServiceApi forekomst og sender den til konstruktøren.

Åpne HomeController.cs-filen fra Kontroller-mappen, og legg til følgende kode i 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 });
        }
    }
}

Trinn 5 – bygg appens klientside

For implementering på klientsiden må du opprette eller endre filene som er oppført i følgende tabell:

Fil Bruk
embed.js Inneholder JavaScript-koden på klientsiden
Embed.cshtml Inneholder appens dokumentobjektmodell (DOM) og en DIV for innebygging av rapporten

Opprette en beholder for den innebygde rapporten

I denne opplæringen oppretter du Embed.cshtml-filen , som har et div element som er en beholder for den innebygde rapporten, og tre skript.

  1. Opprett en fil kalt Embed.cshtml i Mappen Vis/hjem.

  2. Legg til følgende kode i Embed.cshtml-filen .

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

Legg til JavaScript på klientsiden for å bygge inn rapporten

Hvis du vil bygge inn Power BI-innhold, må du opprette et konfigurasjonsobjekt. Hvis du vil lære mer om hvordan du oppretter konfigurasjonsobjektet, kan du se Bygge inn en rapport.

I denne opplæringen oppretter du en JavaScript-fil med navnet embed.js med et konfigurasjonsobjekt for innebygging av rapporten som bruker variabelen models.

Du kan initialisere models ved å bruke et kall til window['powerbi-client'].models. Variabelen models brukes til å angi konfigurasjonsverdier som models.Permissions.All, models.TokenType.Aadog models.ViewMode.View.

Funksjonen powerbi.embed bruker konfigurasjonsobjektet models til å bygge inn rapporten.

  1. Opprett en fil kalt embed.js i wwwroot/js-mappen.

  2. Legg til følgende kode i embed.js-filen .

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

  });

Trinn 6 – Kjør programmet

Når du har fulgt alle tidligere trinn, er du klar til å kjøre programmet. Prøv å kjøre programmet, og eksperimenter med måten Power BI-rapporten er innebygd på. Du kan bruke klient-API-er for innebygd analyse for Power BI til å forbedre appen ved hjelp av API-er på klientsiden.

Viktig

Hvis du brukte gratis prøveversjonstokener for utvikling, må du kjøpe en kapasitet for produksjon. Til en kapasitet er kjøpt, fortsetter banneret for gratis prøveversjon å vises øverst i den innebygde rapporten.

Når appen er klar, kan du flytte den innebygde appen til produksjon.

Relatert innhold

Innebygde analyseprogramtokener

Flytte den innebygde appen til produksjon

Kapasitets- og SKU-er i innebygd analyse med Power BI

Kapasitetsplanlegging i innebygd analyse med Power BI