Zdieľať cez

Kurz: Vloženie zostavy Power BI do aplikácie pre vašich zákazníkov

  • Článok

V tomto kurze sa naučíte vkladať zostavy Power BI do aplikácie .NET 5.0 ako súčasť riešenia vkladania pre zákazníkov (známe aj ako riešenie vlastnené aplikáciou). V riešení vkladania obsahu pre zákazníkov sa používatelia vašej aplikácie nemusia prihlasovať do služby Power BI ani mať licenciu na Power BI.

V tomto kurze sa naučíte vkladať:

  • Zostava Power BI.
  • V aplikácii embed-for-your-customers (vloženie pre zákazníkov).
  • Pomocou objektu služby.
  • Pomocou rozhrania .NET 5.0.
  • S knižnicou Microsoft.Identity.Web (táto knižnica je podporovaná aj v rozhraní .NET Core).

Poznámka

Úplné riešenie použité v tomto kurze je k dispozícii z odkladacieho priestoru GitHub v rámci služby DOTNET5-AppOwnsData-Tutorial .

Požiadavky

Zdroje informácií

V tomto kurze použijete:

  • Rozhranie Rest Reports API služby Power BI na vloženie URL adresy a načítanie vkladacieho tokenu.

  • Knižnica overenia identity webu spoločnosti Microsoft.

  • Klientske rozhrania API vloženej analýzy služby Power BI na vloženie zostavy.

Metóda

Ak chcete vložiť obsah služby Power BI do riešenia Vloženie obsahu pre zákazníkov, postupujte podľa týchto krokov:

  1. Nakonfigurujte svoju aplikáciu Microsoft Entra a objekt služby.

  2. Získajte hodnoty parametra vkladania.

  3. Pridajte požadované balíky NuGet.

  4. Povoľte overovanie na strane servera.

  5. Vytvorte stranu klienta svojej aplikácie.

  6. Spustite aplikáciu.

Krok 1 – Konfigurácia aplikácie Microsoft Entra a objektu služby

V tomto kurze použijete objekt služby na overenie webovej aplikácie pomocou ID služby Microsoft Entra. Potrebujete tiež aplikáciu Microsoft Entra, ktorá umožňuje vygenerovať token Microsoft Entra. Pomocou tokenu Microsoft Entra môže vaša webová aplikácia volať rozhrania REST API služby Power BI a vkladať položky služby Power BI, ako sú napríklad zostavy, tabule a dlaždice.

Postupujte podľa pokynov pre objekt služby, vytvorte aplikáciu Microsoft Entra a povoľte objektu služby aplikácie pracovať s obsahom služby Power BI.

Krok 2 – získajte hodnoty parametra vkladania

Ak chcete vložiť zostavu, potrebujete nasledujúce hodnoty:

ID domény a nájomníka

Ak nepoznáte svoju doménu alebo ID nájomníka, pozrite si tému Vyhľadanie ID nájomníka microsoft Entra a názvu primárnej domény.

Poznámka

Ak chcete vložiť obsah pre používateľa do iného nájomníka (hosťovského používateľa), je potrebné upraviť authorityUri parameter.

ID klienta

Ak chcete načítať identifikátor ID GUID klienta (známy aj ako ID aplikácie), postupujte podľa týchto krokov:

  1. Prihláste sa do služby Microsoft Azure.

  2. Vyhľadajte položku App registrations (Registrácie aplikácií ) a vyberte prepojenie App registrations (Registrácie aplikácií ).

  3. Vyberte aplikáciu Microsoft Entra, ktorú používate na vkladanie obsahu služby Power BI.

  4. V časti Prehľad skopírujte identifikátor GUID ID aplikácie (klienta) .

Tajný kľúč klienta

Ak chcete získať tajný kľúč klienta, postupujte podľa týchto krokov:

  1. Prihláste sa do služby Microsoft Azure.

  2. Vyhľadajte položku App registrations (Registrácie aplikácií ) a vyberte prepojenie App registrations (Registrácie aplikácií ).

  3. Vyberte aplikáciu Microsoft Entra, ktorú používate na vkladanie obsahu služby Power BI.

  4. V časti Spravovať vyberte položku Certifikáty a tajné kódy.

  5. V časti Client secrets (Tajné kódy klienta) vyberte položku New client secret ( Nový tajný kľúč klienta).

  6. Do kontextového okna Pridanie tajného kľúča klienta zadajte popis tajného kľúča vašej aplikácie, vyberte dátum ukončenia jeho platnosti a vyberte položku Pridať.

  7. V časti Client secrets (Tajné kódy klienta) skopírujte reťazec v stĺpci Value (Hodnota) novovytvoreného tajného kľúča aplikácie. Hodnota tajného kľúča klienta je vašim ID klienta.

Poznámka

Uistite sa, že ste skopírovali hodnotu tajného kľúča klienta pri jej prvom zobrazení. Po prechode z tejto stránky sa tajný kľúč klienta skryje a nebudete môcť načítať jeho hodnotu.

