Udostępnij za pośrednictwem

Samouczek: osadzanie raportu usługi Power BI w aplikacji dla klientów

  • Artykuł

Z tego samouczka dowiesz się, jak osadzić raport usługi Power BI w aplikacji platformy .NET 5.0 w ramach rozwiązania embed-for-your-customers (nazywanego również rozwiązaniem app-owns-data). W rozwiązaniu embed-for-your-customers użytkownicy aplikacji nie muszą logować się do usługi Power BI ani mieć licencji usługi Power BI.

Z tego samouczka dowiesz się, jak osadzić:

  • Raport usługi Power BI.
  • W aplikacji embed-for-your-customers.
  • Za pomocą jednostki usługi.
  • Przy użyciu platformy .NET 5.0.
  • Microsoft.Identity.Web Biblioteka (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-AppOwnsData-Tutorial .

Wymagania wstępne

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 w celu osadzenia raportu.

Metoda

Aby osadzić zawartość usługi Power BI w rozwiązaniu embed-for-your-customers, wykonaj następujące kroki:

  1. Skonfiguruj aplikację Microsoft Entra i jednostkę usługi.

  2. Pobierz wartości parametrów osadzania.

  3. Dodaj wymagane pakiety NuGet.

  4. Włącz uwierzytelnianie po stronie serwera.

  5. Skompiluj stronę klienta aplikacji.

  6. Uruchom aplikację.

Krok 1. Konfigurowanie aplikacji Microsoft Entra i jednostki usługi

W tym samouczku użyjesz jednostki usługi do uwierzytelniania aplikacji internetowej pod kątem identyfikatora Entra firmy Microsoft. Potrzebna jest również aplikacja Microsoft Entra, która umożliwia wygenerowanie tokenu Entra firmy Microsoft. Korzystając z tokenu Firmy Microsoft Entra, aplikacja internetowa może wywoływać interfejsy API REST usługi Power BI i osadzać elementy usługi Power BI, takie jak raporty, pulpity nawigacyjne i kafelki.

Postępuj zgodnie z instrukcjami dotyczącymi jednostki usługi, aby utworzyć aplikację Microsoft Entra i włączyć jednostkę usługi aplikacji do pracy z zawartością usługi Power BI.

Krok 2. Pobieranie wartości parametrów osadzania

Aby osadzić raport, potrzebne są następujące wartości:

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:

  1. Zaloguj się do platformy Microsoft Azure.

  2. Wyszukaj Rejestracje aplikacji i wybierz link Rejestracje aplikacji.

  3. Wybierz aplikację Microsoft Entra używaną do osadzania zawartości usługi Power BI.

  4. W sekcji Przegląd skopiuj identyfikator GUID identyfikatora aplikacji (klienta).

Klucz tajny klienta

Aby uzyskać klucz tajny klienta, wykonaj następujące kroki:

  1. Zaloguj się do platformy Microsoft Azure.

  2. Wyszukaj Rejestracje aplikacji i wybierz link Rejestracje aplikacji.

  3. Wybierz aplikację Microsoft Entra używaną do osadzania zawartości usługi Power BI.

  4. W obszarze Zarządzanie wybierz pozycję Certyfikaty i wpisy tajne.

  5. W obszarze Wpisy tajne klienta wybierz pozycję Nowy klucz tajny klienta.

  6. 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.

  7. 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:

  1. Zaloguj się w usłudze Power BI.

  2. Otwórz raport, który chcesz osadzić.

  3. Skopiuj identyfikator GUID z adresu URL. Identyfikator GUID jest liczbą między /groups/ i /reports/.

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

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:

  1. Zaloguj się w usłudze Power BI.

  2. Otwórz raport, który chcesz osadzić.

  3. Skopiuj identyfikator GUID z adresu URL. Identyfikator GUID jest liczbą między /reports/ i /ReportSection.

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

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 wymagane pakiety NuGet do aplikacji:

  • W programie VS Code otwórz terminal i wprowadź 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
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api

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 Konfigurowanie szczegółów 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 pliku Startup.cs , aby prawidłowo zainicjować usługę uwierzytelniania dostarczaną przez Microsoft.Identity.Webusługę .

Dodaj następujący kod do pliku Startup.cs aplikacji.

Uwaga

Kod w programie ConfigureServices wykonuje kilka ważnych rzeczy:

  1. Wywołanie w celu AddMicrosoftWebAppCallsWebApi skonfigurowania biblioteki uwierzytelniania firmy Microsoft w celu uzyskania tokenów dostępu (tokenów firmy Microsoft Entra).
  2. Wywołanie w celu AddInMemoryTokenCaches skonfigurowania pamięci podręcznej tokenów używanej przez bibliotekę Microsoft Authentication Library do buforowania tokenów dostępu i odświeżania tokenów w tle.
  3. Wywołanie w celu services.AddScoped(typeof(PowerBiServiceApi)) skonfigurowania PowerBiServiceApi klasy jako klasy usługi, którą można dodać do innych klas za pomocą wstrzykiwania zależności.
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();
            });
        }
    }
}

