Opplæring: Bygge inn en Power BI-rapport i et program for organisasjonen
Denne opplæringen forklarer hvordan du bygger inn en Power BI-rapport i et .NET 5.0-program, som en del av innebyggingsløsningen for organisasjonen (også kjent som bruker eier data). I en innebygging for organisasjonsløsningen må appbrukerne godkjenne mot Power BI med sin egen legitimasjon.
I denne opplæringen lærer du hvordan du bygger inn:
- En Power BI-rapport
- I en innebygging for organisasjonsappen
- Bruke .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-UserOwnsData-Tutorial GitHub-repositoriet.
Forutsetning
En Lisens for Power BI Pro eller Premium per bruker (PPU ).
Merk
Innebygging for organisasjonsløsningen støttes ikke på kapasiteter basert på A SKU-er. En SKU kan bare brukes til innebygging for kundenes løsning.
Et Power BI-arbeidsområde med en rapport.
Din egen Microsoft Entra-leier.
En .NET Core 5-modellvisningskontrollør (MVC)-app.
.NET Core 5 SDK (eller nyere).
Et integrert utviklingsmiljø (IDE). Vi anbefaler at du bruker ett av følgende miljøer:
Ressurser
I denne opplæringen bruker du:
- Power BI REST Reports API – for å bygge inn nettadressen og hente innebyggingstokenet.
- Godkjenningsbibliotek for Microsoft Identity Web.
- Klient-API-er for innebygd analyse i Power BI – for å bygge inn rapporten.
Metode
Følg disse trinnene for å bygge inn Power BI-innhold i en innebygging for organisasjonsløsningen :
- Konfigurere Microsoft Entra-appen
- Hent parameterverdiene for innebygging
- Legg til de nødvendige NuGet-pakkene
- Aktiver godkjenning på serversiden
- Bygg appens klientside
- Kjør programmet
Trinn 1 – Konfigurer Microsoft Entra-appen
Når nettappen kaller Opp Power BI, trenger den et Microsoft Entra-token for å kalle Power BI REST-API-er og bygge inn Power BI-elementer som rapporter, instrumentbord eller fliser.
Hvis du ikke har en Microsoft Entra-app, kan du opprette en ved hjelp av instruksjonene i Registrer et Microsoft Entra-program som skal brukes med Power BI.
Hvis du vil konfigurere Microsoft Entra-appen, følger du instruksjonene i Konfigurer Microsoft Entra-appen.
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 (en gjestebruker), må du justere parameteren authorityUri
.
Client ID
Følg disse trinnene for å få GUID-en for klient-ID (også kjent som program-ID):
Logg på Microsoft Azure.
Søk etter appregistreringer, og velg appregistreringskoblingen.
Velg Microsoft Entra-appen du bruker til å bygge inn Power BI-innholdet.
Kopier GUID-en for program-ID (klient) fra oversiktsdelen.
Klienthemmelighet
Følg disse trinnene for å få klienthemmeligheten:
Logg på Microsoft Azure.
Søk etter appregistreringer, og velg appregistreringskoblingen.
Velg Microsoft Entra-appen du bruker til å bygge inn Power BI-innholdet.
Velg Sertifikater og hemmeligheter under Administrer.
Velg Ny klienthemmelighet under Klienthemmeligheter.
Angi en beskrivelse for programhemmeligheten i popup-vinduet Legg til en klienthemmelighet , velg når programhemmeligheten utløper, og velg Legg til.
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:
Logg på Power BI-tjenesten.
Åpne rapporten du vil bygge inn.
Kopier GUIDen fra URL-adressen. GUID-en er tallet mellom /groups/ og /reports/.
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:
Logg på Power BI-tjenesten.
Åpne rapporten du vil bygge inn.
Kopier GUIDen fra URL-adressen. GUID-en er tallet mellom /reports/ og /ReportSection.
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 begynner, må du legge Microsoft.Identity.Web
til , og Microsoft.PowerBI.Api
NuGet-pakkene i appen.
Legg til følgende NuGet-pakker i appen:
Åpne en terminal i VS Code, og skriv inn 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 -v 0.3.0-preview
dotnet add package Microsoft.Identity.Web.UI -v 0.3.0-preview
dotnet add package Microsoft.PowerBI.Api
Hvis appen tidligere ble brukt Microsoft.AspNetCore
til å godkjenne, fjerner du denne pakken fra prosjektet ved å skrive:
dotnet remove package Microsoft.AspNetCore.Authentication.AzureAD.UI
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 | 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 kodesnutt i appens Startup.cs-fil .
Merk
Koden i ConfigureServices
oppnår flere viktige ting:
- Kallet for å
AddMicrosoftWebAppCallsWebApi
konfigurere Microsoft Authentication Library til å skaffe tilgangstokener (Microsoft Entra-tokener). - Kallet for å
AddInMemoryTokenCaches
konfigurere en tokenbuffer som Microsoft Authentication Library skal bruke til å bufre tilgangstokener og oppdateringstokener bak kulissene - Kallet for å
services.AddScoped(typeof(PowerBiServiceApi))
konfigurere klassen som en tjenesteklasse som kan legges til i andre klasser ved hjelp av avhengighetsinjeksjonPowerBiServiceApi
.
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();
}
}
}
Opprette en fil med godkjenningsdetaljer
I denne opplæringen appsettings.json
inneholder 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 en sikrere metode, for eksempel Azure Key Vault , for å beholde denne informasjonen.
Opprett en ny fil i prosjektet, og kall den appsettings.json.
Legg til følgende kode i 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": "*" }
Fyll ut parameterverdiene for innebygging hentet fra trinn 2 – Hent parameterverdiene for innebygging.
Domain
- Domene- og leier-IDTenantId
- Domene- og leier-IDClientId
- Klient-IDClientSecret
- Klienthemmelighet
Merk
I den forrige kodesnutten 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 vil imidlertid være forskjellig i andre skyer, for eksempel offentlig sky. Derfor lagres denne verdien som en prosjektkonfigurasjonsverdi, slik at den er enkel å endre når det er nødvendig.
Hent tilgangstokenet for Microsoft Entra, og kall Power Bi-tjeneste
Hvis du vil bygge inn Power BI-innhold (for eksempel 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, og .NET Core-kjøretiden tar seg av å sende tjenesteforekomsten ved kjøretid. I dette tilfellet injiserer konstruktøren 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, og brukes til å skaffe tilgangstokener fra Microsoft Entra ID.
Feltet RequiredScopes
inneholder en strengmatrise som inneholder et sett med delegerte tillatelser som støttes av API-en Power Bi-tjeneste. Når programmet ringer over nettverket for å skaffe et Microsoft Entra-token, sender dette settet med delegerte tillatelser slik at Microsoft Entra ID kan inkludere dem i tilgangstokenet den 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.
Opprett en ny mappe med tittelen Tjenester i appens prosjekt.
Opprett en ny fil med tittelen PowerBiServiceApi.cs i Tjeneste-mappen.
Legg til følgende kode i 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() }; } } }
Endre HomeController.cs-filen
I dette kodeeksemplet bruker du avhengighetsinjeksjon. Da du registrerte PowerBiServiceApi
klassen som en tjeneste ved å ringe services.AddScoped
inn ConfigureServices
metoden. Du kan legge til en PowerBiServiceApi
parameter i konstruktøren, og .NET Core-kjøretiden tar seg av å opprette en PowerBiServiceApi
forekomst og sende den til konstruktøren.
Åpne HomeController.cs-filen fra Kontroller-mappen, og legg den til i følgende kodesnutt:
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 });
}
}
}
Trinn 5 – bygg appens klientside
For implementering på klientsiden må du opprette eller endre filene i tabellen nedenfor.
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
Opprett Embed.cshtml-filen, som har et div
element som brukes som en beholder for den innebygde rapporten, og tre skript.
Opprett en fil kalt Embed.cshtml i Mappen Vis>hjem.
Legg til følgende kodesnutt i Embed.cshtml-filen .
@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> }
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 delen oppretter du en JavaScript-fil med navnet embed.js med et konfigurasjonsobjekt for innebygging av rapporten ved hjelp av variabelen models
.
models
initialiseres ved hjelp av et kall til window['powerbi-client'].models
. Variabelen models
brukes til å angi konfigurasjonsverdier som models.Permissions.All
, models.TokenType.Aad
og models.ViewMode.View
.
Funksjonen powerbi.embed
bruker konfigurasjonsobjektet models
til å bygge inn rapporten.
Opprett en fil kalt embed.js i wwwroot>js-mappen.
Legg til følgende kodesnutt i embed.js-filen .
$(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); }); });
Trinn 6 – Kjør programmet
Når du har gjort alle justeringene som er oppført i denne opplæringen, er du klar til å kjøre programmet. Utfør 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.
Når appen er klar, kan du flytte den innebygde appen til produksjon.