Bagikan melalui

Tutorial: Menyematkan laporan Power BI dalam aplikasi untuk organisasi Anda

  • Artikel

Tutorial ini menjelaskan cara menyematkan laporan Power BI di aplikasi .NET 5.0, sebagai bagian dari penyematan untuk organisasi Anda (juga dikenal sebagai pengguna memiliki data). Dalam penyematan untuk solusi organisasi Anda, pengguna aplikasi Anda perlu mengautentikasi terhadap Power BI dengan kredensial mereka sendiri.

Dalam tutorial ini, Anda mempelajari cara menyematkan:

  • Laporan Power BI
  • Di sematkan untuk aplikasi organisasi Anda
  • Menggunakan .NET 5.0
  • Dengan pustaka Microsoft.Identity.Web (pustaka ini juga didukung di .NET Core)

Catatan

Solusi lengkap yang digunakan dalam tutorial ini, tersedia dari repositori GitHub DOTNET5-UserOwnsData-Tutorial.

Prasyarat

Sumber

Dalam tutorial ini, Anda menggunakan:

Metode

Untuk menyematkan konten Power BI dalam semat untuk solusi organisasi Anda, ikuti langkah-langkah berikut:

  1. Mengonfigurasi aplikasi Microsoft Entra Anda
  2. Mendapatkan nilai parameter penyematan
  3. Tambahkan paket NuGet yang diperlukan
  4. Mengaktifkan autentikasi sisi server
  5. Membangun sisi klien aplikasi Anda
  6. Jalankan aplikasi Anda

Langkah 1 - Mengonfigurasi aplikasi Microsoft Entra Anda

Saat aplikasi web Anda memanggil Power BI, aplikasi ini memerlukan token Microsoft Entra untuk memanggil REST API Power BI dan menyematkan item Power BI seperti laporan, dasbor, atau petak peta.

Jika Anda tidak memiliki aplikasi Microsoft Entra, buat aplikasi menggunakan instruksi di Mendaftarkan aplikasi Microsoft Entra untuk digunakan dengan Power BI.

Untuk mengonfigurasi aplikasi Microsoft Entra Anda, ikuti instruksi di Mengonfigurasi aplikasi Microsoft Entra Anda.

Langkah 2 - Dapatkan nilai parameter penyematan

Untuk menyematkan laporan, Anda memerlukan nilai berikut:

ID domain dan penyewa

Jika Anda tidak mengetahui domain atau ID penyewa Anda, lihat Menemukan ID penyewa Microsoft Entra dan nama domain utama.

Catatan

Untuk menyematkan konten untuk pengguna pada penyewa yang berbeda (pengguna tamu), Anda perlu menyesuaikan parameter authorityUri.

ID klien

Untuk mendapatkan GUID ID klien (juga dikenal sebagai ID aplikasi), ikuti langkah-langkah berikut:

  1. Masuk ke Microsoft Azure.

  2. Cari Pendaftaran aplikasi dan pilih tautan Pendaftaran aplikasi.

  3. Pilih aplikasi Microsoft Entra yang Anda gunakan untuk menyematkan konten Power BI Anda.

  4. Dari bagian Gambaran Umum, salin GUID ID Aplikasi (klien).

Rahasia Klien

Untuk mendapatkan rahasia klien, ikuti langkah-langkah berikut:

  1. Masuk ke Microsoft Azure.

  2. Cari Pendaftaran aplikasi dan pilih tautan Pendaftaran aplikasi.

  3. Pilih aplikasi Microsoft Entra yang Anda gunakan untuk menyematkan konten Power BI Anda.

  4. Di bagian Kelola, pilih Sertifikat & rahasia.

  5. Di bawah Rahasia klien, pilih Rahasia klien baru.

  6. Di jendela pop-up Tambahkan rahasia klien, berikan deskripsi untuk rahasia aplikasi Anda, pilih kapan rahasia aplikasi akan kedaluwarsa, dan pilih Tambahkan.

  7. Dari bagian Rahasia klien, salin string di kolom Nilai rahasia aplikasi yang baru dibuat. Nilai rahasia klien adalah ID klien Anda.

Catatan

Pastikan Anda menyalin nilai rahasia klien saat pertama kali muncul. Setelah keluar dari halaman ini, rahasia klien akan disembunyikan dan Anda tidak akan dapat mengambil nilainya.

