Zelfstudie: Een Power BI-rapport insluiten in een toepassing voor uw klanten

In deze zelfstudie leert u hoe u een Power BI-rapport insluit in een .NET 5.0-toepassing, als onderdeel van de insluitoplossing voor uw klanten (ook wel bekend als een app is eigenaar van gegevens). In een insluiting voor uw klantenoplossing hoeven uw app-gebruikers zich niet aan te melden bij Power BI of een Power BI-licentie te hebben.

In deze zelfstudie leert u hoe u het volgende kunt insluiten:

  • Een Power BI-rapport
  • Insluiten voor uw klanten-app
  • Een service-principal gebruiken
  • .NET 5.0 gebruiken
  • Met de Microsoft.Identity.Web bibliotheek (deze bibliotheek wordt ook ondersteund in .NET Core)

Notitie

De volledige oplossing die in deze zelfstudie wordt gebruikt, is beschikbaar in de GitHub-opslagplaats DOTNET5-AppOwnsData-Tutorial .

Vereisten

Resources

In deze zelfstudie gebruikt u:

Methode

Voer de volgende stappen uit om Power BI-inhoud in te sluiten in een insluiten voor uw klantenoplossing :

  1. Configureer uw Azure AD-app en service-principal.

  2. Haal de parameterwaarden voor de insluiting op.

  3. Voeg de vereiste NuGet-pakketten toe.

  4. Schakel verificatie aan de serverzijde in.

  5. Bouw de clientzijde van uw app.

  6. Voer uw toepassing uit.

Stap 1: uw Azure AD-app en service-principal configureren

In deze zelfstudie gebruikt u een service-principal om u te verifiëren als web-app voor Azure AD. U hebt ook een Azure AD-app nodig waarmee u een Azure AD-token kunt genereren. Met het Azure AD-token kan uw web-app Power BI REST API's aanroepen en Power BI-items, zoals rapporten, dashboards of tegels, insluiten.

Volg de instructies voor de service-principal om een Azure AD-app te maken en de service-principal van apps in staat te stellen om met uw Power BI-inhoud te werken.

Stap 2: de parameterwaarden voor insluiten ophalen

Als u uw rapport wilt insluiten, hebt u de volgende waarden nodig:

Domein- en tenant-id

Als u niet weet wat uw domein- of tenant-id is, raadpleegt u de Microsoft Azure AD-tenant-id en de primaire domeinnaam zoeken.

Notitie

Als u inhoud wilt insluiten voor een gebruiker in een andere tenant (een gastgebruiker), moet u de authorityUri parameter aanpassen.

Client-id

Als u de GUID van de client-id (ook wel de app-id genoemd) wilt ophalen, voert u de volgende stappen uit:

  1. Meld u aan bij Microsoft Azure.

  2. Ga naar App-registraties en selecteer de koppeling App-registraties.

  3. Selecteer de Azure AD-app die u gebruikt voor het insluiten van uw Power BI-inhoud.

  4. Kopieer in de sectie Overzicht de GUID van de app-id (client) .

Clientgeheim

Als u het clientgeheim wilt ophalen, voert u de volgende stappen uit:

  1. Meld u aan bij Microsoft Azure.

  2. Ga naar App-registraties en selecteer de koppeling App-registraties.

  3. Selecteer de Azure AD-app die u gebruikt voor het insluiten van uw Power BI-inhoud.

  4. Selecteer onder Beherencertificatengeheimen&.

  5. Selecteer onder Clientgeheimen de optie Nieuw clientgeheim.

  6. Geef in het pop-upvenster Een clientgeheim toevoegen een beschrijving op voor uw app-geheim, selecteer wanneer het app-geheim verloopt en selecteer Toevoegen.

  7. Kopieer in de sectie Clientgeheimen de tekenreeks in de kolom Waarde van het zojuist gemaakte app-geheim. De waarde van het clientgeheim is uw client-id.

Notitie

Zorg ervoor dat u de waarde van het clientgeheim kopieert wanneer deze voor het eerst wordt weergegeven. Nadat u van deze pagina bent verwijderd, wordt het clientgeheim verborgen en kunt u de waarde ervan niet meer ophalen.

Werkruimte-id

Als u de GUID van de werkruimte-id wilt ophalen, voert u de volgende stappen uit:

  1. Meld u aan bij de Power BI-service.

  2. Open het rapport dat u wilt insluiten.

  3. Kopieer de GUID van de URL. De GUID is de tekenreeks tussen /groups/ en /reports/ .

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

Notitie

