Kurz: Vložení sestavy Power BI do aplikace pro zákazníky

V tomto kurzu se dozvíte, jak vložit sestavu Power BI do aplikace .NET 5.0 jako součást řešení pro vložení pro vaše zákazníky (označované také jako řešení app-owns-data). V řešení pro vložení pro vaše zákazníky se uživatelé vaší aplikace nemusí přihlašovat k Power BI ani mít licenci Power BI.

V tomto kurzu se dozvíte, jak vložit:

  • Sestava Power BI
  • V aplikaci pro vkládání obsahu pro vaše zákazníky.
  • Pomocí aplikačního objektu služby.
  • Pomocí .NET 5.0.
  • S knihovnou Microsoft.Identity.Web (tato knihovna je také podporována v .NET Core).

Poznámka:

Úplné řešení použité v tomto kurzu je k dispozici v úložišti GitHubu DOTNET5-AppOwnsData-Tutorial .

Požadavky

Zdroje informací

V tomto kurzu použijete:

metoda

Pokud chcete vložit obsah Power BI do řešení pro vložení pro vaše zákazníky, postupujte takto:

  1. Nakonfigurujte aplikaci Microsoft Entra a hlavní službu.

  2. Získejte hodnoty parametrů pro vložení.

  3. Přidejte požadované balíčky NuGet.

  4. Povolte ověřování na straně serveru.

  5. Sestavte klientskou stranu vaší aplikace.

  6. Spusťte aplikaci.

Krok 1: Konfigurace aplikace a služebního principálu Microsoft Entra

V tomto kurzu použijete service principal k autentizaci vaší webové aplikace proti Microsoft Entra ID. Potřebujete také aplikaci Microsoft Entra, která umožňuje vygenerovat token Microsoft Entra. Pomocí tokenu Microsoft Entra může vaše webová aplikace volat rozhraní REST API Power BI a vkládat položky Power BI, jako jsou sestavy, řídicí panely a dlaždice.

Podle pokynů principálu služby vytvořte aplikaci Microsoft Entra a povolte této aplikaci principála služby pro práci s obsahem Power BI.

Krok 2 – získání hodnot vložených parametrů

K vložení vašeho reportu potřebujete následující hodnoty:

ID domény a tenanta

Pokud neznáte svoji doménu nebo ID tenanta, přečtěte si téma Vyhledání ID tenanta Microsoft Entra a název primární domény.

Poznámka:

Pokud chcete vložit obsah pro uživatele do jiného tenanta (uživatele typu host), musíte upravit authorityUri parametr.

ID klienta

Pokud chcete získat identifikátor GUID ID klienta (označovaný také jako ID aplikace), postupujte takto:

  1. Přihlaste se k Microsoft Azure.

  2. Vyhledejte Registrace aplikací a vyberte odkaz Registrace aplikací.

  3. Vyberte aplikaci Microsoft Entra, kterou používáte pro vložení obsahu Power BI.

  4. V části Přehled zkopírujte identifikátor GUID ID aplikace (klienta).

Tajný klíč klienta

Klientské tajemství získáte takto:

  1. Přihlaste se k Microsoft Azure.

  2. Vyhledejte Registrace aplikací a vyberte odkaz Registrace aplikací.

  3. Vyberte aplikaci Microsoft Entra, kterou používáte pro vložení obsahu Power BI.

  4. V části Spravovat vyberte Certifikáty a tajné kódy.

  5. V části Tajné kódy klienta vyberte Nový tajný klíč klienta.

  6. V automaticky otevírané okně Přidat tajný klíč klienta zadejte popis tajného kódu aplikace, vyberte, kdy vyprší platnost tajného kódu aplikace, a vyberte Přidat.

  7. V části Tajné kódy klienta zkopírujte řetězec ve sloupci Hodnota nově vytvořeného tajného kódu aplikace. Hodnota tajného klíče klienta je VAŠE ID klienta.

Poznámka:

Ujistěte se, že zkopírujete hodnotu tajného klíče klienta, jakmile se poprvé objeví. Po přechodu mimo tuto stránku bude tajný klíč klienta skrytý a nebudete moct načíst jeho hodnotu.

ID pracovního prostoru