ID pracovného priestoru

Ak chcete načítať identifikátor ID GUID pracovného priestoru, postupujte podľa týchto krokov:

  1. Prihláste sa do služba Power BI.

  2. Otvorte zostavu, ktorú chcete vložiť.

  3. Skopírujte identifikátor GUID z URL adresy. Identifikátor GUID je číslo medzi položkami /groups/ a /reports/.

    Snímka obrazovky znázorňujúca identifikátor ID GUID pracovného priestoru v URL adrese služba Power BI

Poznámka

Ak chcete ID pracovného priestoru získať pomocou programovania, použite rozhranie API Načítať skupiny .

ID zostavy

Ak chcete načítať identifikátor ID GUID zostavy, postupujte podľa týchto krokov:

  1. Prihláste sa do služba Power BI.

  2. Otvorte zostavu, ktorú chcete vložiť.

  3. Skopírujte identifikátor GUID z URL adresy. Identifikátor GUID je číslo medzi položkami /reports/ a /ReportSection.

    Snímka obrazovky znázorňujúca identifikátor ID GUID zostavy v URL adrese služby Power BI

Poznámka

Ak chcete ID zostavy získať pomocou programovania, použite rozhranie API Získať zostavy v skupine .

Krok 3 – Pridajte požadované balíky NuGet

Skôr než začnete, musíte do svojej aplikácie pridať Microsoft.Identity.Webbalíky a Microsoft.PowerBI.Api NuGet.

Pridajte požadované balíky NuGet do svojej aplikácie:

  • V nástroji VS Code otvorte terminál a zadajte nasledujúci kód.

  • Vo Visual Studiu prejdite na položku Nástroje>NuGet Správca balíkov> Správca balíkov Konzola a zadajte nasledujúci kód.

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

Krok 4 – povoľte overovanie na strane servera

Zapnite overovanie na strane servera v aplikácii vytvorením alebo úpravou súborov v nasledujúcej tabuľke.

Súbor Použitie
Startup.cs Inicializácia Microsoft.Identity.Web služby overovania
appsettings.json Konfigurácia podrobností overovania
PowerBiServiceApi.cs Získanie tokenu Microsoft Entra a vkladanie metaúdajov
HomeController.cs Odovzdanie vkladania údajov ako modelu do zobrazenia

Konfigurácia súboru pri spustení na podporu Microsoft.Identity.Web

Upravte kód v Startup.cs tak, aby správne inicializoval službu overovania poskytovanú službou Microsoft.Identity.Web.

Do Startup.cs súboru aplikácie pridajte nasledujúci kód.

Poznámka

Kód v ConfigureServices kóde dosahuje niekoľko dôležitých vecí:

  1. Volanie na AddMicrosoftWebAppCallsWebApi konfiguráciu knižnice overenia spoločnosti Microsoft na získanie prístupových tokenov (tokeny Microsoft Entra).
  2. Volanie na AddInMemoryTokenCaches konfiguráciu vyrovnávacej pamäte tokenov, ktorú knižnica overenia spoločnosti Microsoft používa na ukladanie prístupových tokenov do vyrovnávacej pamäte a obnovenie tokenov na pozadí.
  3. Volanie na services.AddScoped(typeof(PowerBiServiceApi)) konfiguráciu PowerBiServiceApi triedy ako triedy služby, ktorú možno pridať do iných tried pomocou injekcie závislosti.
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();
            });
        }
    }
}

Vytvorenie súboru s podrobnosťami overovania

