Självstudie: Bädda in en Power BI-rapport i ett program för dina kunder

I den här självstudien får du lära dig hur du bäddar in en Power BI-rapport i ett .NET 5.0-program som en del av lösningen embed-for-your-customers (även kallat app-owns-data). I en lösning för inbäddning för dina kunder behöver appanvändare inte logga in på Power BI eller ha en Power BI-licens.

I den här självstudien lär du dig att bädda in:

• En Power BI-rapport.
• I en inbäddningsapp för dina kunder.
• Genom att använda tjänstens huvudnamn.
• Med hjälp av .NET 5.0.
• Microsoft.Identity.Web Med biblioteket (det här biblioteket stöds också i .NET Core).

Kommentar

Den fullständiga lösningen som används i den här självstudien är tillgänglig från github-lagringsplatsen DOTNET5-AppOwnsData-Tutorial .

Förutsättningar

• En Licens för Power BI Pro eller Premium per användare (PPU)

• En Power BI-arbetsyta med en rapport

• Din egen Microsoft Entra-klientorganisation

• En Microsoft Entra-app

• En MVC-app (.NET Core 5 Model View Controller)

• .NET Core 5 SDK eller senare

• En integrerad utvecklingsmiljö (IDE). Vi rekommenderar någon av följande ID:er:

  • Visual Studio.

  • Visual Studio Code med C#-tillägget

Resurser

I den här självstudien använder du:

• Power BI REST Reports API för att bädda in URL:en och hämta inbäddningstoken.

• Microsoft Identity Web Authentication-bibliotek.

• Klient-API:er för Power BI Embedded-analys för att bädda in rapporten.

Metod

Om du vill bädda in Power BI-innehåll i en lösning för inbäddning för dina kunder följer du dessa steg:

1. Konfigurera din Microsoft Entra-app och tjänstens huvudnamn.

2. Hämta parametervärdena för inbäddning.

3. Lägg till nödvändiga NuGet-paket.

4. Aktivera autentisering på serversidan.

5. Skapa appens klientsida.

6. Kör programmet.

Steg 1 – Konfigurera din Microsoft Entra-app och tjänstens huvudnamn

I den här självstudien använder du ett huvudnamn för tjänsten för att autentisera din webbapp mot Microsoft Entra-ID. Du behöver också en Microsoft Entra-app som gör det möjligt att generera en Microsoft Entra-token. Genom att använda Microsoft Entra-token kan webbappen anropa Power BI REST-API:er och bädda in Power BI-objekt, till exempel rapporter, instrumentpaneler och paneler.

Följ instruktionerna för tjänstens huvudnamn för att skapa en Microsoft Entra-app och aktivera appens tjänsthuvudnamn för att arbeta med ditt Power BI-innehåll.

Steg 2 – Hämta parametervärdena för inbäddning

För att bädda in rapporten behöver du följande värden:

• Domän
• Tenant ID
• Klient-ID
• Client secret
• Arbetsyte-ID
• Rapport-ID

Domän- och klientorganisations-ID

Om du inte känner till din domän eller ditt klient-ID kan du läsa Hitta Klient-ID för Microsoft Entra och det primära domännamnet.

Kommentar

Om du vill bädda in innehåll för en användare i en annan klientorganisation (gästanvändare) måste du justera parametern authorityUri .

Client ID

Följ dessa steg för att hämta klient-ID:ts GUID (även kallat program-ID):

1. Logga in på Microsoft Azure.

2. Sök efter Appregistreringar och välj länken Appregistreringar.

3. Välj den Microsoft Entra-app som du använder för att bädda in ditt Power BI-innehåll.

4. I avsnittet Översikt kopierar du program-ID:t (klient-ID :t).

Klienthemlighet

Följ dessa steg för att hämta klienthemligheten:

1. Logga in på Microsoft Azure.

2. Sök efter Appregistreringar och välj länken Appregistreringar.

3. Välj den Microsoft Entra-app som du använder för att bädda in ditt Power BI-innehåll.

4. Under Hantera väljer du Certifikat och hemligheter.

5. Under Klienthemligheter väljer du Ny klienthemlighet.

6. I popup-fönstret Lägg till en klienthemlighet anger du en beskrivning av programhemligheten, väljer när programhemligheten upphör att gälla och väljer Lägg till.

7. I avsnittet Klienthemligheter kopierar du strängen i kolumnen Värde i den nyligen skapade programhemligheten. Värdet för klienthemligheten är ditt klient-ID.

Kommentar

