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

  • Článek

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 embed-for-your-customers.
  • Pomocí instančního objektu.
  • 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 instanční objekt.

  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 na straně klienta vaší aplikace.

  6. Spusťte aplikaci.

Krok 1 : Konfigurace aplikace a instančního objektu Microsoft Entra

V tomto kurzu použijete instanční objekt k ověření webové aplikace na základě ID Microsoft Entra. 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ů instančního objektu vytvořte aplikaci Microsoft Entra a povolte instančnímu objektu aplikace pracovat s obsahem Power BI.

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

K vložení sestavy 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.

Client ID

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

Tajný klíč klienta 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 při prvním zobrazení zkopírujete hodnotu tajného klíče klienta. 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/.

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

Poznámka:

K získání ID pracovního prostoru prostřednictvím kódu programu použijte rozhraní API Získat skupiny .

ID sestavy

Pokud chcete získat identifikátor GUID ID 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.

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

Poznámka:

Id sestavy získáte programově pomocí rozhraní API Získat sestavy ve skupině .

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

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

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

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

  • V sadě Visual Studio přejděte na Nástroje>NuGet Správce balíčků> Správce balíčků konzolu 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 Inicializace Microsoft.Identity.Web ověřovací služby
appsettings.json Konfigurace podrobností o ověřování
PowerBiServiceApi.cs Získání tokenu Microsoft Entra a vkládání metadat
HomeController.cs Předání dat vložení jako modelu do zobrazení

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

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

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

Poznámka:

Kód v ConfigureServices rámci provádění několika důležitých věcí:

  1. Volání AddMicrosoftWebAppCallsWebApi konfiguruje knihovnu Microsoft Authentication Library pro získání přístupových tokenů (tokeny Microsoft Entra).
  2. Volání AddInMemoryTokenCaches konfiguruje mezipaměť tokenů, kterou knihovna Microsoft Authentication Library používá k ukládání přístupových tokenů do mezipaměti a obnovovacích tokenů 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 je ID klienta a tajný klíč klienta. Z bezpečnostníchdůvodůch 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 souboru 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 PowerBi:ServiceRootUrl sledování základní adresy URL služba 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žba 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. Modul runtime .NET Core se postará o 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 konfigurační hodnoty 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 Services vytvořte nový soubor s názvem PowerBiServiceApi.cs.

  3. Do souboru 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 vložení 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. Ve složce Domů zobrazení/vytvořte 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řidání JavaScriptu 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 tématu Vložení sestavy.

V tomto kurzu vytvoříte soubor JavaScriptu s názvem embed.js s objektem konfigurace pro vložení sestavy, která 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.Allje , models.TokenType.Aada models.ViewMode.View.

Funkce powerbi.embed používá models objekt konfigurace 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 vložených analýz Power BI můžete použít k vylepšení aplikace pomocí rozhraní API na straně klienta.

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

Tokeny vložených analytických aplikací

Přesun vložené aplikace do produkčního prostředí

Kapacita a skladové položky ve vložených analytických možnostech Power BI

Plánování kapacity ve vložených analytických možnostech Power BI