Megosztás a következőn keresztül:

Oktatóanyag: Power BI-jelentés beágyazása egy alkalmazásba az ügyfelek számára

  • Cikk

Ebben az oktatóanyagban megtudhatja, hogyan ágyazhat be Power BI-jelentéseket egy .NET 5.0-alkalmazásba az ügyfeleknek készült beágyazási (más néven alkalmazástulajdon-adatok) megoldás részeként. Az ügyfeleknek szánt beágyazási megoldásban az alkalmazás felhasználóinak nem kell bejelentkeznie a Power BI-ba, vagy Power BI-licenccel kell rendelkezniük.

Ebben az oktatóanyagban megtudhatja, hogyan ágyazhat be:

  • Power BI-jelentés.
  • Az ügyfeleknek készült beágyazási alkalmazásban.
  • Szolgáltatásnév használatával.
  • A .NET 5.0 használatával.
  • Microsoft.Identity.Web A kódtár használatával (ez a kódtár a .NET Core-ban is támogatott).

Feljegyzés

Az oktatóanyagban használt teljes megoldás a DOTNET5-AppOwnsData-Tutorial GitHub-adattárból érhető el.

Előfeltételek

Források

Ebben az oktatóanyagban a következőket használja:

Metódus

Ha Power BI-tartalmakat szeretne beágyazni egy ügyfeleknek készült beágyazási megoldásba, kövesse az alábbi lépéseket:

  1. Konfigurálja a Microsoft Entra-alkalmazást és -szolgáltatásnevet.

  2. Kérje le a beágyazási paraméter értékeit.

  3. Adja hozzá a szükséges NuGet-csomagokat.

  4. Kiszolgálóoldali hitelesítés engedélyezése.

  5. Hozza létre az alkalmazás ügyféloldalát.

  6. Futtassa az alkalmazást.

1. lépés – A Microsoft Entra alkalmazás és szolgáltatásnév konfigurálása

Ebben az oktatóanyagban egy szolgáltatásnév használatával hitelesíti a webalkalmazást a Microsoft Entra ID azonosítójával. Szüksége van egy Microsoft Entra-alkalmazásra is, amely lehetővé teszi a Microsoft Entra-jogkivonat létrehozásához. A Microsoft Entra-jogkivonat használatával a webalkalmazás meghívhatja a Power BI REST API-kat, és beágyazhatja a Power BI-elemeket, például jelentéseket, irányítópultokat és csempéket.

A szolgáltatásnév utasításait követve hozzon létre egy Microsoft Entra-alkalmazást, és engedélyezze az alkalmazás szolgáltatásnévének használatát a Power BI-tartalommal.

2. lépés – A beágyazási paraméter értékeinek lekérése

A jelentés beágyazásához a következő értékekre van szüksége:

Tartomány- és bérlőazonosító

Ha nem ismeri a tartományát vagy a bérlőazonosítóját, olvassa el a Microsoft Entra-bérlőazonosító és az elsődleges tartománynév megkeresése című témakört.

Feljegyzés

Ha egy felhasználó tartalmat szeretne beágyazni egy másik bérlőbe (vendégfelhasználóba), módosítania kell a paramétert authorityUri .

Ügyfél azonosítója

Az ügyfélazonosító GUID-azonosítójának (más néven alkalmazásazonosítónak) lekéréséhez kövesse az alábbi lépéseket:

  1. Jelentkezzen be a Microsoft Azure-ba.

  2. Keresse meg a Alkalmazásregisztrációk, és válassza a Alkalmazásregisztrációk hivatkozást.

  3. Válassza ki a Power BI-tartalmak beágyazásához használt Microsoft Entra-alkalmazást.

  4. Az Áttekintés szakaszban másolja ki az alkalmazás (ügyfél) azonosítójának GUID azonosítóját.

Titkos ügyfélkód

