Öğretici: Müşterileriniz için bir uygulamaya Power BI raporu ekleme
Bu öğreticide, bir Power BI raporunu bir .NET 5.0 uygulamasına, müşterileriniz için ekleme (uygulama-kendi verileri olarak da bilinir) çözümünün bir parçası olarak eklemeyi öğreneceksiniz. Müşterileriniz için ekleme çözümünde, uygulama kullanıcılarınızın Power BI'da oturum açması veya Power BI lisansına sahip olması gerekmez.
Bu öğreticide şunları eklemeyi öğreneceksiniz:
- Power BI raporu.
- Müşterileriniz için ekleme uygulamasında.
- Hizmet sorumlusu kullanarak.
- .NET 5.0 kullanarak.
- Kitaplığı ile
Microsoft.Identity.Web
(bu kitaplık .NET Core'da da desteklenir).
Not
Bu öğreticide kullanılan çözümün tamamına DOTNET5-AppOwnsData-Tutorial GitHub deposundan ulaşabilirsiniz.
Önkoşullar
Power BI Pro veya Kullanıcı Başına Premium (PPU) lisansı
Rapor içeren bir Power BI çalışma alanı
Microsoft Entra uygulaması
.NET Core 5 model görünüm denetleyicisi (MVC) uygulaması
.NET Core 5 SDK veya üzeri
Tümleşik bir geliştirme ortamı (IDE). Aşağıdaki IDE'lerden birini öneririz:
Kaynaklar
Bu öğreticide şunları kullanacaksınız:
URL'yi eklemek ve ekleme belirtecini almak için Power BI REST Raporları API'si.
Raporu eklemek için Power BI tümleşik analiz İstemci API'leri.
Metot
Power BI içeriğini müşterileriniz için ekleme çözümüne eklemek için şu adımları izleyin:
Microsoft Entra uygulamanızı ve hizmet sorumlunuzu yapılandırın.
Gerekli NuGet paketlerini ekleyin.
Sunucu tarafı kimlik doğrulamasını etkinleştirin.
Uygulamanızın istemci tarafını oluşturun.
Uygulamanızı çalıştırın.
1. Adım - Microsoft Entra uygulamanızı ve hizmet sorumlunuzu yapılandırma
Bu öğreticide, web uygulamanızın kimliğini Microsoft Entra Id ile doğrulamak için bir hizmet sorumlusu kullanacaksınız. Ayrıca bir Microsoft Entra belirteci oluşturmayı mümkün kılan bir Microsoft Entra uygulamasına da ihtiyacınız vardır. Web uygulamanız, Microsoft Entra belirtecini kullanarak Power BI REST API'lerini çağırabilir ve raporlar, panolar ve kutucuklar gibi Power BI öğelerini ekleyebilir.
2. Adım - Ekleme parametresi değerlerini alma
Raporunuzu eklemek için aşağıdaki değerlere ihtiyacınız vardır:
Etki alanı ve kiracı kimliği
Etki alanınızı veya kiracı kimliğinizi bilmiyorsanız bkz . Microsoft Entra kiracı kimliğini ve birincil etki alanı adını bulma.
Not
Kullanıcının içeriğini farklı bir kiracıya (konuk kullanıcı) eklemek için parametresini authorityUri
ayarlamanız gerekir.
Client ID
İstemci kimliği GUID'sini (uygulama kimliği olarak da bilir) almak için şu adımları izleyin:
Uygulama kayıtları arayın ve Uygulama kayıtları bağlantısını seçin.
Power BI içeriğinizi eklemek için kullandığınız Microsoft Entra uygulamasını seçin.
Genel Bakış bölümünden Uygulama (istemci) Kimliği GUID'sini kopyalayın.
İstemci gizli anahtarı
İstemci gizli dizisini almak için şu adımları izleyin:
Uygulama kayıtları arayın ve Uygulama kayıtları bağlantısını seçin.
Power BI içeriğinizi eklemek için kullandığınız Microsoft Entra uygulamasını seçin.
Yönet'in altında Sertifikalar ve gizli diziler'i seçin.
İstemci gizli dizileri'nin altında Yeni istemci gizli dizisi'ni seçin.
İstemci gizli dizisi ekle açılır penceresinde, uygulama gizli diziniz için bir açıklama sağlayın, uygulama gizli dizisinin süresinin ne zaman doleceğini seçin ve Ekle'yi seçin.
İstemci gizli dizileri bölümünden, yeni oluşturulan uygulama gizli dizisinin Value sütunundaki dizeyi kopyalayın. İstemci gizli anahtarı değeri, istemci kimliğinizdir.
Not
İstemci gizli anahtarı değerini ilk göründüğünde kopyaladığınızdan emin olun. Bu sayfadan uzaklaştıktan sonra gizli dizi gizlenir ve değerini alamazsınız.
Çalışma Alanı Kimliği
Çalışma alanı kimliği GUID'sini almak için şu adımları izleyin:
Power BI hizmetinde oturum açma.
Eklemek istediğiniz raporu açın.
URL'den GUID'yi kopyalayın. GUID, /groups/ ve /reports/ arasındaki sayıdır.
Not
Çalışma alanı kimliğini program aracılığıyla almak için Get Groups API'sini kullanın.
Rapor Kimliği
Rapor kimliği GUID'sini almak için şu adımları izleyin:
Power BI hizmetinde oturum açma.
Eklemek istediğiniz raporu açın.
URL'den GUID'yi kopyalayın. GUID, /reports/ ve /ReportSection arasındaki sayıdır.
Not
Rapor kimliğini program aracılığıyla almak için Gruptaki Raporları Al API'sini kullanın.
3. Adım - Gerekli NuGet paketlerini ekleme
Başlamadan önce , ve Microsoft.PowerBI.Api
NuGet paketlerini uygulamanıza eklemeniz Microsoft.Identity.Web
gerekir.
Gerekli NuGet paketlerini uygulamanıza ekleyin:
VS Code'da bir terminal açın ve aşağıdaki kodu girin.
Visual Studio'da Araçlar>NuGet Paket Yöneticisi> Paket Yöneticisi Konsolu'na gidin ve aşağıdaki kodu yazın.
dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI
dotnet add package Microsoft.PowerBI.Api
4. Adım - Sunucu tarafı kimlik doğrulamasını etkinleştirme
Aşağıdaki tabloda yer alan dosyaları oluşturarak veya değiştirerek uygulamanızda sunucu tarafı kimlik doğrulamasını açın.
Dosya | Kullanma |
---|---|
Startup.cs | Microsoft.Identity.Web Kimlik doğrulama hizmetini başlatma |
appsettings.json | Kimlik doğrulama ayrıntılarını yapılandırma |
PowerBiServiceApi.cs | Microsoft Entra belirtecini alma ve meta verileri ekleme |
HomeController.cs | Ekleme verilerini görünüme model olarak geçirme |
Başlangıç dosyanızı destekleyecek şekilde yapılandırma Microsoft.Identity.Web
tarafından Microsoft.Identity.Web
sağlanan kimlik doğrulama hizmetini düzgün bir şekilde başlatmak için Startup.cs kodunu değiştirin.
Uygulamanızın Startup.cs dosyasına aşağıdaki kodu ekleyin.
Not
içindeki ConfigureServices
kod birkaç önemli şeyi gerçekleştirir:
- çağrısı
AddMicrosoftWebAppCallsWebApi
, erişim belirteçleri (Microsoft Entra belirteçleri) almak için Microsoft Kimlik Doğrulama Kitaplığı'nı yapılandırıyor. - çağrısı
AddInMemoryTokenCaches
, Microsoft Kimlik Doğrulama Kitaplığı'nın arka planda erişim belirteçlerini önbelleğe almak ve belirteçleri yenilemek için kullandığı bir belirteç önbelleğini yapılandırır. - çağrısı
services.AddScoped(typeof(PowerBiServiceApi))
, sınıfı bağımlılık ekleme kullanılarak diğer sınıflara eklenebilen bir hizmet sınıfı olarak yapılandırılırPowerBiServiceApi
.
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();
});
}
}
}
Kimlik doğrulama ayrıntıları dosyası oluşturma
Bu öğreticide, appsettings.json dosyası istemci kimliği ve istemci gizli dizisi gibi hassas bilgiler içerir. Güvenlik nedeniyle, bu bilgileri ayarlar dosyasında tutmanızı önermeyiz. Uygulamanıza eklerken, hassas bilgilerin güvenliğini sağlamak için Azure Key Vault gibi daha güvenli bir araç kullanmayı göz önünde bulundurun.
Projenizde yeni bir dosya oluşturun ve appsettings.json olarak adlandırınız.
appsettings.json aşağıdaki kodu ekleyin:
{ "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": "*" }
2. Adım - Ekleme parametresi değerlerini alma bölümünden alınan ekleme parametresi değerlerini doldurun.
Domain
- Etki alanı ve kiracı kimliğiTenantId
- Etki alanı ve kiracı kimliğiClientId
- İstemci kimliğiClientSecret
- İstemci gizli anahtarı
Not
Yukarıdaki kodda PowerBi:ServiceRootUrl
parametresi, Power BI hizmeti temel URL'sini izlemek için özel bir yapılandırma değeri olarak eklenir. Microsoft genel bulutundaki Power BI hizmeti karşı programladığınızda URL şeklindedirhttps://api.powerbi.com/
. Ancak Power BI hizmeti kök URL'si, kamu bulutu gibi diğer bulutlarda farklıdır. Bu nedenle, özel yapılandırma değeri proje yapılandırma değeri olarak depolanır, böylece gerektiğinde değiştirebilirsiniz.
Microsoft Entra erişim belirtecini alın ve Power BI hizmeti
Raporlar ve panolar gibi Power BI içeriğini eklemek için uygulamanızın bir Microsoft Entra belirteci alması gerekir. Belirteci almak için bir yapılandırma nesnesi gerekir.
Bu bölümdeki kod .NET Core bağımlılık ekleme desenini kullanır. Sınıfınızın bir hizmet kullanması gerektiğinde, bu hizmet için bir oluşturucu parametresi ekleyebilirsiniz. .NET Core çalışma zamanı, hizmet örneğini çalışma zamanında geçirme işlemini üstlenir. Bu durumda oluşturucu, yapılandırma değerini appsettings.json almak için kullanılan parametresini IConfiguration
kullanarak .NET Core yapılandırma hizmetinin bir örneğini PowerBi:ServiceRootUrl
ekler. ITokenAcquisition
adlı tokenAcquisition
parametresi, kitaplık tarafından sağlanan Microsoft kimlik doğrulama hizmetine bir başvuru tutarMicrosoft.Identity.Web
. ITokenAcquisition
parametresi, Microsoft Entra Id'den erişim belirteçleri almak için kullanılır.
alanı, RequiredScopes
Power BI hizmeti API tarafından desteklenen temsilci izinleri kümesini içeren bir dize dizisi içerir. Uygulamanız bir Microsoft Entra belirteci almak için ağ üzerinden çağırdığında, Microsoft Entra Id'nin bunları döndürdüğü erişim belirtecine ekleyebilmesi için bu temsilci izinleri kümesini geçirir.
Not
Microsoft Entra uygulamanızın web uygulamanızın gerektirdiği kapsamlarla yapılandırıldığını doğrulayın. Daha fazla bilgi için bkz . Microsoft Entra uygulamanızın izinlerini değiştirme.
Uygulamanızın projesinde Hizmetler adlı yeni bir klasör oluşturun.
Hizmetler klasöründe PowerBiServiceApi.cs adlı yeni bir dosya oluşturun.
aşağıdaki kodu PowerBiServiceApi.cs ekleyin.
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 }; } } }
HomeController.cs dosyasını değiştirme
Bu kod örneğinde, HomeController.cs dosyasını değiştirmek için bağımlılık ekleme özelliğini kullanırsınız. Önceki bir adımı izleyerek yöntemini çağırarak services.AddScoped
ConfigureServices
sınıfını bir hizmet olarak yapılandırmıştınızPowerBiServiceApi
. Bu kodla oluşturucuya bir PowerBiServiceApi
parametre eklersiniz ve .NET Core çalışma zamanı bir PowerBiServiceApi
örnek oluşturur ve oluşturucuya geçirir.
Denetleyiciler klasöründen HomeController.cs dosyasını açın ve aşağıdaki kodu ekleyin:
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 });
}
}
}
5. Adım - Uygulamanızın istemci tarafını oluşturma
İstemci tarafı uygulaması için, aşağıdaki tabloda listelenen dosyaları oluşturmanız veya değiştirmeniz gerekir:
Dosya | Kullanma |
---|---|
embed.js | İstemci tarafı JavaScript kodunu içerir |
Embed.cshtml | Uygulamanızın belge nesne modelini (DOM) ve raporu eklemek için bir DIV içerir |
Eklenmiş raporunuz için kapsayıcı oluşturma
Bu öğreticide, katıştırılmış raporunuz için kapsayıcı olan bir div
öğesi ve üç betik içeren Embed.cshtml dosyasını oluşturacaksınız.
Giriş Sayfasını Görüntüle/klasöründe Embed.cshtml adlı bir dosya oluşturun.
Embed.cshtml dosyasına aşağıdaki kodu ekleyin.
@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> }
Raporunuzu eklemek için istemci tarafı JavaScript ekleme
Power BI içeriği eklemek için bir yapılandırma nesnesi oluşturmanız gerekir. Yapılandırma nesnesi oluşturma hakkında daha fazla bilgi edinmek için bkz . Rapor ekleme.
Bu öğreticide, değişkenini models
kullanan raporunuzu eklemek için yapılandırma nesnesiyle embed.js adlı bir JavaScript dosyası oluşturacaksınız.
çağrısı window['powerbi-client'].models
kullanarak başlatabilirsinizmodels
. models
değişkeni, , models.TokenType.Aad
ve models.ViewMode.View
gibi models.Permissions.All
yapılandırma değerlerini ayarlamak için kullanılır.
İşlev, powerbi.embed
raporunuzu eklemek için yapılandırma nesnesini kullanır models
.
wwwroot/js klasöründe embed.js adlı bir dosya oluşturun.
aşağıdaki kodu embed.js dosyasına ekleyin.
$(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); }); });
6. Adım : Uygulamanızı çalıştırma
Önceki tüm adımları izledikten sonra uygulamanızı çalıştırmaya hazırsınız demektir. Uygulamanızı çalıştırmayı deneyin ve Power BI raporunuzun katıştırılmış şekliyle denemeler yapın. İstemci tarafı API'lerini kullanarak uygulamanızı geliştirmek için Power BI tümleşik analiz İstemci API'lerini kullanabilirsiniz.
Önemli
Geliştirme için ücretsiz ekleme deneme belirteçleri kullandıysanız üretim için bir kapasite satın almanız gerekir. Kapasite satın alınana kadar Ücretsiz deneme sürümü başlığı eklenen raporun en üstünde görünmeye devam eder.
Uygulamanız hazır olduğunda, eklenmiş uygulamanızı üretim ortamına taşıyabilirsiniz.