Se till att du kopierar värdet för klienthemligheten när det först visas. När du har navigerat bort från den här sidan döljs klienthemligheten och du kan inte hämta dess värde.

Arbetsplats-ID

Följ dessa steg för att hämta arbetsyte-ID:ts GUID:

1. Logga in på Power BI-tjänst.

2. Öppna den rapport som du vill bädda in.

3. Kopiera GUID från URL:en. GUID är talet mellan /groups/ och /reports/.

   

Kommentar

Om du vill hämta arbetsytans ID programmatiskt använder du API:et Hämta grupper .

Rapport-ID

Följ dessa steg för att hämta rapport-ID:ts GUID:

1. Logga in på Power BI-tjänst.

2. Öppna den rapport som du vill bädda in.

3. Kopiera GUID från URL:en. GUID är talet mellan /reports/ och /ReportSection.

   

Kommentar

Om du vill hämta rapport-ID:t programmatiskt använder du API:et Hämta rapporter i grupp .

Steg 3 – Lägg till nödvändiga NuGet-paket

Innan du kan börja måste du lägga till , och Microsoft.PowerBI.Api NuGet-paketen Microsoft.Identity.Webi din app.

Lägg till nödvändiga NuGet-paket i din app:

• Öppna en terminal i VS Code och ange följande kod.

• I Visual Studio går du till Verktyg>NuGet Package Manager Package Manager-konsolen> och skriver in följande kod.

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

Steg 4 – Aktivera autentisering på serversidan

Aktivera autentisering på serversidan i din app genom att skapa eller ändra filerna i följande tabell.

Fil	Använd
Startup.cs	Initiera autentiseringstjänsten Microsoft.Identity.Web
appsettings.json	Konfigurera autentiseringsinformation
PowerBiServiceApi.cs	Hämta Microsoft Entra-token och inbäddningsmetadata
HomeController.cs	Skicka inbäddningsdata som en modell till vyn

Konfigurera startfilen så att den stöder Microsoft.Identity.Web

Ändra koden i Startup.cs för att initiera autentiseringstjänsten som tillhandahålls av Microsoft.Identity.Web.

Lägg till följande kod i appens Startup.cs-fil .

Kommentar

Koden i ConfigureServices åstadkommer flera viktiga saker:

1. Anropet till AddMicrosoftWebAppCallsWebApi konfigurerar Microsoft-autentiseringsbiblioteket för att hämta åtkomsttoken (Microsoft Entra-token).
2. Anropet till AddInMemoryTokenCaches konfigurerar en tokencache som Microsofts autentiseringsbibliotek använder för att cachelagrar åtkomsttoken och uppdateringstoken i bakgrunden.
3. Anropet PowerBiServiceApi till services.AddScoped(typeof(PowerBiServiceApi)) konfigurerar klassen som en tjänstklass som kan läggas till i andra klasser med hjälp av beroendeinmatning.

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

Skapa en autentiseringsinformationsfil

I den här självstudien innehåller filen appsettings.json känslig information, till exempel klient-ID och klienthemlighet. Av säkerhetsskäl rekommenderar vi inte att du behåller den här informationen i inställningsfilen. När du bäddar in i ditt program bör du överväga ett säkrare verktyg, till exempel Azure Key Vault, för att skydda känslig information.

1. Skapa en ny fil i projektet och ge den namnet appsettings.json.

2. Lägg till följande kod i 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. Fyll i de inbäddningsparametervärden som hämtats från steg 2 – Hämta parametervärdena för inbäddning.

   • Domain - Domän- och klientorganisations-ID
   • TenantId - Domän- och klientorganisations-ID
   • ClientId - Klient-ID
   • ClientSecret - Client secret

Kommentar

I föregående kod läggs parametern PowerBi:ServiceRootUrl till som ett anpassat konfigurationsvärde för att spåra bas-URL:en till Power BI-tjänst. När du programmerar mot Power BI-tjänst i Microsofts offentliga moln är https://api.powerbi.com/URL:en . Rot-URL:en för Power BI-tjänst skiljer sig dock i andra moln, till exempel myndighetsmolnet. Därför lagras det anpassade konfigurationsvärdet som ett projektkonfigurationsvärde, så att du kan ändra det efter behov.

Hämta Microsoft Entra-åtkomsttoken och anropa Power BI-tjänst

För att kunna bädda in Power BI-innehåll som rapporter och instrumentpaneler måste din app hämta en Microsoft Entra-token. För att hämta token behöver du ett konfigurationsobjekt.

