Kurz: Vložení sestavy Power BI do aplikace pro zákazníky
V tomto kurzu se dozvíte, jak vložit sestavu Power BI do aplikace .NET 5.0 jako součást řešení pro vložení pro vaše zákazníky (označované také jako řešení app-owns-data). V řešení pro vložení pro vaše zákazníky se uživatelé vaší aplikace nemusí přihlašovat k Power BI ani mít licenci Power BI.
V tomto kurzu se dozvíte, jak vložit:
- Sestava Power BI
- V aplikaci embed-for-your-customers.
- Pomocí instančního objektu.
- Pomocí .NET 5.0.
- S knihovnou
Microsoft.Identity.Web
(tato knihovna je také podporována v .NET Core).
Poznámka:
Úplné řešení použité v tomto kurzu je k dispozici v úložišti GitHubu DOTNET5-AppOwnsData-Tutorial .
Požadavky
Pracovní prostor Power BI se sestavou
Vlastní tenant Microsoft Entra
Aplikace Microsoft Entra
Aplikace kontroleru zobrazení modelu .NET Core 5 (MVC)
.NET Core 5 SDK nebo novější
Integrované vývojové prostředí (IDE). Doporučujeme jedno z následujících prostředí IDE:
Visual Studio Code s rozšířením jazyka C#
Zdroje informací
V tomto kurzu použijete:
Rozhraní REST Reports API Power BI pro vložení adresy URL a načtení tokenu pro vložení
Klientská rozhraní API vložených analytických možností Power BI pro vložení sestavy
metoda
Pokud chcete vložit obsah Power BI do řešení pro vložení pro vaše zákazníky, postupujte takto:
Získejte hodnoty parametrů pro vložení.
Přidejte požadované balíčky NuGet.
Povolte ověřování na straně serveru.
Sestavte na straně klienta vaší aplikace.
Krok 1 : Konfigurace aplikace a instančního objektu Microsoft Entra
V tomto kurzu použijete instanční objekt k ověření webové aplikace na základě ID Microsoft Entra. Potřebujete také aplikaci Microsoft Entra, která umožňuje vygenerovat token Microsoft Entra. Pomocí tokenu Microsoft Entra může vaše webová aplikace volat rozhraní REST API Power BI a vkládat položky Power BI, jako jsou sestavy, řídicí panely a dlaždice.
Podle pokynů instančního objektu vytvořte aplikaci Microsoft Entra a povolte instančnímu objektu aplikace pracovat s obsahem Power BI.
Krok 2 – získání hodnot vložených parametrů
K vložení sestavy potřebujete následující hodnoty:
ID domény a tenanta
Pokud neznáte svoji doménu nebo ID tenanta, přečtěte si téma Vyhledání ID tenanta Microsoft Entra a název primární domény.
Poznámka:
Pokud chcete vložit obsah pro uživatele do jiného tenanta (uživatele typu host), musíte upravit authorityUri
parametr.
Client ID
Pokud chcete získat identifikátor GUID ID klienta (označovaný také jako ID aplikace), postupujte takto:
Přihlaste se k Microsoft Azure.
Vyhledejte Registrace aplikací a vyberte odkaz Registrace aplikací.
Vyberte aplikaci Microsoft Entra, kterou používáte pro vložení obsahu Power BI.
V části Přehled zkopírujte identifikátor GUID ID aplikace (klienta).
Tajný klíč klienta
Tajný klíč klienta získáte takto:
Přihlaste se k Microsoft Azure.
Vyhledejte Registrace aplikací a vyberte odkaz Registrace aplikací.
Vyberte aplikaci Microsoft Entra, kterou používáte pro vložení obsahu Power BI.
V části Spravovat vyberte Certifikáty a tajné kódy.
V části Tajné kódy klienta vyberte Nový tajný klíč klienta.
V automaticky otevírané okně Přidat tajný klíč klienta zadejte popis tajného kódu aplikace, vyberte, kdy vyprší platnost tajného kódu aplikace, a vyberte Přidat.
V části Tajné kódy klienta zkopírujte řetězec ve sloupci Hodnota nově vytvořeného tajného kódu aplikace. Hodnota tajného klíče klienta je VAŠE ID klienta.
Poznámka:
Ujistěte se, že při prvním zobrazení zkopírujete hodnotu tajného klíče klienta. Po přechodu mimo tuto stránku bude tajný klíč klienta skrytý a nebudete moct načíst jeho hodnotu.
ID pracovního prostoru
Pokud chcete získat identifikátor GUID ID pracovního prostoru, postupujte takto:
Přihlaste se ke službě Power BI.
Otevřete sestavu, kterou chcete vložit.
Zkopírujte identifikátor GUID z adresy URL. Identifikátor GUID je číslo mezi /groups/ a /reports/.
Poznámka:
K získání ID pracovního prostoru prostřednictvím kódu programu použijte rozhraní API Získat skupiny .
ID sestavy
Pokud chcete získat identifikátor GUID ID sestavy, postupujte takto:
Přihlaste se ke službě Power BI.
Otevřete sestavu, kterou chcete vložit.
Zkopírujte identifikátor GUID z adresy URL. Identifikátor GUID je číslo mezi /reports/ a /ReportSection.
Poznámka:
Id sestavy získáte programově pomocí rozhraní API Získat sestavy ve skupině .
Krok 3 : Přidání požadovaných balíčků NuGet
Než začnete, musíte do své aplikace přidat Microsoft.Identity.Web
balíčky NuGet a Microsoft.PowerBI.Api
.
Přidejte do aplikace požadované balíčky NuGet:
Ve VS Code otevřete terminál a zadejte následující kód.
V sadě Visual Studio přejděte na Nástroje>NuGet Správce balíčků> Správce balíčků konzolu a zadejte následující kód.
dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api
Krok 4 – Povolení ověřování na straně serveru
Zapněte ověřování na straně serveru v aplikaci vytvořením nebo úpravou souborů v následující tabulce.
Soubor | Používání |
---|---|
Startup.cs | Inicializace Microsoft.Identity.Web ověřovací služby |
appsettings.json | Konfigurace podrobností o ověřování |
PowerBiServiceApi.cs | Získání tokenu Microsoft Entra a vkládání metadat |
HomeController.cs | Předání dat vložení jako modelu do zobrazení |
Konfigurace spouštěcího souboru pro podporu Microsoft.Identity.Web
Upravte kód v Startup.cs tak, aby správně inicializoval ověřovací službu poskytovanou Microsoft.Identity.Web
.
Do souboru Startup.cs aplikace přidejte následující kód.
Poznámka:
Kód v ConfigureServices
rámci provádění několika důležitých věcí:
- Volání
AddMicrosoftWebAppCallsWebApi
konfiguruje knihovnu Microsoft Authentication Library pro získání přístupových tokenů (tokeny Microsoft Entra). - Volání
AddInMemoryTokenCaches
konfiguruje mezipaměť tokenů, kterou knihovna Microsoft Authentication Library používá k ukládání přístupových tokenů do mezipaměti a obnovovacích tokenů na pozadí. - Volání
services.AddScoped(typeof(PowerBiServiceApi))
konfigurujePowerBiServiceApi
třídu jako třídu služby, kterou lze přidat do jiných tříd pomocí injektáže závislostí.
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();
});
}
}
}
Vytvoření souboru s podrobnostmi o ověřování
V tomto kurzu soubor appsettings.json obsahuje citlivé informace, jako je ID klienta a tajný klíč klienta. Z bezpečnostníchdůvodůch Při vkládání do aplikace zvažte bezpečnější nástroj, jako je Azure Key Vault, pro zabezpečení citlivých informací.
V projektu vytvořte nový soubor a pojmenujte ho appsettings.json.
Do appsettings.json přidejte následující kód:
{ "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": "*" }
Vyplňte hodnoty vložených parametrů získané z kroku 2 – Získání hodnot vložených parametrů.
Domain
- ID domény a tenantaTenantId
- ID domény a tenantaClientId
- ID klientaClientSecret
- Tajný klíč klienta
Poznámka:
V předchozím kódu se parametr přidá jako vlastní konfigurační hodnota pro PowerBi:ServiceRootUrl
sledování základní adresy URL služba Power BI. Když programujete proti služba Power BI ve veřejném cloudu Microsoftu, adresa URL je https://api.powerbi.com/
. Kořenová adresa URL služba Power BI se ale liší v jiných cloudech, jako je cloud státní správy. Proto je vlastní hodnota konfigurace uložena jako hodnota konfigurace projektu, takže ji můžete podle potřeby změnit.
Získání přístupového tokenu Microsoft Entra a volání služba Power BI
Aby bylo možné vkládat obsah Power BI, jako jsou sestavy a řídicí panely, musí vaše aplikace získat token Microsoft Entra. K získání tokenu potřebujete objekt konfigurace.
Kód v této části používá model injektáže závislostí .NET Core. Pokud vaše třída potřebuje použít službu, můžete pro tuto službu přidat parametr konstruktoru. Modul runtime .NET Core se postará o předání instance služby za běhu. V tomto případě konstruktor vloží instanci konfigurační služby .NET Core pomocí parametru IConfiguration
, který se používá k načtení PowerBi:ServiceRootUrl
hodnoty konfigurace z appsettings.json. Parametr ITokenAcquisition
, který je pojmenován tokenAcquisition
, obsahuje odkaz na ověřovací službu Microsoftu poskytovanou knihovnou Microsoft.Identity.Web
. Tento ITokenAcquisition
parametr se používá k získání přístupových tokenů z ID Microsoft Entra.
Pole RequiredScopes
obsahuje pole řetězců, které obsahuje sadu delegovaných oprávnění podporovaných rozhraním API služba Power BI. Když vaše aplikace volá přes síť k získání tokenu Microsoft Entra, předá tuto sadu delegovaných oprávnění, aby je Microsoft Entra ID mohl zahrnout do přístupového tokenu, který vrátí.
Poznámka:
Ověřte, že je vaše aplikace Microsoft Entra nakonfigurovaná s obory vyžadovanými vaší webovou aplikací. Další informace najdete v tématu Změna oprávnění aplikace Microsoft Entra.
V projektu aplikace vytvořte novou složku s názvem Služby.
Ve složce Služby vytvořte nový soubor s názvem PowerBiServiceApi.cs.
Do PowerBiServiceApi.cs přidejte následující kód.
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 }; } } }
Úprava souboru HomeController.cs
V tomto příkladu kódu použijete injektáž závislostí k úpravě souboru HomeController.cs . Podle předchozího kroku jste nakonfigurovali PowerBiServiceApi
třídu jako službu voláním services.AddScoped
metody ConfigureServices
. S tímto kódem přidáte do konstruktoru PowerBiServiceApi
parametr a modul runtime .NET Core vytvoří PowerBiServiceApi
instanci a předá ji konstruktoru.
Ve složce Controllers otevřete soubor HomeController.cs a přidejte do něj následující kód:
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 });
}
}
}
Krok 5 : Sestavení klientské strany aplikace
Pro implementaci na straně klienta je potřeba vytvořit nebo upravit soubory uvedené v následující tabulce:
Soubor | Používání |
---|---|
embed.js | Obsahuje kód JavaScriptu na straně klienta. |
Embed.cshtml | Obsahuje objektový model dokumentu vaší aplikace (DOM) a div pro vložení sestavy. |
Vytvoření kontejneru pro vloženou sestavu
V tomto kurzu vytvoříte soubor Embed.cshtml , který obsahuje div
element, který je kontejnerem pro vloženou sestavu, a tři skripty.
Ve složce Domů zobrazení/vytvořte soubor s názvem Embed.cshtml.
Do souboru Embed.cshtml přidejte následující kód.
@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> }
Přidání JavaScriptu na straně klienta pro vložení sestavy
Pokud chcete vložit obsah Power BI, musíte vytvořit objekt konfigurace. Další informace o vytvoření objektu konfigurace najdete v tématu Vložení sestavy.
V tomto kurzu vytvoříte javascriptový soubor s názvem embed.js s objektem konfigurace pro vložení sestavy, která používá proměnnou models
.
Inicializovat models
můžete pomocí volání window['powerbi-client'].models
. Proměnná models
se používá k nastavení konfiguračních hodnot, jako models.Permissions.All
je , models.TokenType.Aad
a models.ViewMode.View
.
Funkce powerbi.embed
používá models
objekt konfigurace k vložení sestavy.
Ve složce wwwroot/js vytvořte soubor s názvem embed.js.
Do souboru embed.js přidejte následující kód.
$(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); }); });
Krok 6 : Spuštění aplikace
Po provedení všech předchozích kroků jste připraveni spustit aplikaci. Zkuste spustit aplikaci a experimentujte se způsobem, jakým je sestava Power BI vložená. Klientská rozhraní API vložených analýz Power BI můžete použít k vylepšení aplikace pomocí rozhraní API na straně klienta.
Důležité
Pokud jste pro vývoj použili bezplatné zkušební tokeny pro vložení, musíte si koupit kapacitu pro produkční prostředí. Dokud není zakoupena kapacita, bude se v horní části vložené sestavy zobrazovat banner bezplatné zkušební verze .
Až bude vaše aplikace připravená, můžete vloženou aplikaci přesunout do produkčního prostředí.