Čítať v angličtine

Zdieľať cez

Kurz: Vloženie zostavy Power BI do aplikácie pre vašu organizáciu

  • Článok

Tento kurz vysvetľuje, ako vložiť zostavu Power BI do aplikácie .NET 5.0 ako súčasť riešenia Vloženie obsahu pre vašu organizáciu (známe aj ako používateľ vlastní údaje). V riešení vkladania obsahu pre organizáciu musia používatelia vašej aplikácie vykonať overenie v službe Power BI pomocou vlastných poverení.

V tomto kurze sa naučíte vkladať:

  • Zostava Power BI
  • V aplikácii na vloženie obsahu pre organizáciu
  • Používanie rozhrania .NET 5.0
  • S knižnicou Microsoft.Identity.Web (táto knižnica je podporovaná aj v .NET Core)

Poznámka

Úplné riešenie použité v tomto kurze je k dispozícii z odkladacieho priestoru GitHub DOTNET5-UserOwnsData-Tutorial .

Požiadavky

  • Licenciu Power BI Pro alebo Premium na používateľa .

    Poznámka

    Riešenie Vloženie obsahu pre organizáciu nie je podporované v kapacitách založených na skladových jednotkách A SKU. SKU A možno použiť iba na riešenie vkladania obsahu pre zákazníkov .

  • Pracovný priestor Služby Power BI so zostavou.

  • Vlastný nájomník Microsoft Entra.

  • Aplikácia Microsoft Entra.

  • Aplikácia radiča zobrazenia modelu .NET Core 5 (MVC).

  • .NET Core 5 SDK (alebo vyššia verzia).

  • Integrované vývojové prostredie (IDE). Odporúčame používať jedno z nasledujúcich prostredí:

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 organizáciu , postupujte podľa týchto krokov:

  1. Konfigurácia aplikácie Microsoft Entra
  2. Získanie hodnôt parametra vkladania
  3. Pridanie požadovaných balíkov NuGet
  4. Povolenie overovania na strane servera
  5. Vytvorenie strany klienta aplikácie
  6. Spustenie aplikácie

Krok 1 – Konfigurácia aplikácie Microsoft Entra

Keď vaša webová aplikácia zavolá službu Power BI, potrebuje token Microsoft Entra na volanie rozhraní REST API služby Power BI a vkladanie položiek služby Power BI, ako sú napríklad zostavy, tabule alebo dlaždice.

Ak nemáte aplikáciu Microsoft Entra, vytvorte si ju pomocou pokynov v téme Registrácia aplikácie Microsoft Entra na používanie so službou Power BI.

Ak chcete nakonfigurovať aplikáciu Microsoft Entra, postupujte podľa pokynov v téme Konfigurácia aplikácie Microsoft Entra.

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.

Do svojej aplikácie pridajte nasledujúce balíky NuGet:

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

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

PowerShell 
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

Ak ste v minulosti použili Microsoft.AspNetCore na overenie, odstráňte tento balík z projektu zadaním textu:

PowerShell 
dotnet remove package Microsoft.AspNetCore.Authentication.AzureAD.UI

Krok 4 – povoľte overovanie na strane servera

Povoľte 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 Podrobnosti o overení
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 úryvok kódu.

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žije 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.
C# 
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();

    }
  }
}

Vytvorenie súboru s podrobnosťami overovania

V tomto kurze appsettings.json súbor obsahuje citlivé informácie, ako napríklad ID klienta a tajný kľúč klienta. Z bezpečnostných dôvodov neodporúčame ponechať tieto informácie v súbore nastavení. Pri vkladaní do aplikácie zvážte bezpečnejšiu metódu, ako je napríklad služba Azure Key Vault na zachovanie týchto informácií.

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

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

    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": "*"
}

  3. Vyplňte hodnoty parametra vkladania získané z kroku 2 – získanie hodnôt parametra vkladania.

Poznámka

V predchádzajúcom úryvku kódu PowerBi:ServiceRootUrl sa parameter pridá ako vlastná konfigurateľná hodnota na sledovanie základnej URL adresy na služba Power BI. Pri programovaní v služba Power BI vo verejnom cloude spoločnosti Microsoft je https://api.powerbi.com/URL adresa . Koreňová URL adresa služba Power BI sa však bude líšiť v iných cloudoch, napríklad v cloude pre štátnu správu. Preto je táto hodnota uložená ako hodnota konfigurácie projektu, takže sa v prípade potreby ľahko zmení.

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

Na vkladanie obsahu služby Power BI (napríklad zostáv a tabúľ) musí vaša aplikácia 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 pridať parameter konštruktora pre túto službu a modul runtime rozhrania .NET Core sa stará o odovzdanie inštancie služby v čase spustenia. V tomto prípade konštruktor vstrekuje inštanciu služby konfigurácie .NET Core pomocou IConfiguration parametra, ktorý sa používa na načítanie konfiguračnej PowerBi:ServiceRootUrl hodnoty z appsettings.json. Parameter ITokenAcquisition s názvom tokenAcquisition obsahuje odkaz na službu overovania spoločnosti Microsoft poskytovanú knižnicou Microsoft.Identity.Web a používa sa na získanie prístupových tokenov z identifikátora Microsoft Entra ID.

Pole RequiredScopes obsahuje pole reťazca obsahujúce množinu delegovaných povolení podporovaných rozhraním služba Power BI rozhrania 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 mohlo 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.

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

 }

}

Úprava súboru HomeController.cs

V tomto príklade kódu použijete injekciu závislosti. Ako ste zaregistrovali triedu PowerBiServiceApi ako službu zavolaním services.AddScoped metódy .ConfigureServices Do konštruktora PowerBiServiceApi môžete pridať parameter a modul runtime rozhrania .NET Core sa stará o vytvorenie inštancie PowerBiServiceApi a jej odovzdanie do konštruktora.

V priečinku Controllers otvorte súbor HomeController.cs a pridajte ho do nasledujúceho úryvku kódu:

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

V prípade implementácie na strane klienta je potrebné vytvoriť alebo upraviť súbory 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

Vytvorte súbor Embed.cshtml , ktorý obsahuje div prvok používaný ako kontajner 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 úryvok kódu.

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

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 tejto časti vytvoríte súbor JavaScript s názvom embed.js s konfiguračným objektom na vkladanie zostavy pomocou premennej models.

models sa inicializuje 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 embed.js súboru pridajte nasledujúci úryvok kódu.

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

Po vykonaní všetkých úprav uvedených v tomto kurze ste pripravení spustiť svoju aplikáciu. Spustite aplikáciu a experimentujte so spôsobom vloženia zostavy Power BI. Na vylepšenie aplikácie pomocou rozhraní API na strane klienta môžete použiť klientske rozhrania API vloženej analýzy služby Power BI.

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

Súvisiaci obsah