Gebruik de API Groepen ophalen om de werkruimte-id programmatisch op te halen.

Rapport-id

Voer de volgende stappen uit om de GUID van de rapport-id op te halen:

  1. Meld u aan bij de Power BI-service.

  2. Open het rapport dat u wilt insluiten.

  3. Kopieer de GUID van de URL. De GUID is de tekenreeks tussen /reports/ en /ReportSection.

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

Notitie

Als u de rapport-id programmatisch wilt ophalen, gebruikt u de API Rapporten ophalen in groep .

Stap 3: de vereiste NuGet-pakketten toevoegen

Voordat u kunt beginnen, moet u de Microsoft.Identity.WebMicrosoft.PowerBI.Api en NuGet-pakketten toevoegen aan uw app.

Voeg de Onderstaande NuGet-pakketten toe aan uw app:

  • Open in VS Code een terminal en typ de onderstaande code.

  • Navigeer in Visual Studio naar de Console ToolsNuGet>PackageManagerPackage> Manager en typ de onderstaande code.

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

Stap 4: verificatie aan de serverzijde inschakelen

Schakel verificatie aan de serverzijde in uw app in door de bestanden in de onderstaande tabel te maken of te wijzigen.

File Gebruik
Startup.cs De Microsoft.Identity.Web verificatieservice initialiseren
appsettings.json Verificatiedetails
PowerBiServiceApi.cs Het Azure AD-token ophalen en metagegevens insluiten
HomeController.cs Gegevens als model doorgeven aan de weergave

Uw opstartbestand configureren ter ondersteuning Microsoft.Identity.Web

Wijzig de code in Startup.cs om de verificatieservice Microsoft.Identity.Webvan Startup.cs correct te initialiseren.

Voeg het onderstaande codefragment toe aan het bestand Startup.cs van uw app.

Notitie

De code in ConfigureServices het bereiken van verschillende belangrijke dingen:

  1. De aanroep voor AddMicrosoftWebAppCallsWebApi het configureren van de Microsoft-verificatiebibliotheek voor het verkrijgen van toegangstokens (Azure AD-tokens).
  2. De aanroep voor AddInMemoryTokenCaches het configureren van een tokencache die door de Microsoft-verificatiebibliotheek wordt gebruikt voor het opslaan van toegangstokens in de cache en het vernieuwen van tokens achter de schermen
  3. De aanroep om services.AddScoped(typeof(PowerBiServiceApi)) de PowerBiServiceApi klasse te configureren als een serviceklasse die kan worden toegevoegd aan andere klassen met behulp van afhankelijkheidsinjectie.
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 may 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();
            });
        }
    }
}

Een verificatiedetailsbestand maken

In deze zelfstudie bevat het appsettings.json bestand gevoelige informatie, zoals client-id en clientgeheim. Om veiligheidsredenen wordt het afgeraden om deze informatie in het instellingenbestand te bewaren. Overweeg bij het insluiten van inhoud in uw toepassing een veiligere methode, zoals Azure Key Vault voor het bewaren van deze informatie.

  1. Maak in uw project een nieuw bestand en noem het appsettings.json.

  2. Voeg de volgende code toe aan 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. Vul de insluitparameterwaarden in die zijn verkregen uit stap 2: haal de insluitingsparameterwaarden op.

Notitie

In het bovenstaande codefragment wordt de PowerBi:ServiceRootUrl parameter toegevoegd als een aangepaste configuratiewaarde om de basis-URL naar de Power BI-service bij te houden. Wanneer u programmeert op basis van de Power BI-service in de openbare Cloud van Microsoft, is https://api.powerbi.com/de URL. De hoofd-URL voor de Power BI-service is echter anders in andere clouds, zoals de cloud van de overheid. Daarom wordt deze waarde opgeslagen als een projectconfiguratiewaarde, zodat u deze eenvoudig kunt wijzigen wanneer dat nodig is.

Het Azure AD-toegangstoken ophalen en de Power BI-service aanroepen

Als u Power BI inhoud (zoals rapporten en dashboards) wilt insluiten, moet uw app een Azure AD-token ophalen. Als u het token wilt ophalen, hebt u een configuratieobject nodig.