Pokud chcete získat identifikátor GUID ID pracovního prostoru, postupujte takto:

  1. Přihlaste se ke službě Power BI.

  2. Otevřete sestavu, kterou chcete vložit.

  3. Zkopírujte identifikátor GUID z adresy URL. Identifikátor GUID je číslo mezi /groups/ a /reports/.

    Snímek obrazovky znázorňující GUID ID pracovního prostoru v adrese URL služby Power BI

Poznámka:

K získání ID pracovního prostoru programově použijte Get Groups API.

ID sestavy

Pokud chcete získat identifikátor GUID sestavy, postupujte takto:

  1. Přihlaste se ke službě Power BI.

  2. Otevřete sestavu, kterou chcete vložit.

  3. Zkopírujte identifikátor GUID z adresy URL. Identifikátor GUID je číslo mezi /reports/ a /ReportSection.

    Snímek obrazovky znázorňující identifikátor GUID sestavy v URL služby Power BI

Poznámka:

Id sestavy můžete získat programaticky pomocí rozhraní API "Get Reports In Group".

Krok 3 : Přidání požadovaných balíčků NuGet

Než začnete, musíte do své aplikace přidat balíček Microsoft.Identity.Web a balíček Microsoft.PowerBI.Api NuGet.

Přidejte do aplikace požadované balíčky NuGet:

  • Ve VS Code otevřete terminál a zadejte následující kód.

  • V Visual Studio přejděte na Nástroje>Správce balíčků NuGet>Konzole správce balíčků a zadejte následující kód.

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

Krok 4 – Povolení ověřování na straně serveru

Zapněte ověřování na straně serveru v aplikaci vytvořením nebo úpravou souborů v následující tabulce.

Soubor Používání
Startup.cs Inicializujte Microsoft.Identity.Web ověřovací službu
appsettings.json Konfigurace údajů pro ověření
PowerBiServiceApi.cs Získání tokenu Microsoft Entra a vkládání metadat
HomeController.cs Předat data vkládání jako model do zobrazení

Konfigurace spouštěcího souboru pro podporu Microsoft.Identity.Web

Upravte kód v Startup.cs tak, aby správně inicializoval ověřovací službu poskytovanou Microsoft.Identity.Web.

Do souboru Startup.cs aplikace přidejte následující kód.

Poznámka:

Kód v ConfigureServices dosahuje několika důležitých úkolů:

  1. Volání AddMicrosoftWebAppCallsWebApi konfiguruje knihovnu Microsoft Authentication Library k získání přístupových tokenů (tokenů Microsoft Entra).
  2. Volání AddInMemoryTokenCaches konfiguruje mezipaměť tokenů, kterou knihovna Microsoft Authentication Library používá k ukládání přístupových a obnovovacích tokenů do mezipaměti na pozadí.
  3. Volání services.AddScoped(typeof(PowerBiServiceApi)) konfiguruje PowerBiServiceApi třídu jako třídu služby, kterou lze přidat do jiných tříd pomocí injektáže závislostí.
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();
            });
        }
    }
}

Vytvoření souboru s podrobnostmi o ověřování

V tomto kurzu soubor appsettings.json obsahuje citlivé informace, jako ID klienta a tajemství klienta. Z bezpečnostních důvodů nedoporučujeme uchovávat tyto informace v souboru nastavení. Při vkládání do aplikace zvažte bezpečnější nástroj, jako je Azure Key Vault, pro zabezpečení citlivých informací.

  1. V projektu vytvořte nový soubor a pojmenujte ho appsettings.json.

  2. Do appsettings.json přidejte následující 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 vložených parametrů získané z kroku 2 – Získání hodnot vložených parametrů.

Poznámka:

V předchozím kódu se parametr přidá jako vlastní konfigurační hodnota pro sledování základní adresy URL služby Power BI. Když programujete proti služba Power BI ve veřejném cloudu Microsoftu, adresa URL je https://api.powerbi.com/. Kořenová adresa URL služba Power BI se ale liší v jiných cloudech, jako je cloud státní správy. Proto je vlastní hodnota konfigurace uložena jako hodnota konfigurace projektu, takže ji můžete podle potřeby změnit.

Získání přístupového tokenu Microsoft Entra a volání služby Power BI

Aby bylo možné vkládat obsah Power BI, jako jsou sestavy a řídicí panely, musí vaše aplikace získat token Microsoft Entra. K získání tokenu potřebujete objekt konfigurace.

