Öğ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).

Dekont

Bu öğreticide kullanılan çözümün tamamına DOTNET5-AppOwnsData-Tutorial 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 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.

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:

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.

Dekont

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:

  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 gizli anahtarı

İstemci gizli dizisini 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'in altında Sertifikalar ve gizli diziler'i seçin.

  5. İstemci gizli dizileri'nin altında Yeni istemci gizli dizisi'ni 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.

Dekont

İ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:

  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.

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

Dekont

Ç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.

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

Dekont

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.Webgerekir.

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.Websağlanan kimlik doğrulama hizmetini düzgün bir şekilde başlatmak için Startup.cs dosyasındaki kodu değiştirin.

Uygulamanızın Startup.cs dosyasına aşağıdaki kodu ekleyin.

Dekont

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. ç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.
  3. ç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ır PowerBiServiceApi .
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ırabilirsiniz.

  2. appsettings.json dosyasına 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.

Dekont

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, appsettings.json dosyasından yapılandırma değerini almak PowerBi:ServiceRootUrl için kullanılan parametresini IConfiguration kullanarak .NET Core yapılandırma hizmetinin bir örneğini ekler. ITokenAcquisition adlı tokenAcquisitionparametresi, 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.

Dekont

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 dosyasına 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.AddScopedConfigureServices 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.

Controllers 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.

  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, değişkenini modelskullanan raporunuzu eklemek için yapılandırma nesnesiyle embed.js adlı bir JavaScript dosyası oluşturacaksınız.

çağrısı window['powerbi-client'].modelskullanarak başlatabilirsinizmodels. models değişkeni, , models.TokenType.Aadve models.ViewMode.Viewgibi models.Permissions.Allyapılandırma değerlerini ayarlamak için kullanılır.

İşlev, powerbi.embed raporunuzu eklemek için yapılandırma nesnesini kullanır models .

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

  2. Embed.js dosyasına aşağıdaki kodu 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.