De code in deze sectie maakt gebruik van het .NET Core-afhankelijkheidsinjectiepatroon. Wanneer uw klasse een service moet gebruiken, kunt u een constructorparameter voor die service toevoegen en zorgt de .NET Core-runtime ervoor dat het service-exemplaar tijdens runtime wordt doorgegeven. In dit geval injecteert de constructor een exemplaar van de .NET Core-configuratieservice met behulp van de IConfiguration parameter, die wordt gebruikt om de PowerBi:ServiceRootUrl configuratiewaarde op te halen uit appsettings.json. De ITokenAcquisition parameter, die een naam heeft tokenAcquisition , bevat een verwijzing naar de Microsoft-verificatieservice die wordt geleverd door de Microsoft.Identity.Web bibliotheek en wordt gebruikt voor het verkrijgen van toegangstokens van Azure AD.

Het RequiredScopes veld bevat een tekenreeksmatrix met een set gedelegeerde machtigingen die worden ondersteund door de Power BI-service-API. Wanneer uw toepassing via het netwerk wordt aangeroepen om een Azure AD-token te verkrijgen, wordt deze set gedelegeerde machtigingen doorgegeven, zodat Azure AD deze kan opnemen in het toegangstoken dat wordt geretourneerd.

Notitie

Controleer of uw Azure AD-app is geconfigureerd met de bereiken die zijn vereist voor uw web-app. Zie De machtigingen van uw Azure AD-app wijzigen voor meer informatie.

  1. Maak in het app-project een nieuwe map met de titel Services.

  2. Maak in de map Services een nieuw bestand met de naam PowerBiServiceApi.cs.

  3. Voeg de volgende code toe aan 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
                };
            }
    
        }
    }
    

Het bestand HomeController.cs wijzigen

In dit codevoorbeeld gebruikt u afhankelijkheidsinjectie. Wanneer u de PowerBiServiceApi klasse als een service hebt geregistreerd door de ConfigureServices methode aan te roepenservices.AddScoped. U kunt een PowerBiServiceApi parameter toevoegen aan de constructor en de .NET Core-runtime zorgt ervoor dat er een PowerBiServiceApi exemplaar wordt gemaakt en doorgegeven aan de constructor.

Open vanuit de map Controllers het bestand HomeController.cs en voeg het volgende codefragment toe:

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

Stap 5: de clientzijde van uw app bouwen

Voor implementatie aan de clientzijde moet u de bestanden in de onderstaande tabel maken of wijzigen

File Gebruik
embed.js Bevat de JavaScript-code aan de clientzijde
Embed.cshtml Bevat het documentobjectmodel van uw app (DOM) en een DEEL voor het insluiten van het rapport

Een container maken voor uw ingesloten rapport

Maak het bestand Embed.cshtml , dat een div element bevat dat wordt gebruikt als een container voor uw ingesloten rapport en drie scripts.

  1. Maak in de map ViewHome> een bestand met de naam Embed.cshtml.

  2. Voeg het volgende codefragment toe aan het bestand Embed.cshtml .

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

JavaScript aan de clientzijde toevoegen om uw rapport in te sluiten

Als u Power BI inhoud wilt insluiten, moet u een configuratieobject maken. Zie Een rapport insluiten voor meer informatie over het maken van het configuratieobject.

In deze zelfstudie maakt u een JavaScript-bestand met de naam embed.js met een configuratieobject voor het insluiten van uw rapport met behulp van de variabele models.

models wordt geïnitialiseerd met behulp van een aanroep naar window['powerbi-client'].models. De variabele wordt gebruikt voor het models instellen van configuratiewaarden zoals models.Permissions.All, models.TokenType.Aad en models.ViewMode.View.

De powerbi.embed functie gebruikt het models configuratieobject om uw rapport in te sluiten.

  1. Maak in de map wwwrootjs> een bestand met de naam embed.js.

  2. Voeg het volgende codefragment toe aan het embed.js-bestand .

    $(function () {
    
        // 1 - Get DOM object for div that is report container 
        var reportContainer = document.getElementById("embed-container");
    
        // 2 - Get report embedding data from view model
        var reportId = window.viewModel.reportId;
        var embedUrl = window.viewModel.embedUrl;
        var token = window.viewModel.token
    
        // 3 - Embed report 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 embed container on 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);
        });
    
      });
    

Stap 6: Uw toepassing uitvoeren

Nadat u alle aanpassingen in deze zelfstudie hebt aangebracht, bent u klaar om uw toepassing uit te voeren. Voer uw toepassing uit en experimenteer met de manier waarop uw Power BI rapport is ingesloten. U kunt de Power BI client-API's voor ingesloten analyses gebruiken om uw app te verbeteren met behulp van API's aan de clientzijde.

Wanneer uw app klaar is, kunt u uw ingesloten app verplaatsen naar productie.

Volgende stappen