Az ügyfél titkos kódjának lekéréséhez kövesse az alábbi lépéseket:

  1. Jelentkezzen be a Microsoft Azure-ba.

  2. Keresse meg a Alkalmazásregisztrációk, és válassza a Alkalmazásregisztrációk hivatkozást.

  3. Válassza ki a Power BI-tartalmak beágyazásához használt Microsoft Entra-alkalmazást.

  4. A Kezelés területen válassza a Tanúsítványok és titkos kódok lehetőséget.

  5. Az Ügyfélkódok csoportban válassza az Új ügyfélkulcs lehetőséget.

  6. Az Ügyfélkód hozzáadása előugró ablakban adja meg az alkalmazás titkos kódjának leírását, jelölje ki az alkalmazás titkos kódjának lejárati dátumát, és válassza a Hozzáadás lehetőséget.

  7. Az Ügyfél titkos kulcsok szakaszból másolja ki az újonnan létrehozott alkalmazáskulcs Érték oszlopában lévő sztringet. Az ügyfél titkos kódjának értéke az ügyfél azonosítója.

Feljegyzés

Győződjön meg arról, hogy az ügyfél titkos kódjának értékét az első megjelenésekor másolja. A lapról való navigálás után az ügyfél titkos kódja el lesz rejtve, és nem fogja tudni lekérni az értékét.

Munkaterület azonosítója

A munkaterület azonosítójának GUID-azonosítójának lekéréséhez kövesse az alábbi lépéseket:

  1. Jelentkezzen be a Power BI szolgáltatás.

  2. Nyissa meg a beágyazni kívánt jelentést.

  3. Másolja ki a GUID-t az URL-címből. A GUID a /groups/ és a /reports/közötti szám.

    Képernyőkép a munkaterület azonosítójának GUID-jával a Power BI szolgáltatás URL-címében

Feljegyzés

A munkaterület-azonosító programozott lekéréséhez használja a Csoportok lekérése API-t.

Jelentésazonosító

A jelentésazonosító GUID-azonosítójának lekéréséhez kövesse az alábbi lépéseket:

  1. Jelentkezzen be a Power BI szolgáltatás.

  2. Nyissa meg a beágyazni kívánt jelentést.

  3. Másolja ki a GUID-t az URL-címből. A GUID a /reports/ és a /ReportSection közötti szám.

    Képernyőkép a jelentésazonosító GUID-jával a Power B I szolgáltatás U R L-ben

Feljegyzés

A jelentésazonosító programozott lekéréséhez használja a Jelentések lekérése a Csoport API-ban lehetőséget.

3. lépés – A szükséges NuGet-csomagok hozzáadása

Mielőtt elkezdené, hozzá kell adnia a , és Microsoft.PowerBI.Api NuGet-csomagokat Microsoft.Identity.Webaz alkalmazáshoz.

Adja hozzá a szükséges NuGet-csomagokat az alkalmazáshoz:

  • A VS Code-ban nyisson meg egy terminált, és írja be a következő kódot.

  • A Visual Studióban keresse meg a Tools>NuGet Csomagkezelő> Csomagkezelő Konzolt, és írja be a következő kódot.

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

4. lépés – Kiszolgálóoldali hitelesítés engedélyezése

Kapcsolja be a kiszolgálóoldali hitelesítést az alkalmazásban az alábbi táblázatban található fájlok létrehozásával vagy módosításával.

Fájl Használat
Startup.cs A hitelesítési szolgáltatás inicializálása Microsoft.Identity.Web
appsettings.json Hitelesítési adatok konfigurálása
PowerBiServiceApi.cs A Microsoft Entra-jogkivonat lekérése és metaadatok beágyazása
HomeController.cs Beágyazási adatok átadása modellként a nézetbe

Az indítási fájl konfigurálása a támogatáshoz Microsoft.Identity.Web

Módosítsa a kódot a Startup.cs a megadott hitelesítési szolgáltatás Microsoft.Identity.Webmegfelelő inicializálásához.