ID Ruang Kerja

Untuk mendapatkan GUID ID ruang kerja, ikuti langkah-langkah berikut:

  1. Masuk ke layanan Power BI.

  2. Buka laporan yang ingin Anda sematkan.

  3. Salin GUID dari URL. GUID adalah angka antara /groups/ dan /reports/.

    Cuplikan layar memperlihatkan GUID ID ruang kerja di URL layanan Power BI

Catatan

Untuk mendapatkan ID ruang kerja secara terprogram, gunakan API Dapatkan Grup.

ID Laporan

Untuk mendapatkan GUID ID laporan, ikuti langkah-langkah berikut:

  1. Masuk ke layanan Power BI.

  2. Buka laporan yang ingin Anda sematkan.

  3. Salin GUID dari URL. GUID adalah angka antara /reports/ dan /ReportSection.

    Cuplikan layar memperlihatkan GUID ID laporan di U R L layanan Power B I

Catatan

Untuk mendapatkan ID laporan secara terprogram, gunakan API Dapatkan Laporan di Grup.

Langkah 3 - Tambahkan paket NuGet yang diperlukan

Sebelum memulai, Anda perlu menambahkan paket Microsoft.Identity.Web, dan Microsoft.PowerBI.Api NuGet ke aplikasi Anda.

Tambahkan paket NuGet berikut ke aplikasi Anda:

  • Di Visual Studio Code, buka terminal dan ketik kode berikut.

  • Di Visual studio, navigasikan ke Alat>NuGet Package Manager>Package Manager Console dan ketik kode berikut.

dotnet add package Microsoft.Identity.Web -v 0.3.0-preview
dotnet add package Microsoft.Identity.Web.UI -v 0.3.0-preview
dotnet add package Microsoft.PowerBI.Api

Jika aplikasi Anda sebelumnya digunakan Microsoft.AspNetCore untuk mengautentikasi, hapus paket ini dari proyek Anda dengan mengetik:

dotnet remove package Microsoft.AspNetCore.Authentication.AzureAD.UI

Langkah 4 - Aktifkan autentikasi sisi server

Aktifkan autentikasi sisi server di aplikasi Anda, dengan membuat atau memodifikasi file dalam tabel berikut.

File Menggunakan
Startup.cs Menginisialisasi layanan autentikasi Microsoft.Identity.Web
appsettings.json Detail autentikasi
PowerBiServiceApi.cs Mendapatkan token Microsoft Entra dan menyematkan metadata
HomeController.cs Meneruskan penyematan data sebagai model ke tampilan

Mengonfigurasi file startup Anda untuk mendukung Microsoft.Identity.Web

Ubah kode di Startup.cs untuk menginisialisasi layanan autentikasi yang disediakan dengan benar oleh Microsoft.Identity.Web.

Tambahkan cuplikan kode berikut ke file Startup.cs aplikasi Anda.

Catatan

Kode dalam ConfigureServices menyelesaikan beberapa hal penting:

  1. Panggilan untuk AddMicrosoftWebAppCallsWebApi mengonfigurasi Microsoft Authentication Library untuk memperoleh token akses (token Microsoft Entra).
  2. Panggilan untuk AddInMemoryTokenCaches mengonfigurasi cache token yang akan digunakan Microsoft Authentication Library untuk menyimpan token akses dan menyegarkan token di belakang layar
  3. Panggilan untuk services.AddScoped(typeof(PowerBiServiceApi)) mengonfigurasi kelas PowerBiServiceApi sebagai kelas layanan yang dapat ditambahkan ke kelas lain menggunakan injeksi dependensi.
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Identity.Web.UI;
using UserOwnsData.Services;

namespace UserOwnsData {

  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(PowerBiServiceApi.RequiredScopes)
        .AddInMemoryTokenCaches();

      services.AddScoped (typeof (PowerBiServiceApi));

      var mvcBuilder = services.AddControllersWithViews (options => {
        var policy = new AuthorizationPolicyBuilder()
          .RequireAuthenticatedUser()
          .Build();
        options.Filters.Add (new AuthorizeFilter (policy));
      });

      mvcBuilder.AddMicrosoftIdentityUI();

