Opetusohjelma: Power BI -raportin upottaminen sovellukseen organisaatiolle

  • Artikkeli

Tässä opetusohjelmassa kerrotaan, miten voit upottaa Power BI -raportin .NET 5.0 -sovellukseen osana Upottaminen organisaatiollesi -ratkaisua (tunnetaan myös nimellä user owns data). Upottaminen organisaatiollesi -ratkaisussa sovelluksesi käyttäjien on suoritettava Power BI -todennus omilla tunnistetiedoillaan.

Tässä opetusohjelmassa opit upottamaan:

  • Power BI -raportti
  • Organisaatiolle tarkoitettu upotus -sovelluksessa
  • .NET 5.0:n käyttäminen
  • Kirjaston Microsoft.Identity.Web avulla (kirjastoa tuetaan myös .NET Coressa)

Muistiinpano

Tässä opetusohjelmassa käytettävä täydellinen ratkaisu on saatavilla DOTNET5-UserOwnsData-Tutorial GitHub-säilöstä.

Edellytykset

Resursseja

Tässä opetusohjelmassa käytetään:

Metodi

Jos haluat upottaa Power BI -sisältöä Upottaminen organisaatiollesi -ratkaisuun, toimi seuraavasti:

  1. Microsoft Entra -sovelluksen määrittäminen
  2. Upotusparametriarvojen hakeminen
  3. Tarvittavien NuGet-pakettien lisääminen
  4. Ota käyttöön palvelinpuolen todennus
  5. Sovelluksen asiakaspuolen luominen
  6. Suorita sovelluksesi

Vaihe 1 – Määritä Microsoft Entra -sovelluksesi

Kun verkkosovelluksesi kutsuu Power BI:tä, se tarvitsee Microsoft Entra -tunnuksen Power BI REST -ohjelmointirajapintojen kutsumiseen ja Power BI -kohteiden, kuten raporttien, koontinäyttöjen tai ruutujen, upottamiseen.

Jos sinulla ei ole Microsoft Entra -sovellusta, luo sellainen Noudattamalla ohjeita kohdassa Microsoft Entra -sovelluksen rekisteröinti Power BI:ssä käytettäväksi.

Määritä Microsoft Entra -sovelluksesi noudattamalla ohjeita artikkelissa Microsoft Entra -sovelluksen määrittäminen.

Vaihe 2 – Hae upotusparametriarvot

Tarvitset raportin upottamiseen seuraavat arvot:

Toimialueen ja vuokraajan tunnus

Jos et tiedä toimialueesi tai vuokraajatunnustasi, katso Etsi Microsoft Entra -vuokraajatunnus ja ensisijainen toimialuenimi.

Muistiinpano

Jos haluat upottaa sisältöä toiselle vuokraajalle (vieraskäyttäjälle), sinun on muutettava parametria authorityUri .

Client ID

Jos haluat saada asiakastunnuksen yksilöivän tunnisteen (tunnetaan myös sovellustunnuksena), toimi seuraavasti:

  1. Kirjaudu Microsoft Azureen.

  2. Etsi Sovelluksen rekisteröinnit ja valitse Sovelluksen rekisteröinnit -linkki.

  3. Valitse Microsoft Entra -sovellus, jota käytät Power BI -sisällön upottamiseen.

  4. Kopioi Yleiskatsaus-osiosta yksilöivä tunniste Sovelluksen (asiakkaan) tunnus.

Asiakasohjelman salaisuus

Saat asiakassalaisuuden seuraavasti:

  1. Kirjaudu Microsoft Azureen.

  2. Etsi Sovelluksen rekisteröinnit ja valitse Sovelluksen rekisteröinnit -linkki.

  3. Valitse Microsoft Entra -sovellus, jota käytät Power BI -sisällön upottamiseen.

  4. Valitse Hallinta-kohdasta Varmenteet ja salaisuudet.

  5. Valitse Asiakassalaisuudet -kohdasta Uusi asiakassalaisuus.

  6. Anna Lisää asiakassalaisuus -ponnahdusikkunassa sovellussalaisuuden kuvaus, valitse milloin sovellussalaisuus vanhentuu ja valitse Lisää.

  7. Kopioi Asiakassalaisuudet-osiosta juuri luodun sovellussalaisuuden Arvo-sarakkeesta merkkijono. Asiakassalaisuuden arvo on asiakastunnuksesi.

Muistiinpano

Kopioi asiakasohjelman salasana-arvo, kun se tulee ensimmäisen kerran näkyviin. Kun siirryt pois tältä sivulta, asiakassalaisuus piilotetaan etkä pysty noutamaan sen arvoa.

Työtilan tunnus

Jos haluat saada työtilan yksilöivän tunnisteen, toimi seuraavasti:

  1. Kirjaudu Power BI -palveluun.

  2. Avaa upotettava raportti.

  3. Kopioi YKSILÖIVÄ tunnus URL-osoitteesta. Yksilöivä tunnus on luku /groups/ - ja /reports/-tunnusten välistä.

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