Koden i det här avsnittet använder .NET Core-beroendeinmatningsmönstret. När klassen behöver använda en tjänst kan du lägga till en konstruktorparameter för den tjänsten. .NET Core-körningen tar hand om att skicka tjänstinstansen vid körning. I det här fallet matar konstruktorn in en instans av .NET Core-konfigurationstjänsten med hjälp av parametern IConfiguration , som används för att hämta PowerBi:ServiceRootUrl konfigurationsvärdet från appsettings.json. Parametern ITokenAcquisition , som heter tokenAcquisition, innehåller en referens till Microsoft-autentiseringstjänsten som tillhandahålls av Microsoft.Identity.Web biblioteket. Parametern ITokenAcquisition används för att hämta åtkomsttoken från Microsoft Entra-ID.

Fältet RequiredScopes innehåller en strängmatris som innehåller en uppsättning delegerade behörigheter som stöds av Power BI-tjänst-API:et. När ditt program anropar över nätverket för att hämta en Microsoft Entra-token skickas den här uppsättningen delegerade behörigheter så att Microsoft Entra-ID:t kan inkludera dem i den åtkomsttoken som det returnerar.

Kommentar

Kontrollera att din Microsoft Entra-app har konfigurerats med de omfång som krävs av webbappen. Mer information finns i Ändra behörigheter för din Microsoft Entra-app.

1. Skapa en ny mapp med namnet Tjänster i appens projekt.

2. I mappen Tjänster skapar du en ny fil med namnet PowerBiServiceApi.cs.

3. Lägg till följande kod i 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
               };
           }
   
       }
   }
   

Ändra filen HomeController.cs

I det här kodexemplet använder du beroendeinmatning för att ändra filen HomeController.cs . Genom att följa ett tidigare steg konfigurerade PowerBiServiceApi du klassen som en tjänst genom att anropa services.AddScoped i ConfigureServices -metoden. Med den här koden lägger du till en PowerBiServiceApi parameter i konstruktorn och .NET Core-körningen skapar en PowerBiServiceApi instans och skickar den till konstruktorn.

Öppna filen HomeController.cs från mappen Controllers och lägg till följande kod i den:

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

Steg 5 – Skapa appens klientsida

För implementering på klientsidan måste du skapa eller ändra de filer som visas i följande tabell:

Fil	Använd
embed.js	Innehåller JavaScript-koden på klientsidan
Embed.cshtml	Innehåller appens dokumentobjektmodell (DOM) och en DIV för att bädda in rapporten

Skapa en container för din inbäddade rapport

I den här självstudien skapar du filen Embed.cshtml , som har ett div element som är en container för din inbäddade rapport och tre skript.

1. I mappen Visa/start skapar du en fil med namnet Embed.cshtml.

2. Lägg till följande kod i filen 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>
   }
   

Lägg till JavaScript på klientsidan för att bädda in rapporten

Om du vill bädda in Power BI-innehåll måste du skapa ett konfigurationsobjekt. Mer information om hur du skapar konfigurationsobjektet finns i Bädda in en rapport.

I den här självstudien skapar du en JavaScript-fil med namnet embed.js med ett konfigurationsobjekt för att bädda in rapporten som använder variabeln models.

Du kan initiera models med hjälp av ett anrop till window['powerbi-client'].models. Variabeln models används för att ange konfigurationsvärden som models.Permissions.All, models.TokenType.Aadoch models.ViewMode.View.

Funktionen powerbi.embed använder konfigurationsobjektet models för att bädda in rapporten.

1. I mappen wwwroot/js skapar du en fil med namnet embed.js.

2. Lägg till följande kod i filen embed.js .

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

Steg 6 – Kör programmet

När du har följt alla tidigare steg är du redo att köra programmet. Prova att köra programmet och experimentera med hur Din Power BI-rapport är inbäddad. Du kan använda Api:er för Power BI Embedded-analysklienten för att förbättra din app med hjälp av API:er på klientsidan.

Viktigt!

Om du använde kostnadsfria utvärderingstoken för inbäddning för utveckling måste du köpa en kapacitet för produktion. Tills en kapacitet har köpts fortsätter banderollen för den kostnadsfria utvärderingsversionen att visas överst i den inbäddade rapporten.

När appen är klar kan du flytta den inbäddade appen till produktion.

Relaterat innehåll

Inbäddade analysprogramtoken

Flytta din inbäddade app till produktion

Kapacitet och SKU:er i Power BI Embedded-analys

Kapacitetsplanering i Power BI Embedded-analys