      services.AddRazorPages();

    }
  }
}

Membuat file detail autentikasi

Dalam tutorial ini, file appsettings.json berisi informasi sensitif seperti ID klien dan rahasia klien. Untuk alasan keamanan, kami tidak menyarankan untuk menyimpan informasi ini dalam file pengaturan. Saat menyematkan dalam aplikasi Anda, pertimbangkan metode yang lebih aman seperti Azure Key Vault untuk menyimpan informasi ini.

  1. Di proyek Anda, buat file baru dan sebut saja appsettings.json.

  2. Tambahkan kode berikut ke appsettings.json:

    {
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "Domain": "",
        "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. Isi nilai parameter penyematan yang diperoleh dari Langkah 2 - Dapatkan nilai parameter penyematan.

Catatan

Dalam cuplikan kode sebelumnya, PowerBi:ServiceRootUrl parameter ditambahkan sebagai nilai konfigurasi kustom untuk melacak URL dasar ke layanan Power BI. Saat memprogram terhadap layanan Power BI di awan publik Microsoft, URL-nya adalah https://api.powerbi.com/. Namun, URL akar untuk layanan Power BI akan berbeda di cloud lain seperti cloud pemerintah. Oleh karena itu, nilai ini disimpan sebagai nilai konfigurasi proyek sehingga mudah diubah saat diperlukan.

Dapatkan token akses Microsoft Entra dan panggil layanan Power BI

Untuk menyematkan konten Power BI (seperti laporan dan dasbor), aplikasi Anda perlu mendapatkan token Microsoft Entra. Untuk mendapatkan token, Anda memerlukan objek konfigurasi.

Kode di bagian ini menggunakan pola injeksi dependensi .NET Core. Ketika kelas Anda perlu menggunakan layanan, Anda dapat menambahkan parameter konstruktor untuk layanan tersebut dan runtime .NET Core mengurus melewati instans layanan pada waktu proses. Dalam hal ini, konstruktor menyuntikkan instans layanan konfigurasi .NET Core menggunakan IConfiguration parameter, yang digunakan untuk mengambil PowerBi:ServiceRootUrl nilai konfigurasi dari appsettings.json. Parameter ITokenAcquisition , yang diberi nama tokenAcquisition menyimpan referensi ke layanan autentikasi Microsoft yang disediakan oleh Microsoft.Identity.Web pustaka dan digunakan untuk memperoleh token akses dari ID Microsoft Entra.

Bidang RequiredScopes ini menyimpan array string yang berisi sekumpulan izin yang didelegasikan yang didukung oleh API layanan Power BI. Saat aplikasi Anda memanggil di seluruh jaringan untuk memperoleh token Microsoft Entra, meneruskan serangkaian izin yang didelegasikan ini sehingga ID Microsoft Entra dapat menyertakannya dalam token akses yang dikembalikannya.

Catatan

Verifikasi bahwa aplikasi Microsoft Entra Anda dikonfigurasi dengan cakupan yang diperlukan oleh aplikasi web Anda. Untuk informasi selengkapnya, lihat Mengubah izin aplikasi Microsoft Entra Anda.

  1. Di proyek aplikasi Anda, buat folder baru berjudul Layanan.

  2. Di folder Layanan, buat file baru berjudul PowerBiServiceApi.cs.

  3. Tambahkan kode berikut ke PowerBiServiceApi.cs.

    using Microsoft.Identity.Web;
using Microsoft.PowerBI.Api;
using Microsoft.PowerBI.Api.Models;
using Microsoft.Rest;
using Newtonsoft.Json;

namespace UserOwnsData.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 static readonly string[] RequiredScopes = new string[] {
         "https://analysis.windows.net/powerbi/api/Report.Read.All"
     };

    // A method to get the Azure AD token (also known as 'access token')
     public string GetAccessToken() {
         return this.tokenAcquisition.GetAccessTokenForUserAsync(RequiredScopes).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 embedding data
   var report = await pbiClient.Reports.GetReportInGroupAsync(WorkspaceId, ReportId);

   // Return report embedding data to caller
   return new EmbeddedReportViewModel {
    Id = report.Id.ToString(),
    EmbedUrl = report.EmbedUrl,
    Name = report.Name,
    Token = GetAccessToken()
   };
  }

 }

}