Tworzenie pliku szczegółów uwierzytelniania

W tym samouczku plik appsettings.json 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 rozważ bezpieczniejsze narzędzie, takie jak usługa Azure Key Vault, w celu zabezpieczenia poufnych informacji.

  1. W projekcie utwórz nowy plik i nadaj mu nazwę appsettings.json.

  2. Dodaj następujący kod do pliku 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. Wypełnij wartości parametrów osadzania uzyskane w kroku 2 — Pobierz wartości parametrów osadzania.

Uwaga

W poprzednim kodzie parametr jest dodawany jako wartość konfiguracji niestandardowej 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 różni się w innych chmurach, takich jak chmura dla instytucji rządowych. W związku z tym wartość konfiguracji niestandardowej jest przechowywana jako wartość konfiguracji projektu, więc można ją zmienić zgodnie z potrzebami.

Pobierz token dostępu firmy Microsoft Entra i wywołaj usługa Power BI

Aby osadzić zawartość usługi Power BI, na przykład raporty i pulpity nawigacyjne, aplikacja musi uzyskać token entra firmy Microsoft. 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. Ś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 pliku appsettings.json. Parametr ITokenAcquisition o nazwie tokenAcquisitionzawiera odwołanie do usługi uwierzytelniania firmy Microsoft dostarczonej przez bibliotekę Microsoft.Identity.Web . Parametr służy do uzyskiwania ITokenAcquisition 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.

  1. W projekcie aplikacji utwórz nowy folder o nazwie Usługi.

  2. W folderze Usługi utwórz nowy plik o nazwie PowerBiServiceApi.cs.

  3. Dodaj następujący kod do pliku 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
            };
        }

    }
}

Modyfikowanie pliku HomeController.cs

W tym przykładzie kodu użyjesz iniekcji zależności, aby zmodyfikować plik HomeController.cs . Wykonując poprzedni krok, skonfigurowano PowerBiServiceApi klasę jako usługę przez wywołanie services.AddScoped metody .ConfigureServices W tym kodzie dodajesz PowerBiServiceApi parametr do konstruktora, a środowisko uruchomieniowe platformy .NET Core tworzy PowerBiServiceApi wystąpienie i przekazuje je do konstruktora.

W folderze Controllers otwórz plik HomeController.cs i dodaj do niego następujący kod:

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

Krok 5. Kompilowanie po stronie klienta aplikacji

W przypadku implementacji po stronie klienta należy utworzyć lub zmodyfikować pliki wymienione 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 do osadzania raportu

Tworzenie kontenera dla osadzonego raportu

W tym samouczku utworzysz plik Embed.cshtml , który zawiera div element, który jest kontenerem dla osadzonego raportu i trzy skrypty.

  1. W folderze Wyświetl/głównąutwórz plik o nazwie Embed.cshtml.

  2. Dodaj następujący kod do pliku 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>
}

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 tym samouczku utworzysz plik JavaScript o nazwie embed.js z obiektem konfiguracji do osadzania raportu, który używa zmiennej models.

Można zainicjować models za pomocą 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.

  1. W folderze wwwroot/js utwórz plik o nazwie embed.js.

  2. Dodaj następujący kod do pliku 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);
    });

  });

Krok 6. Uruchamianie aplikacji

Po wykonaniu wszystkich poprzednich kroków możesz uruchomić aplikację. Spróbuj uruchomić 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.

Ważne

Jeśli do programowania użyto bezpłatnych tokenów osadzania wersji próbnej, musisz kupić pojemność dla środowiska produkcyjnego. Do momentu zakupu pojemności baner Wersji bezpłatnej wersji próbnej będzie nadal wyświetlany w górnej części osadzonego raportu.

Gdy aplikacja będzie gotowa, możesz przenieść aplikację osadzoną do środowiska produkcyjnego.

Powiązana zawartość

Tokeny aplikacji osadzonej analizy

Przenoszenie osadzonej aplikacji do środowiska produkcyjnego

Pojemność i jednostki SKU w osadzonej analizie usługi Power BI

Planowanie pojemności w osadzonej analizie usługi Power BI