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

Ez az oktatóanyag bemutatja, hogyan ágyazhat be Power BI-jelentéseket egy .NET 5.0-alkalmazásba a szervezet (más néven felhasználó tulajdonában lévő adatok) beágyazási megoldásának részeként. A szervezeti megoldás beágyazásához az alkalmazás felhasználóinak saját hitelesítő adataikkal kell hitelesíteniük magukat a Power BI-ban.

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

• Power BI-jelentés
• Beágyazás a szervezeti alkalmazáshoz
• A .NET 5.0 használata
• A tárral Microsoft.Identity.Web (ez a könyvtár a .NET Core-ban is támogatott)

Feljegyzés

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

Előfeltételek

• Felhasználónkénti Power BI Pro vagy Premium (PPU) licenc.

  Feljegyzés

  A szervezeti megoldás beágyazása nem támogatott az A termékváltozatokon alapuló kapacitásokon. Az A termékváltozat csak az ügyfélmegoldás beágyazásához használható.

• Power BI-munkaterület jelentéssel.

• Saját Microsoft Entra-bérlője.

• Egy Microsoft Entra-alkalmazás.

• .NET Core 5 modellnézet-vezérlő (MVC) alkalmazás.

• .NET Core 5 SDK (vagy újabb).

• Integrált fejlesztési környezet (IDE). Az alábbi környezetek egyikét javasoljuk:

  • Visual Studio.
  • Visual Studio Code (C # kiterjesztéssel).

Források

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

• Power BI REST Reports API – az URL beágyazásához és a beágyazási jogkivonat lekéréséhez.
• Microsoft Identity Web Authentication-kódtár.
• Power BI embedded analytics ügyfél API-k – a jelentés beágyazásához.

Metódus

Ha Power BI-tartalmakat szeretne beágyazni egy beágyazásba a szervezeti megoldáshoz, kövesse az alábbi lépéseket:

1. A Microsoft Entra-alkalmazás konfigurálása
2. A beágyazási paraméter értékeinek lekérése
3. Adja hozzá a szükséges NuGet-csomagokat
4. Kiszolgálóoldali hitelesítés engedélyezése
5. Az alkalmazás ügyféloldalának létrehozása
6. Az alkalmazás futtatása

1. lépés – A Microsoft Entra-alkalmazás konfigurálása

Amikor a webalkalmazás meghívja a Power BI-t, egy Microsoft Entra-jogkivonatra van szüksége a Power BI REST API-k meghívásához és Power BI-elemek, például jelentések, irányítópultok vagy csempék beágyazásához.

Ha nem rendelkezik Microsoft Entra-alkalmazással, hozzon létre egyet a Microsoft Entra-alkalmazás regisztrálása a Power BI-ban való használatához.

A Microsoft Entra-alkalmazás konfigurálásához kövesse a Microsoft Entra-alkalmazás konfigurálására vonatkozó utasításokat.

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
• Bérlőazonosító
• Ügyfélazonosító
• Titkos ügyfélkód
• Munkaterület azonosítója
• Jelentésazonosító

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 másik bérlőre (vendégfelhasználóra) szeretne beágyazni tartalmat, 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.

   

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.

   

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

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

Adja hozzá a következő 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 -v 0.3.0-preview
dotnet add package Microsoft.Identity.Web.UI -v 0.3.0-preview
dotnet add package Microsoft.PowerBI.Api

Ha az alkalmazás korábban hitelesítésre használta Microsoft.AspNetCore , távolítsa el ezt a csomagot a projektből a következő beírással:

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

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

Engedélyezze 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 részletek
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ódrészletet 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 egy jogkivonat-gyorsítótár konfigurálására, 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 fog használni a színfalak mögött
3. A hívás services.AddScoped(typeof(PowerBiServiceApi)) szolgáltatásosztályként konfigurálja az PowerBiServiceApi osztályt, amely függőséginjektálással adható hozzá más osztályokhoz.

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

    }
  }
}

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 módszert, például az Azure Key Vaultot ezen információk megőrzéséhez.

1. A projektben hozzon létre egy új fájlt, és hívja meg appsettings.json.

2. Adja hozzá a következő kódot a appsettings.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. 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.

   • Domain - Tartomány- és bérlőazonosító
   • TenantId - Tartomány- és bérlőazonosító
   • ClientId - Ügyfélazonosító
   • ClientSecret - Titkos ügyfélkód

Feljegyzés

Az előző kódrészletben a PowerBi:ServiceRootUrl paraméter egyéni konfigurációs értékként lesz hozzáadva a Power BI szolgáltatás alap URL-címének nyomon követéséhez. Ha a microsoftos nyilvános felhőben a 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ő lesz. Ezért ezt az értéket a rendszer projektkonfigurációs értékként tárolja, így szükség esetén könnyen módosítható.

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

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, és 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éterrel, amely a PowerBi:ServiceRootUrl konfigurációs érték appsettings.json való lekérésére szolgál. A ITokenAcquisition névvel ellátott tokenAcquisition paraméter a kódtár által Microsoft.Identity.Web biztosított Microsoft hitelesítési szolgáltatásra hivatkozik, és a Hozzáférési jogkivonatok a Microsoft Entra-azonosítóból való beszerzésére szolgál.

A RequiredScopes mező tartalmaz egy sztringtömböt, amely a Power BI szolgáltatás API által támogatott delegált engedélyek készletét tartalmazza. Amikor az alkalmazás a hálózaton keresztül meghív egy Microsoft Entra-jogkivonatot, á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 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()
      };
     }
   
    }
   
   }
   

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

Ebben a kód példában függőséginjektálást használ. Amikor az osztályt PowerBiServiceApi szolgáltatásként regisztrálta a ConfigureServices metódus meghívásávalservices.AddScoped. Hozzáadhat egy paramétert PowerBiServiceApi a konstruktorhoz, és a .NET Core-futtatókörnyezet gondoskodik a PowerBiServiceApi példány létrehozásáról és a konstruktornak való átadásáról.

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

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

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 a fájlokat az alábbi táblázatban.

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

Hozza létre az Embed.cshtml fájlt, amelynek a div beágyazott jelentés tárolójaként használt eleme és három szkriptje van.

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

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

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

Ü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 a szakaszban egy embed.js nevű JavaScript-fájlt hoz létre egy konfigurációs objektummal a jelentés beágyazásához a változó modelshasználatával.

models inicializálása a következő hívással történik: window['powerbi-client'].models. 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ódrészletet a embed.js fájlhoz.

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

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

Miután elvégezte az oktatóanyagban felsorolt összes módosítást, készen áll az alkalmazás futtatására. Hajtsa végre az alkalmazást, és kísérletezzen a Power BI-jelentés beágyazásának 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.

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

Kapcsolódó tartalom

• Beágyazott elemzési alkalmazás jogkivonatai
• Beágyazott alkalmazás áthelyezése éles környezetbe
• Kapacitás és termékváltozatok beágyazott Power BI-elemzésekben
• Kapacitástervezés a Beágyazott Power BI-elemzésekben