Mengubah file HomeController.cs

Dalam contoh kode ini, Anda menggunakan injeksi ketergantungan. Saat Anda mendaftarkan kelas PowerBiServiceApi sebagai layanan dengan memanggil services.AddScoped dalam metode ConfigureServices. Anda dapat menambahkan PowerBiServiceApi parameter ke konstruktor, dan runtime .NET Core mengurus pembuatan PowerBiServiceApi instans dan meneruskannya ke konstruktor.

Dari folder Controllers, buka file HomeController.cs dan tambahkan ke cuplikan kode berikut:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using UserOwnsData.Models;
using UserOwnsData.Services;

namespace UserOwnsData.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() {
            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 });
        }
    }
}

Langkah 5 - Membangun sisi klien aplikasi Anda

Untuk implementasi sisi klien, Anda perlu membuat atau mengubah file dalam tabel berikut.

File Menggunakan
embed.js Berisi kode JavaScript sisi klien
Embed.cshtml Berisi model objek dokumen (DOM) aplikasi Anda, dan DIV untuk menyematkan laporan

Membuat kontainer untuk laporan tersemat Anda

Buat file Embed.cshtml, yang memiliki div elemen yang digunakan sebagai kontainer untuk laporan tertanam Anda, dan tiga skrip.

  1. Di folder Tampilkan>Beranda, buat file bernama Embed.cshtml.

  2. Tambahkan cuplikan kode berikut ke file Embed.cshtml.

    @model UserOwnsData.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.21.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>
}

Menambahkan JavaScript sisi klien untuk menyematkan laporan Anda

Untuk menyematkan konten Power BI, Anda perlu membuat objek konfigurasi. Untuk mempelajari selengkapnya tentang membuat objek konfigurasi, lihat Menyematkan laporan.

Di bagian ini, Anda membuat file JavaScript bernama embed.js dengan objek konfigurasi untuk menyematkan laporan Anda, menggunakan variabel models.

models diinisialisasi menggunakan panggilan ke window['powerbi-client'].models. Variabel models digunakan untuk mengatur nilai konfigurasi seperti models.Permissions.All, , models.TokenType.Aaddan models.ViewMode.View.

Fungsi powerbi.embed ini menggunakan objek konfigurasi models untuk menyematkan laporan Anda.

  1. Di folder wwwroot>js, buat file bernama.embed.js.

  2. Tambahkan cuplikan kode berikut ke file embed.js.

    $(function(){
    // 1 - Get DOM object for div that is report container
    let reportContainer = document.getElementById("embed-container");

    // 2 - Get report embedding data from view model
    let reportId = window.viewModel.reportId;
    let embedUrl = window.viewModel.embedUrl;
    let token = window.viewModel.token

    // 3 - Embed report using the Power BI JavaScript API.
    let models = window['powerbi-client'].models;
    let config = {
        type: 'report',
        id: reportId,
        embedUrl: embedUrl,
        accessToken: token,
        permissions: models.Permissions.All,
        tokenType: models.TokenType.Aad,
        viewMode: models.ViewMode.View,
        settings: {
            panes: {
                filters: { expanded: false, visible: true },
                pageNavigation: { visible: false }
            }
        }
    };

    // Embed the report and display it within the div container.
    let report = powerbi.embed(reportContainer, config);

    // 4 - Add logic to resize embed container on window resize event
    let heightBuffer = 12;
    let newHeight = $(window).height() - ($("header").height() + heightBuffer);
    $("#embed-container").height(newHeight);
    $(window).resize(function() {
        var newHeight = $(window).height() - ($("header").height() + heightBuffer);
        $("#embed-container").height(newHeight);
    });

});

Langkah 6 - Jalankan aplikasi Anda

Setelah membuat semua penyesuaian yang tercantum dalam tutorial ini, Anda siap untuk menjalankan aplikasi Anda. Jalankan aplikasi Anda dan bereksperimenlah dengan cara laporan Power BI disematkan. Anda dapat menggunakan API Klien analitik tertanam Power BI untuk meningkatkan aplikasi Anda menggunakan API sisi klien.

Setelah aplikasi siap, Anda dapat memindahkan aplikasi yang disematkan ke produksi.

Konten terkait