Adja hozzá az alábbi kódot az alkalmazás Startup.cs fájljához.

Feljegyzés

A kód számos ConfigureServices fontos dolgot hajt végre:

  1. A Microsoft Authentication Library hozzáférési jogkivonatok (Microsoft Entra-jogkivonatok) beszerzésére való konfigurálására irányuló hívás AddMicrosoftWebAppCallsWebApi .
  2. A hívás AddInMemoryTokenCaches konfigurál egy jogkivonat-gyorsítótárat, amelyet a Microsoft Hitelesítési kódtár a hozzáférési jogkivonatok gyorsítótárazására és a jogkivonatok frissítésére használ a színfalak mögött.
  3. A hívás services.AddScoped(typeof(PowerBiServiceApi)) az PowerBiServiceApi osztályt szolgáltatásosztályként konfigurálja, amely függőséginjektálással adható hozzá más osztályokhoz.
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();
            });
        }
    }
}

Hitelesítési adatfájl létrehozása

Ebben az oktatóanyagban a appsettings.json fájl bizalmas információkat tartalmaz, például az ügyfélazonosítót és az ügyfél titkos kódját. Biztonsági okokból nem javasoljuk, hogy ezeket az információkat a beállításfájlban tárolja. Az alkalmazásba való beágyazáskor érdemes megfontolni egy biztonságosabb eszközt, például az Azure Key Vaultot a bizalmas adatok védelméhez.

  1. A projektben hozzon létre egy új fájlt, és nevezze el appsettings.json.

  2. Adja hozzá a következő kódot a 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. Töltse ki a beágyazási paraméter 2. lépésben kapott értékeit – A beágyazási paraméterértékek lekérése.

Feljegyzés

Az előző kódban a PowerBi:ServiceRootUrl paraméter egyéni konfigurációs értékként van hozzáadva a Power BI szolgáltatás alap URL-címének nyomon követéséhez. Amikor a Microsoft nyilvános felhőben lévő Power BI szolgáltatás programozza, az URL-cím a következőhttps://api.powerbi.com/: . A Power BI szolgáltatás fő URL-címe azonban más felhőkben, például a kormányzati felhőben eltérő. Ezért az egyéni konfigurációs érték projektkonfigurációs értékként van tárolva, így szükség szerint módosíthatja.

Szerezze be a Microsoft Entra hozzáférési jogkivonatot, és hívja meg a Power BI szolgáltatás

A Power BI-tartalmak, például jelentések és irányítópultok beágyazásához az alkalmazásnak microsoft Entra-jogkivonatot kell beszereznie. A jogkivonat beszerzéséhez konfigurációs objektumra van szükség.

Az ebben a szakaszban található kód a .NET Core-függőséginjektálási mintát használja. Amikor az osztálynak szolgáltatást kell használnia, hozzáadhat egy konstruktorparamétert a szolgáltatáshoz. A .NET Core-futtatókörnyezet gondoskodik a szolgáltatáspéldány futásidőben történő átadásáról. Ebben az esetben a konstruktor a .NET Core konfigurációs szolgáltatás egy példányát injektálja a IConfiguration paraméter használatával, amely a PowerBi:ServiceRootUrl konfigurációs érték appsettings.json való lekérésére szolgál. A ITokenAcquisition névvel ellátott tokenAcquisitionparaméter a kódtár által Microsoft.Identity.Web biztosított Microsoft-hitelesítési szolgáltatásra hivatkozik. A ITokenAcquisition paraméter hozzáférési jogkivonatok beszerzésére szolgál a Microsoft Entra-azonosítóból.

A RequiredScopes mező egy sztringtömböt tartalmaz, amely a Power BI szolgáltatás API által támogatott delegált engedélyek készletét tartalmazza. Amikor az alkalmazás meghívja a hálózaton egy Microsoft Entra-jogkivonat beszerzését, átadja ezt a delegált engedélyeket, hogy a Microsoft Entra-azonosító belefoglalhassa őket a visszaadott hozzáférési jogkivonatba.

