Öğretici: Müşterileriniz için bir uygulamaya Power BI raporu ekleme

Bu öğreticide, embed-for-your-customers (app-owns-data) çözümünün parçası olarak .NET 8.0 uygulamasına Power BI raporu 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 gömülü uygulamada.
  • Hizmet sorumlusu kullanarak.
  • .NET 8.0 kullanarak.
  • Microsoft.Identity.Web kitaplığı üzerinde (bu kitaplık .NET Core'da desteklenir).

Not

Bu öğreticide kullanılan çözümün tamamına PowerBI-Developer-Samples GitHub deposundan ulaşabilirsiniz.

Önkoşullar

Kaynaklar

Bu öğreticide şunları kullanacaksınız:

Metot

Power BI içeriğini müşterileriniz için ekleme çözümüne eklemek için şu adımları izleyin:

  1. Microsoft Entra uygulamanızı ve hizmet sorumlunuzu yapılandırın.

  2. Ekleme parametresi değerlerini alın.

  3. Gerekli NuGet paketlerini ekleyin.

  4. Sunucu tarafı kimlik doğrulamasını etkinleştirin.

  5. Uygulamanızın istemci tarafını oluşturun.

  6. 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 kimlik doğrulamasını Microsoft Entra ID karşısında yapmak için bir servis ilkesi kullanacaksınız. 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.

Bir Microsoft Entra uygulaması oluşturmak ve uygulamanın hizmet sorumlusunun Power BI içeriğinizle çalışmasını sağlamak için hizmet sorumlusu yönergelerini izleyin.

2. Adım - Ekleme parametresi değerlerini alma

Raporunuzu eklemek için aşağıdaki değerlere ihtiyacınız vardır:

Alan adı ve kiracı kimliği

Eğer etki alanınızı veya kiracı kimliğinizi bilmiyorsanız, Microsoft Entra kiracı kimliğini ve birincil etki alanı adını bulma sayfasına bakın.

Not

Kullanıcının içeriğini farklı bir kiracıya (konuk kullanıcı) eklemek için parametresini authorityUri ayarlamanız gerekir.

Müşteri Kimliği

İstemci kimliği GUID'sini ( uygulama kimliği olarak da bilinir) almak için şu adımları izleyin:

  1. Microsoft Azure'da oturum açın.

  2. Uygulama kayıtları arayın ve Uygulama kayıtları bağlantısını seçin.

  3. Power BI içeriğinizi eklemek için kullandığınız Microsoft Entra uygulamasını seçin.

  4. Genel Bakış bölümünden Uygulama (istemci) Kimliği GUID'sini kopyalayın.

İstemci sırrı

İstemci gizli anahtarını almak için şu adımları izleyin:

  1. Microsoft Azure'da oturum açın.

  2. Uygulama kayıtları arayın ve Uygulama kayıtları bağlantısını seçin.

  3. Power BI içeriğinizi eklemek için kullandığınız Microsoft Entra uygulamasını seçin.

  4. Yönet altında Sertifikalar ve Gizli Diziler'i seçin.

  5. İstemci sırlarının altında Yeni istemci sırrını seçin.

  6. İ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.

  7. İ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üğü anda kopyaladığınızdan emin olun. Bu sayfadan uzaklaştıktan sonra istemci sırrı artık görüntülenmeyecek ve değerini bir daha görüntüleyemezsiniz.

Çalışma Alanı Kimliği

Çalışma alanı kimliği GUID'sini almak için şu adımları izleyin:

  1. Power BI hizmetinde oturum açma.

  2. Eklemek istediğiniz raporu açın.

  3. URL'den GUID'yi kopyalayın. GUID, /groups/ ve /reports/ arasındaki sayıdır.

    Power BI hizmeti URL'sinde çalışma alanı kimliği GUID'sini gösteren ekran görüntüsü

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:

  1. Power BI hizmetinde oturum açma.

  2. Eklemek istediğiniz raporu açın.

  3. URL'den GUID'yi kopyalayın. GUID, /reports/ ve /ReportSection arasındaki sayıdır.

    Power BI hizmeti U R L'de rapor kimliği GUID'sini gösteren ekran görüntüsü

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.Identity.Web NuGet paketlerini uygulamanıza eklemeniz Microsoft.PowerBI.Apigerekir.

Gerekli NuGet paketlerini uygulamanıza ekleyin:

  • VS Code'da bir terminal açın ve aşağıdaki kodu girin.

  • Visual Studio'da Araçlar>> bölümüne 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 Kullan
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 sağlanan kimlik doğrulama hizmetini düzgün bir şekilde başlatmak için Startup.cs içindeki kodu 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:

  1. ç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.
  2. AddInMemoryTokenCaches fonksiyonu, Microsoft Kimlik Doğrulama Kitaplığı tarafından erişim belirteçlerini ve yenileme belirteçlerini arka planda önbelleğe almak için kullanılan bir belirteç önbelleğini yapılandırır.
  3. services.AddScoped(typeof(PowerBiServiceApi)) çağrısı, PowerBiServiceApi sınıfını bağımlılık enjeksiyonu kullanarak diğer sınıflara eklenebilen bir hizmet sınıfı olarak yapılandırır.
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 anahtarı 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.

  1. Projenizde yeni bir dosya oluşturun ve appsettings.json olarak adlandırınız.

  2. 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": "*"
}

  3. 2. Adım - Ekleme parametresi değerlerini alma bölümünden alınan ekleme parametresi değerlerini doldurun.

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 bulutunda Power BI hizmetiyle programlarken, URL adresi https://api.powerbi.com/ şeklindedir. 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 jetonunu alın ve Power BI hizmetini çağırın

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, IConfiguration parametresini kullanarak .NET Core yapılandırma hizmetinin bir örneğini enjekte eder ve PowerBi:ServiceRootUrl, appsettings.json dosyasından yapılandırma değerini almak için kullanılır. ITokenAcquisition adlı tokenAcquisition parametresi, Microsoft.Identity.Web kitaplığı tarafından sağlanan Microsoft kimlik doğrulama hizmetine bir referans tutar. 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, Microsoft Entra belirteci almak için ağ üzerinden çağrı yaptığında, Microsoft Entra ID'nin bunları döndüreceği erişim belirtecine ekleyebilmesi için bu temsilci izinleri kümesini iletir.

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.

  1. Uygulamanızın projesinde Hizmetler adlı yeni bir klasör oluşturun.

  2. Hizmetler klasöründe PowerBiServiceApi.cs adlı yeni bir dosya oluşturun.

  3. 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, PowerBiServiceApi yönteminde services.AddScoped çağrısını yaparak ConfigureServices sınıfını bir hizmet olarak yapılandırdınız. 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 Kullan
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, gömülü raporunuz için bir kapsayıcı olan Embed.cshtml dosyasını ve üç betiği içeren bir div öğesi oluşturuyorsunuz.

  1. Giriş Sayfasını Görüntüle/klasöründe Embed.cshtml adlı bir dosya oluşturun.

  2. 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, raporunuzu eklemek için bir yapılandırma nesnesi içeren `embed.js` adlı bir JavaScript dosyası oluşturacaksınız; bu, değişken `models` kullanır.

models kullanarak window['powerbi-client'].models çağrısı ile başlatabilirsiniz. models değişkeni, , models.Permissions.Allve models.TokenType.Aadgibi models.ViewMode.Viewyapılandırma değerlerini ayarlamak için kullanılır.

powerbi.embed işlevi raporunuzu gömmek için models yapılandırma nesnesini kullanır.

  1. wwwroot/js klasöründe embed.js adlı bir dosya oluşturun.

  2. 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 embed deneme tokenları 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.

İlgili içerik

  • Last updated on