V tomto kurze súbor appsettings.json obsahuje citlivé informácie, ako napríklad ID klienta a tajný kľúč klienta. Z bezpečnostných dôvodov neodporúčame, aby ste si tieto informácie ponechali v súbore nastavení. Pri vkladaní do aplikácie zvážte bezpečnejší nástroj, ako je napríklad služba Azure Key Vault, na zabezpečenie citlivých informácií.

  1. V projekte vytvorte nový súbor a pomenujte ho appsettings.json.

  2. Na appsettings.json pridajte nasledujúci kód:

    {
 "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. Vyplňte hodnoty parametra vkladania získané z kroku 2 – získanie hodnôt parametra vkladania.

Poznámka

V predchádzajúcom kóde PowerBi:ServiceRootUrl sa parameter pridá ako vlastná konfigurateľná hodnota na sledovanie základnej URL adresy na služba Power BI. Keď programujete v služba Power BI vo verejnom cloude spoločnosti Microsoft, URL adresa je https://api.powerbi.com/. Koreňová URL adresa služba Power BI sa však líši v iných cloudoch, napríklad v cloude pre štátnu správu. Preto je vlastná hodnota konfigurácie uložená ako hodnota konfigurácie projektu, takže ju môžete zmeniť podľa potreby.

Získajte prístupový token Microsoft Entra a zavolajte služba Power BI

Ak chcete vložiť obsah služby Power BI, ako sú napríklad zostavy a tabule, vaša aplikácia musí získať token Microsoft Entra. Ak chcete získať token, budete potrebovať konfiguračný objekt.

Kód v tejto časti používa vzor injekcie závislosti .NET Core. Keď vaša trieda potrebuje použiť službu, môžete pre danú službu pridať parameter konštruktora. Modul runtime rozhrania .NET Core sa stará o odovzdanie inštancie služby v čase spustenia. V tomto prípade konštruktor vloží inštanciu konfiguračnej služby .NET Core pomocou IConfiguration parametra, ktorý sa používa na načítanie hodnoty konfigurácie PowerBi:ServiceRootUrl z appsettings.json. Parameter ITokenAcquisition s názvom tokenAcquisition, obsahuje odkaz na službu overovania spoločnosti Microsoft poskytovanú knižnicou Microsoft.Identity.Web . Parameter sa ITokenAcquisition používa na získanie prístupových tokenov z identifikátora Microsoft Entra ID.

Pole RequiredScopes obsahuje pole reťazca, ktoré obsahuje množinu delegovaných povolení podporovaných rozhraním služba Power BI API. Keď vaša aplikácia zavolá cez sieť a získa token Microsoft Entra, odovzdá túto množinu delegovaných povolení, aby ich id Microsoft Entra bolo možné zahrnúť do prístupového tokenu, ktorý vráti.

Poznámka

Overte, či je vaša aplikácia Microsoft Entra nakonfigurovaná s rozsahmi požadovanými webovou aplikáciou. Ďalšie informácie nájdete v téme Zmena povolení aplikácie Microsoft Entra.

  1. V projekte aplikácie vytvorte nový priečinok s názvom Služby.

  2. V priečinku Služby vytvorte nový súbor s názvom PowerBiServiceApi.cs.

  3. Do PowerBiServiceApi.cs pridajte nasledujúci kód.

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

    }
}

Úprava súboru HomeController.cs

V tomto príklade kódu použijete na úpravu súboru HomeController.cs položku dependency injection. Vykonaním predchádzajúceho kroku ste nakonfigurovali triedu PowerBiServiceApi ako službu zavolaním services.AddScoped ConfigureServices metódy . Pomocou tohto kódu pridáte parameter do konštruktora PowerBiServiceApi a modul runtime rozhrania .NET Core vytvorí inštanciu PowerBiServiceApi a odovzdá ju konštruktoru.

V priečinku Controllers otvorte súbor HomeController.cs a pridajte doň nasledujúci kód:

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 – vytvorte stranu klienta aplikácie

Pri implementácii na strane klienta je potrebné vytvoriť alebo upraviť súbory, ktoré sú uvedené v nasledujúcej tabuľke:

Súbor Použitie
embed.js Obsahuje JavaScript kód na strane klienta
Embed.cshtml Obsahuje objektový model dokumentu aplikácie (DOM) a DIV na vkladanie zostavy

Vytvorenie kontajnera pre vloženú zostavu

V tomto kurze vytvoríte súbor Embed.cshtml , ktorý obsahuje div prvok, ktorý je kontajnerom pre vloženú zostavu, a tri skripty.

  1. V priečinku Zobraziť/domov vytvorte súbor s názvom Embed.cshtml.

  2. Do súboru Embed.cshtml pridajte nasledujúci kód.

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

Pridanie JavaScriptu na strane klienta na vloženie zostavy

Ak chcete vložiť obsah služby Power BI, musíte vytvoriť konfiguračný objekt. Ďalšie informácie o vytváraní konfiguračného objektu nájdete v téme Vloženie zostavy.

V tomto kurze vytvoríte súbor JavaScript s názvom embed.js s konfiguračným objektom na vkladanie zostavy, ktorá používa premennú models.

Inicializovať models môžete pomocou volania funkcie window['powerbi-client'].models. Premenná models sa používa na nastavenie hodnôt konfigurácie, ako models.Permissions.Allsú napríklad , models.TokenType.Aada models.ViewMode.View.

Funkcia powerbi.embed používa konfiguračný models objekt na vloženie zostavy.

  1. V priečinku wwwroot/js vytvorte súbor s názvom embed.js.

  2. Do súboru embed.js pridajte nasledujúci kód.

    $(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 – spustite aplikáciu

Po vykonaní všetkých predchádzajúcich krokov ste pripravení na spustenie aplikácie. Skúste aplikáciu spúšťať a experimentujte s tým, ako je zostava Power BI vložená. Na vylepšenie aplikácie môžete použiť klientske rozhrania API vloženej analýzy služby Power BI pomocou rozhraní API na strane klienta.

Dôležité

Ak ste na vývoj používali bezplatné vkladacie skúšobné tokeny, musíte si kúpiť kapacitu na produkciu. Kým si nezakúpite kapacitu, v hornej časti vloženej zostavy sa bude naďalej zobrazovať pruh bezplatnej skúšobnej verzie .

Keď je vaša aplikácia pripravená, môžete vloženú aplikáciu premiestniť do produkcie.

Súvisiaci obsah