Feljegyzés

Ellenőrizze, hogy a Microsoft Entra-alkalmazás a webalkalmazás által megkövetelt hatókörökkel van-e konfigurálva. További információ: A Microsoft Entra-alkalmazás engedélyeinek módosítása.

  1. Az alkalmazás projektjében hozzon létre egy új, Szolgáltatások nevű mappát.

  2. A Szolgáltatások mappában hozzon létre egy új fájlt PowerBiServiceApi.cs címmel.

  3. Adja hozzá a következő kódot a 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
            };
        }

    }
}

A HomeController.cs fájl módosítása

Ebben a kód példában függőséginjektálás használatával módosítja a HomeController.cs fájlt. Az előző lépés végrehajtásával szolgáltatásként konfigurálta az PowerBiServiceApi osztályt a ConfigureServices metódus meghívásávalservices.AddScoped. Ezzel a kóddal hozzáad egy paramétert PowerBiServiceApi a konstruktorhoz, és a .NET Core-futtatókörnyezet létrehoz egy példányt PowerBiServiceApi , és átadja a konstruktornak.

A Vezérlők mappában nyissa meg a HomeController.cs fájlt, és adja hozzá a következő kódot:

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

5. lépés – Az alkalmazás ügyféloldalának létrehozása

Az ügyféloldali implementációhoz létre kell hoznia vagy módosítania kell az alábbi táblázatban felsorolt fájlokat:

Fájl Használat
embed.js Az ügyféloldali JavaScript-kódot tartalmazza
Embed.cshtml Az alkalmazás dokumentumobjektum-modelljét (DOM) és egy DIV-t tartalmaz a jelentés beágyazásához

Tároló létrehozása a beágyazott jelentéshez

Ebben az oktatóanyagban létre kell hoznia az Embed.cshtml fájlt, amelynek egy div eleme a beágyazott jelentés tárolója, és három szkripttel rendelkezik.

  1. A Kezdőlap megtekintése/ mappában hozzon létre egy Embed.cshtml nevű fájlt.

  2. Adja hozzá a következő kódot az Embed.cshtml fájlhoz.

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

Ügyféloldali JavaScript hozzáadása a jelentés beágyazásához

A Power BI-tartalmak beágyazásához létre kell hoznia egy konfigurációs objektumot. A konfigurációs objektum létrehozásáról további információt a Jelentés beágyazása című témakörben talál.

Ebben az oktatóanyagban egy embed.js nevű JavaScript-fájlt hoz létre egy konfigurációs objektummal a változót modelshasználó jelentés beágyazásához.

Inicializálható models a következő window['powerbi-client'].modelshívással: . A models változó olyan konfigurációs értékek beállítására szolgál, mint az models.Permissions.All, models.TokenType.Aadés models.ViewMode.Viewa .

A powerbi.embed függvény a models konfigurációs objektummal ágyazza be a jelentést.

  1. A wwwroot/js mappában hozzon létre egy embed.js nevű fájlt.

  2. Adja hozzá a következő kódot a embed.js fájlhoz.

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

  });

6. lépés – Az alkalmazás futtatása

Miután elvégezte az összes korábbi lépést, készen áll az alkalmazás futtatására. Próbálja meg futtatni az alkalmazást, és kísérletezzen a Power BI-jelentés beágyazási módjával. A Beágyazott Power BI-elemzési ügyfél API-k segítségével fejlesztheti az alkalmazást ügyféloldali API-k használatával.

Fontos

Ha ingyenes beágyazási próbaverziós jogkivonatokat használt a fejlesztéshez, termelési kapacitást kell vásárolnia. A kapacitás megvásárlásáig az ingyenes próbaverzió szalagcíme továbbra is megjelenik a beágyazott jelentés tetején.

Ha az alkalmazás készen áll, áthelyezheti a beágyazott alkalmazást éles környezetbe.

Kapcsolódó tartalom