Muistiinpano

Jos haluat saada työtilan tunnuksen ohjelmallisesti, käytä Hae ryhmät -ohjelmointirajapintaa.

Raportin tunnus

Jos haluat saada raporttitunnuksen yksilöivän tunnisteen, toimi seuraavasti:

  1. Kirjaudu Power BI -palveluun.

  2. Avaa upotettava raportti.

  3. Kopioi YKSILÖIVÄ tunnus URL-osoitteesta. Yksilöivä tunnus on luku /reports/ - ja /ReportSection-arvojen välillä.

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

Muistiinpano

Jos haluat saada raporttitunnuksen ohjelmallisesti, käytä Hae raportit ryhmässä -ohjelmointirajapintaa.

Vaihe 3 – Lisää tarvittavat NuGet-paketit

Ennen kuin aloitat, sinun on lisättävä -, - Microsoft.Identity.Webja Microsoft.PowerBI.Api NuGet-paketit sovellukseesi.

Lisää seuraavat NuGet-paketit sovellukseesi:

  • Avaa VS Codessa pääte ja kirjoita seuraava koodi.

  • Siirry Visual Studiossa kohtaan Työkalut>NuGet paketinhallinta> paketinhallinta Konsoli ja kirjoita seuraava koodi.

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

Jos sovelluksesi todensi Microsoft.AspNetCore aiemmin, poista tämä paketti projektistasi kirjoittamalla:

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

Vaihe 4 – Ota käyttöön palvelinpuolen todennus

Ota palvelinpuolen todentaminen käyttöön sovelluksessa luomalla tai muokkaamalla seuraavan taulukon tiedostoja.

File Käyttäminen
Startup.cs Todentamispalvelun Microsoft.Identity.Web alustaminen
appsettings.json Todentamisen tiedot
PowerBiServiceApi.cs Hanki Microsoft Entra -tunnus ja upota metatietoja
HomeController.cs Tietojen upottamisen välittäminen mallina näkymään

Määritä käynnistystiedosto tukemaan Microsoft.Identity.Web

Muokkaa Startup.cs-tiedoston koodia, jotta kohteen tarjoama Microsoft.Identity.Webtodennuspalvelu alustetaan oikein.

Lisää seuraava koodikatkelman sovelluksesi Startup.cs-tiedostoon .

Muistiinpano

-koodi ConfigureServices suorittaa useita tärkeitä asioita:

  1. Kutsu, joka AddMicrosoftWebAppCallsWebApi määrittää Microsoftin todentamiskirjaston hankkimaan käyttöoikeustietueet (Microsoft Entra -tunnukset).
  2. Kutsu AddInMemoryTokenCaches määrittää tunnuksen välimuistin, jota Microsoftin todennuskirjasto käyttää välimuistiin käyttöoikeustietueiden ja taustalla olevien päivitystunnusten välimuistiin.
  3. Kutsu services.AddScoped(typeof(PowerBiServiceApi)) määrittää PowerBiServiceApi luokan palveluluokaksi, joka voidaan lisätä muihin luokkiin riippuvuuslisäystä käyttämällä.
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();

    }
  }
}

Todennustietotiedoston luominen

