Samouczek: osadzanie raportu usługi Power BI w aplikacji dla organizacji
W tym samouczku wyjaśniono, jak osadzić raport usługi Power BI w aplikacji .NET 5.0 w ramach rozwiązania osadzania dla organizacji (nazywanego również użytkownikiem jest właścicielem danych). W rozwiązaniu osadzania dla organizacji użytkownicy aplikacji muszą uwierzytelniać się w usłudze Power BI przy użyciu własnych poświadczeń.
Z tego samouczka dowiesz się, jak osadzić:
- Raport usługi Power BI
- W osadzeniu dla aplikacji organizacji
- Korzystanie z platformy .NET 5.0
Microsoft.Identity.WebBiblioteka (ta biblioteka jest również obsługiwana na platformie .NET Core)
Uwaga
Pełne rozwiązanie używane w tym samouczku jest dostępne w repozytorium GitHub DOTNET5-UserOwnsData-Tutorial .
Wymagania wstępne
Licencja usługi Power BI Pro lub Premium na użytkownika (PPU).
Uwaga
Osadzanie dla rozwiązania organizacji nie jest obsługiwane w przypadku pojemności opartych na jednostkach SKU A. Jednostka SKU A może być używana tylko dla rozwiązania osadzania dla klientów .
Obszar roboczy usługi Power BI z raportem.
Aplikacja .NET Core 5 model view controller (MVC).
Zestaw .NET Core 5 SDK (lub nowszy).
Zintegrowane środowisko projektowe (IDE). Zalecamy użycie jednego z następujących środowisk:
- Visual Studio.
- Visual Studio Code (z rozszerzeniem C#).
Zasoby
W tym samouczku użyjesz następujących funkcji:
- Interfejs API raportów REST usługi Power BI — aby osadzić adres URL i pobrać token osadzania.
- Biblioteka uwierzytelniania sieci Web tożsamości firmy Microsoft.
- Interfejsy API klienta osadzonej analizy usługi Power BI — aby osadzić raport.
Method
Aby osadzić zawartość usługi Power BI w rozwiązaniu osadzania dla organizacji , wykonaj następujące kroki:
- Konfigurowanie aplikacji Microsoft Entra
- Pobieranie wartości parametrów osadzania
- Dodawanie wymaganych pakietów NuGet
- Włączanie uwierzytelniania po stronie serwera
- Tworzenie po stronie klienta aplikacji
- Uruchamianie aplikacji
Krok 1. Konfigurowanie aplikacji Microsoft Entra
Gdy aplikacja internetowa wywołuje usługę Power BI, potrzebuje tokenu firmy Microsoft Entra do wywoływania interfejsów API REST usługi Power BI i osadzania elementów usługi Power BI, takich jak raporty, pulpity nawigacyjne lub kafelki.
Jeśli nie masz aplikacji Microsoft Entra, utwórz aplikację, korzystając z instrukcji w temacie Rejestrowanie aplikacji Firmy Microsoft Entra do użycia z usługą Power BI.
Aby skonfigurować aplikację Microsoft Entra, postępuj zgodnie z instrukcjami w temacie Konfigurowanie aplikacji Microsoft Entra.
Krok 2. Pobieranie wartości parametrów osadzania
Aby osadzić raport, potrzebne są następujące wartości:
- Domena
- Identyfikator dzierżawy
- Client ID
- Klucz tajny klienta
- Identyfikator obszaru roboczego
- Identyfikator raportu
Identyfikator domeny i dzierżawy
Jeśli nie znasz domeny lub identyfikatora dzierżawy, zobacz Znajdowanie identyfikatora dzierżawy usługi Microsoft Entra i podstawowej nazwy domeny.
Uwaga
Aby osadzić zawartość dla użytkownika w innej dzierżawie (użytkownik-gość), należy dostosować authorityUri parametr .
Client ID
Aby uzyskać identyfikator GUID klienta (znany również jako identyfikator aplikacji), wykonaj następujące kroki:
Zaloguj się do platformy Microsoft Azure.
Wyszukaj Rejestracje aplikacji i wybierz link Rejestracje aplikacji.
Wybierz aplikację Microsoft Entra używaną do osadzania zawartości usługi Power BI.
W sekcji Przegląd skopiuj identyfikator GUID identyfikatora aplikacji (klienta).
Klucz tajny klienta
Aby uzyskać klucz tajny klienta, wykonaj następujące kroki:
Zaloguj się do platformy Microsoft Azure.
Wyszukaj Rejestracje aplikacji i wybierz link Rejestracje aplikacji.
Wybierz aplikację Microsoft Entra używaną do osadzania zawartości usługi Power BI.
W obszarze Zarządzanie wybierz pozycję Certyfikaty i wpisy tajne.
W obszarze Wpisy tajne klienta wybierz pozycję Nowy klucz tajny klienta.
W oknie podręcznym Dodawanie wpisu tajnego klienta podaj opis wpisu tajnego aplikacji, wybierz, kiedy wpis tajny aplikacji wygaśnie, a następnie wybierz pozycję Dodaj.
W sekcji Wpisy tajne klienta skopiuj ciąg w kolumnie Wartość nowo utworzonego wpisu tajnego aplikacji. Wartość wpisu tajnego klienta to identyfikator klienta.
Uwaga
Pamiętaj, aby skopiować wartość wpisu tajnego klienta po jej pierwszym wyświetleniu. Po odejściu od tej strony wpis tajny klienta zostanie ukryty i nie będzie można pobrać jej wartości.
Identyfikator obszaru roboczego
Aby uzyskać identyfikator GUID identyfikatora obszaru roboczego, wykonaj następujące kroki:
Zaloguj się w usłudze Power BI.
Otwórz raport, który chcesz osadzić.
Skopiuj identyfikator GUID z adresu URL. Identyfikator GUID jest liczbą między /groups/ i /reports/.
Uwaga
Aby programowo uzyskać identyfikator obszaru roboczego, użyj interfejsu API Pobierz grupy .
Identyfikator raportu
Aby uzyskać identyfikator GUID identyfikatora raportu, wykonaj następujące kroki:
Zaloguj się w usłudze Power BI.
Otwórz raport, który chcesz osadzić.
Skopiuj identyfikator GUID z adresu URL. Identyfikator GUID jest liczbą między /reports/ i /ReportSection.
Uwaga
Aby programowo uzyskać identyfikator raportu, użyj interfejsu API Pobierz raporty w grupie .
Krok 3. Dodawanie wymaganych pakietów NuGet
Przed rozpoczęciem należy dodać Microsoft.Identity.Webpakiety i Microsoft.PowerBI.Api NuGet do aplikacji.
Dodaj następujące pakiety NuGet do aplikacji:
W programie VS Code otwórz terminal i wpisz następujący kod.
W programie Visual Studio przejdź do pozycji Narzędzia>NuGet Menedżer pakietów> Menedżer pakietów Console i wpisz następujący kod.
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
Jeśli aplikacja była wcześniej używana Microsoft.AspNetCore do uwierzytelniania, usuń ten pakiet z projektu, wpisując:
dotnet remove package Microsoft.AspNetCore.Authentication.AzureAD.UI
Krok 4. Włączanie uwierzytelniania po stronie serwera
Włącz uwierzytelnianie po stronie serwera w aplikacji, tworząc lub modyfikując pliki w poniższej tabeli.
| Plik | Używanie |
|---|---|
| Startup.cs | Inicjowanie Microsoft.Identity.Web usługi uwierzytelniania |
| appsettings.json | Szczegóły uwierzytelniania |
| PowerBiServiceApi.cs | Pobieranie tokenu Entra firmy Microsoft i osadzanie metadanych |
| HomeController.cs | Przekazywanie danych osadzania jako modelu do widoku |
Konfigurowanie pliku uruchamiania do obsługi Microsoft.Identity.Web
Zmodyfikuj kod w Startup.cs , aby prawidłowo zainicjować usługę uwierzytelniania dostarczaną przez Microsoft.Identity.Webusługę .
Dodaj następujący fragment kodu do pliku Startup.cs aplikacji.
Uwaga
Kod w programie ConfigureServices wykonuje kilka ważnych rzeczy:
- Wywołanie w celu
AddMicrosoftWebAppCallsWebApiskonfigurowania biblioteki uwierzytelniania firmy Microsoft w celu uzyskania tokenów dostępu (tokenów firmy Microsoft Entra). - Wywołanie w celu
AddInMemoryTokenCachesskonfigurowania pamięci podręcznej tokenów używanej przez bibliotekę uwierzytelniania firmy Microsoft do buforowania tokenów dostępu i odświeżania tokenów w tle - Wywołanie w celu
services.AddScoped(typeof(PowerBiServiceApi))skonfigurowaniaPowerBiServiceApiklasy jako klasy usługi, które można dodać do innych klas przy użyciu wstrzykiwania zależności.
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();
}
}
}
Tworzenie pliku szczegółów uwierzytelniania
W tym samouczku appsettings.json plik zawiera poufne informacje, takie jak identyfikator klienta i klucz tajny klienta. Ze względów bezpieczeństwa nie zalecamy przechowywania tych informacji w pliku ustawień. Podczas osadzania w aplikacji należy rozważyć bardziej bezpieczną metodę, taką jak usługa Azure Key Vault , w celu przechowywania tych informacji.
W projekcie utwórz nowy plik i wywołaj go appsettings.json.
Dodaj następujący kod do 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": "*" }Wypełnij wartości parametrów osadzania uzyskane w kroku 2 — Pobierz wartości parametrów osadzania.
Domain- Identyfikator domeny i dzierżawyTenantId- Identyfikator domeny i dzierżawyClientId- Client IDClientSecret- Klucz tajny klienta
Uwaga
W poprzednim fragmencie kodu parametr jest dodawany jako niestandardowa wartość konfiguracji w PowerBi:ServiceRootUrl celu śledzenia podstawowego adresu URL do usługa Power BI. W przypadku programowania względem usługa Power BI w chmurze publicznej firmy Microsoft adres URL to https://api.powerbi.com/. Jednak główny adres URL usługa Power BI będzie inny w innych chmurach, takich jak chmura dla instytucji rządowych. W związku z tym ta wartość jest przechowywana jako wartość konfiguracji projektu, więc w razie potrzeby można ją łatwo zmienić.
Pobierz token dostępu firmy Microsoft Entra i wywołaj usługa Power BI
Aby osadzić zawartość usługi Power BI (np. raporty i pulpity nawigacyjne), aplikacja musi uzyskać token firmy Microsoft Entra. Aby uzyskać token, potrzebny jest obiekt konfiguracji.
Kod w tej sekcji używa wzorca iniekcji zależności platformy .NET Core. Gdy klasa musi używać usługi, możesz dodać parametr konstruktora dla tej usługi, a środowisko uruchomieniowe platformy .NET Core zajmuje się przekazywaniem wystąpienia usługi w czasie wykonywania. W tym przypadku konstruktor wprowadza wystąpienie usługi konfiguracji .NET Core przy użyciu parametru IConfiguration , który służy do pobierania PowerBi:ServiceRootUrl wartości konfiguracji z appsettings.json. Parametr ITokenAcquisition o nazwie tokenAcquisition zawiera odwołanie do usługi uwierzytelniania firmy Microsoft dostarczonej Microsoft.Identity.Web przez bibliotekę i służy do uzyskiwania tokenów dostępu z identyfikatora Entra firmy Microsoft.
Pole RequiredScopes zawiera tablicę ciągów zawierającą zestaw delegowanych uprawnień obsługiwanych przez interfejs API usługa Power BI. Gdy aplikacja wywołuje w sieci, aby uzyskać token firmy Microsoft Entra, przekazuje ten zestaw delegowanych uprawnień, aby identyfikator Entra firmy Microsoft mógł uwzględnić je w zwracanym tokenie dostępu.
Uwaga
Sprawdź, czy aplikacja Microsoft Entra została skonfigurowana z zakresami wymaganymi przez aplikację internetową. Aby uzyskać więcej informacji, zobacz Zmienianie uprawnień aplikacji Microsoft Entra.
W projekcie aplikacji utwórz nowy folder o nazwie Usługi.
W folderze Usługi utwórz nowy plik o nazwie PowerBiServiceApi.cs.
Dodaj następujący kod, aby 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() }; } } }
Modyfikowanie pliku HomeController.cs
W tym przykładzie kodu użyto wstrzykiwania zależności. Podczas rejestrowania PowerBiServiceApi klasy jako usługi przez wywołanie services.AddScoped metody .ConfigureServices Możesz dodać PowerBiServiceApi parametr do konstruktora, a środowisko uruchomieniowe platformy .NET Core zajmuje się tworzeniem PowerBiServiceApi wystąpienia i przekazywaniem go do konstruktora.
W folderze Controllers otwórz plik HomeController.cs i dodaj go do następującego fragmentu kodu:
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 });
}
}
}
Krok 5. Kompilowanie po stronie klienta aplikacji
W przypadku implementacji po stronie klienta należy utworzyć lub zmodyfikować pliki w poniższej tabeli.
| Plik | Używanie |
|---|---|
| embed.js | Zawiera kod JavaScript po stronie klienta |
| Embed.cshtml | Zawiera model obiektów dokumentów aplikacji (DOM) i div na potrzeby osadzania raportu |
Tworzenie kontenera dla osadzonego raportu
Utwórz plik Embed.cshtml, który zawiera div element używany jako kontener dla raportu osadzonego i trzy skrypty.
W folderze Wyświetl>główną utwórz plik o nazwie Embed.cshtml.
Dodaj następujący fragment kodu do pliku 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> }
Dodawanie kodu JavaScript po stronie klienta w celu osadzenia raportu
Aby osadzić zawartość usługi Power BI, należy utworzyć obiekt konfiguracji. Aby dowiedzieć się więcej na temat tworzenia obiektu konfiguracji, zobacz Osadzanie raportu.
W tej sekcji utworzysz plik JavaScript o nazwie embed.js z obiektem konfiguracji do osadzania raportu przy użyciu zmiennej models.
models jest inicjowany przy użyciu wywołania metody window['powerbi-client'].models. Zmienna models służy do ustawiania wartości konfiguracji, takich jak models.Permissions.All, models.TokenType.Aadi models.ViewMode.View.
Funkcja powerbi.embed używa obiektu konfiguracji do osadzania models raportu.
W folderze wwwroot>js utwórz plik o nazwie embed.js.
Dodaj następujący fragment kodu do pliku 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); }); });
Krok 6. Uruchamianie aplikacji
Po wprowadzeniu wszystkich korekt wymienionych w tym samouczku możesz uruchomić aplikację. Wykonaj aplikację i poeksperymentuj ze sposobem osadzania raportu usługi Power BI. Interfejsy API klienta osadzonej analizy usługi Power BI umożliwiają ulepszanie aplikacji przy użyciu interfejsów API po stronie klienta.
Gdy aplikacja będzie gotowa, możesz przenieść aplikację osadzoną do środowiska produkcyjnego.