Kód v této části používá model injektáže závislostí .NET Core. Pokud vaše třída potřebuje použít službu, můžete pro tuto službu přidat parametr konstruktoru. Běhové prostředí .NET Core zajišťuje předání instance služby za běhu. V tomto případě konstruktor vloží instanci konfigurační služby .NET Core pomocí parametru IConfiguration , který se používá k načtení PowerBi:ServiceRootUrl hodnoty konfigurace z appsettings.json. Parametr ITokenAcquisition , který je pojmenován tokenAcquisition, obsahuje odkaz na ověřovací službu Microsoftu poskytovanou knihovnou Microsoft.Identity.Web . Tento ITokenAcquisition parametr se používá k získání přístupových tokenů z ID Microsoft Entra.

Pole RequiredScopes obsahuje pole řetězců, které obsahuje sadu delegovaných oprávnění podporovaných rozhraním API služba Power BI. Když vaše aplikace volá přes síť k získání tokenu Microsoft Entra, předá tuto sadu delegovaných oprávnění, aby je Microsoft Entra ID mohl zahrnout do přístupového tokenu, který vrátí.

Poznámka:

Ověřte, že je vaše aplikace Microsoft Entra nakonfigurovaná s obory vyžadovanými vaší webovou aplikací. Další informace najdete v tématu Změna oprávnění aplikace Microsoft Entra.

  1. V projektu aplikace vytvořte novou složku s názvem Služby.

  2. Ve složce Služby vytvořte nový soubor s názvem PowerBiServiceApi.cs.

  3. Do PowerBiServiceApi.cs přidejte následující 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 souboru HomeController.cs

V tomto příkladu kódu použijete injektáž závislostí k úpravě souboru HomeController.cs . Podle předchozího kroku jste nakonfigurovali PowerBiServiceApi třídu jako službu voláním services.AddScoped metody ConfigureServices . S tímto kódem přidáte do konstruktoru PowerBiServiceApi parametr a modul runtime .NET Core vytvoří PowerBiServiceApi instanci a předá ji konstruktoru.

Ve složce Controllers otevřete soubor HomeController.cs a přidejte do něj následující 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 : Sestavení klientské strany aplikace

Pro implementaci na straně klienta je potřeba vytvořit nebo upravit soubory uvedené v následující tabulce:

Soubor Používání
embed.js Obsahuje kód JavaScriptu na straně klienta.
Embed.cshtml Obsahuje objektový model dokumentu vaší aplikace (DOM) a DIV pro integraci sestavy.

Vytvoření kontejneru pro vloženou sestavu

V tomto kurzu vytvoříte soubor Embed.cshtml , který obsahuje div element, který je kontejnerem pro vloženou sestavu, a tři skripty.

  1. Vytvořte v složce View/Home soubor s názvem Embed.cshtml.

  2. Do souboru Embed.cshtml přidejte následující 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>
}

Přidejte JavaScript na straně klienta pro vložení sestavy

Pokud chcete vložit obsah Power BI, musíte vytvořit objekt konfigurace. Další informace o vytvoření objektu konfigurace najdete v Vložení sestavy.

V tomto kurzu vytvoříte JavaScriptový soubor s názvem embed.js, který obsahuje konfigurační objekt pro vložení vaší zprávy, a ten používá proměnnou models.

Inicializovat models můžete pomocí volání window['powerbi-client'].models. Proměnná models se používá k nastavení konfiguračních hodnot, jako models.Permissions.All, models.TokenType.Aad a models.ViewMode.View.

Funkce powerbi.embed používá konfigurační objekt models k vložení sestavy.

  1. Ve složce wwwroot/js vytvořte soubor s názvem embed.js.

  2. Do souboru embed.js přidejte následující 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 : Spuštění aplikace

Po provedení všech předchozích kroků jste připraveni spustit aplikaci. Zkuste spustit aplikaci a experimentujte se způsobem, jakým je sestava Power BI vložená. Klientská rozhraní API pro vloženou analýzu Power BI můžete využít k vylepšení své aplikace pomocí klientských API.

Důležité

Pokud jste pro vývoj použili bezplatné zkušební tokeny pro vložení, musíte si koupit kapacitu pro produkční prostředí. Dokud není zakoupena kapacita, bude se v horní části vložené sestavy zobrazovat banner bezplatné zkušební verze .

Až bude vaše aplikace připravená, můžete vloženou aplikaci přesunout do produkčního prostředí.

Související obsah

  • Last updated on