Tässä opetusohjelmassa appsettings.json tiedosto sisältää luottamuksellisia tietoja, kuten asiakastunnuksen ja asiakassalaisuuden. Suojaussyistä emme suosittele näiden tietojen säilyttämistä asetustiedostossa. Kun upotat sovellukseen, harkitse tätä turvallisempaa menetelmää, kuten Azure Key Vaultia .

  1. Luo projektissa uusi tiedosto ja kutsu sitä appsettings.json-tiedostoksi.

  2. Lisää seuraava koodi appsettings.json-tiedostoon:

    {
    "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äytä upotetut parametriarvot, jotka on saatu vaiheessa 2 - Hae upotetut parametriarvot.

Muistiinpano

Edellisessä koodikatkelmassa PowerBi:ServiceRootUrl parametri lisätään mukautettuna määritysarvona seuraamaan Power BI -palvelu perus-URL-osoitetta. Kun ohjelmointi perustuu Microsoftin julkisen pilvipalvelun Power BI -palvelu, URL-osoite on https://api.powerbi.com/. Power BI -palvelu URL-pääosoite on kuitenkin erilainen muissa pilvipalveluissa, kuten julkishallinnon pilvipalvelussa. Siksi tämä arvo tallennetaan projektin määritysarvona, joten sitä on helppo muuttaa tarvittaessa.

Hanki Microsoft Entra -käyttöoikeustietue ja kutsu Power BI -palvelu

Jotta voit upottaa Power BI -sisältöä (kuten raportteja ja koontinäyttöjä), sovelluksesi on saatava Microsoft Entra -tunnus. Tarvitset määritysobjektin, jotta voit hankkia tunnuksen.

Tämän osion koodi käyttää .NET Core -riippuvuussuhteen lisäysmallia. Kun luokan on käytettävä palvelua, voit lisätä konstruktoriparametrin kyseiselle palvelulle ja .NET Core -suorituspalvelu huolehtii palveluesiintymän välittämisestä suorituksen aikana. Tässä tapauksessa konstruktori lisää .NET Core -määrityspalvelun esiintymän -parametrin IConfiguration avulla, jota käytetään konfigurointiarvon PowerBi:ServiceRootUrl noutamiseen appsettings.json-tiedostosta. Nimetty ITokenAcquisition parametri tokenAcquisition sisältää viittauksen kirjaston Microsoft.Identity.Web tarjoamaan Microsoft-todennuspalveluun, ja sen avulla hankitaan käyttöoikeustietueet Microsoft Entra -tunnuksesta.

-RequiredScopeskentässä on merkkijonomatriisi, joka sisältää joukon Power BI -palvelu-ohjelmointirajapinnan tukemia delegoituja käyttöoikeuksia. Kun sovelluksesi kutsuu verkon kautta Microsoft Entra -tunnuksen hankkimiseksi, välittää nämä delegoidut käyttöoikeudet, jotta Microsoft Entra -tunnus voi sisällyttää ne palauttamaansa käyttöoikeustietueeseen.

Muistiinpano

Varmista, että Microsoft Entra -sovellukseen on määritetty verkkosovelluksesi edellyttämät vaikutusalueet. Lisätietoja on kohdassa Microsoft Entra -sovelluksen käyttöoikeuksien muuttaminen.

  1. Luo sovelluksesi projektissa uusi kansio nimeltä Palvelut.

  2. Luo Palvelut-kansioon uusi tiedosto nimeltä PowerBiServiceApi.cs.

  3. Lisää seuraava koodi kohtaan 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()
   };
  }

 }

}

HomeController.cs-tiedoston muokkaaminen

Tässä koodiesimerkissä käytetään riippuvuuslisäystä. Kun rekisteröit PowerBiServiceApi luokan palveluna kutsumalla services.AddScoped -menetelmässä ConfigureServices . Voit lisätä parametrin PowerBiServiceApi konstruktoriin, ja .NET Core -suorituspalvelu huolehtii esiintymän PowerBiServiceApi luomisesta ja sen välittämisestä konstruktorille.

Avaa Controllers-kansiostaHomeController.cs-tiedosto ja lisää se seuraavaan koodikatkelmaan:

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

Vaihe 5 – Sovelluksen asiakaspuolen luominen

Asiakaspuolen toteutusta varten sinun on luotava seuraavan taulukon tiedostot tai muokattava niitä.

File Käyttäminen
embed.js Sisältää client-side JavaScript -koodin
Embed.cshtml Sisältää sovelluksesi asiakirjaobjektimallin (DOM) ja DIV-objektin raportin upottamista varten.

Säilön luominen upotetulle raportille

Luo Embed.cshtml-tiedosto, jossa on div upotetun raportin säilönä käytettävä elementti ja kolme komentosarjaa.

  1. Luo Näytä aloitus ->kansiossa tiedosto nimeltä Embed.cshtml.

  2. Lisää seuraava koodikatkelma Embed.cshtml-tiedostoon .

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

Asiakaspuolen JavaScriptin lisääminen raportin upottamiseen

Jos haluat upottaa Power BI -sisältöä, sinun on luotava määritysobjekti. Lisätietoja määritysobjektin luomisesta on artikkelissa Raportin upottaminen.

Tässä osiossa luot JavaScript-tiedoston nimeltä embed.js ja määritysobjekti raportin upottamista varten muuttujan modelsavulla.

models valmistellaan kutsulla kohteeseen window['powerbi-client'].models. Muuttujan models avulla määritetään konfigurointiarvot, kuten models.Permissions.All, models.TokenType.Aadja models.ViewMode.View.

Funktio powerbi.embed käyttää models määritysobjektia raportin upottamiseen.

  1. Luo wwwroot>js -kansioon tiedosto nimeltä embed.js.

  2. Lisää seuraava koodikatkelma embed.js-tiedostoon .

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

});

Vaihe 6 – Suorita sovelluksesi

Kun olet tehnyt kaikki tässä opetusohjelmassa luetellut muutokset, olet valmis suorittamaan sovelluksesi. Suorita sovellus ja kokeile, miten Power BI -raporttisi on upotettu. Voit parantaa sovellustasi asiakaspuolen ohjelmointirajapintojen avulla upotetun Power BI -analytiikan asiakasohjelman ohjelmointirajapintojen avulla.

Kun sovelluksesi on valmis, voit siirtää upotetun sovelluksesi tuotantoon.

Liittyvä sisältö

Upotetun analytiikan sovellustunnukset

Upotetun sovelluksesi siirtäminen tuotantoon

Kapasiteetti ja SKU Power BI:n upotetussa analytiikassa

Kapasiteetin suunnittelu Power BI Embedded -analytiikassa