Konfigurasi otomatis penginstalan aplikasi templat

  • Artikel

Aplikasi templat adalah cara yang bagus bagi pelanggan untuk mulai mendapatkan wawasan dari data mereka. Aplikasi templat akan menyiapkan wawasan dan menjalankannya dengan cepat dengan menyambungkan wawasan ke data pelanggan. Aplikasi templat memberi pelanggan laporan bawaan yang dapat disesuaikan jika diinginkan.

Pelanggan tidak selalu terbiasa dengan detail cara menyambungkan ke data mereka. Memberikan detail ini ketika mereka menginstal aplikasi templat bisa menjadi kesulitan tersendiri bagi mereka.

Jika Anda adalah penyedia layanan data dan telah membuat aplikasi templat untuk membantu pelanggan Anda memulai data mereka di layanan Anda, Anda dapat mempermudah mereka menginstal aplikasi templat Anda. Anda dapat mengotomatiskan konfigurasi parameter dari aplikasi templat Anda. Saat pelanggan masuk ke portal Anda, mereka akan memilih tautan khusus yang telah Anda siapkan. Tautan ini:

  • Meluncurkan otomatisasi, yang mengumpulkan informasi yang dibutuhkan.
  • Mengonfigurasi parameter aplikasi templat.
  • Mengalihkan pelanggan ke akun Power BI di mana mereka dapat menginstal aplikasinya.

Yang harus mereka lakukan adalah memilih Instal dan mengautentikasi sumber data mereka, dan selesai!

Pengalaman pelanggan diilustrasikan di sini.

Illustration of user experience with an auto-installation application.

Artikel ini menjelaskan alur dasar, prasyarat, dan langkah-langkah utama serta API yang Anda butuhkan untuk mengotomatiskan konfigurasi penginstalan aplikasi templat. Jika Anda ingin mendalami dan memulai, Anda dapat melompat ke tutorial, di mana Anda akan mengotomatiskan konfigurasi penginstalan aplikasi templat dengan menggunakan aplikasi sampel sederhana yang telah kami siapkan dengan menggunakan fungsi Azure.

Alur dasar

Alur dasar mengotomatiskan konfigurasi penginstalan aplikasi templat adalah sebagai berikut:

  1. Pengguna masuk ke portal ISV dan memilih tautan yang disediakan. Tindakan ini akan memulai aliran otomatis. Portal ISV menyiapkan konfigurasi khusus pengguna pada tahap ini.

  2. ISV memperoleh token khusus aplikasi berdasarkan perwakilan layanan (token khusus aplikasi) yang terdaftar di penyewa ISV.

  3. Dengan menggunakan REST API Power BI, ISV membuat tiket penginstalan, yang berisi konfigurasi parameter khusus pengguna seperti yang disiapkan oleh ISV.

  4. ISV akan mengalihkan pengguna ke Power BI dengan menggunakan metode pengalihan POST, yang berisi tiket penginstalan.

  5. Pengguna dialihkan ke akun Power BI mereka dengan tiket penginstalan dan diminta untuk menginstal aplikasi templat. Saat pengguna memilih Instal, aplikasi templat akan diinstal untuk mereka.

Catatan

Sementara nilai parameter dikonfigurasi oleh ISV dalam proses pembuatan tiket penginstalan,kredensial terkait sumber data hanya disediakan oleh pengguna pada tahap akhir penginstalan. Pengaturan ini mencegah pengguna diekspos ke pihak ketiga dan memastikan koneksi yang aman antara pengguna dan sumber data aplikasi templat.

Prasyarat

Untuk memberikan pengalaman penginstalan yang telah dikonfigurasi sebelumnya untuk aplikasi templat Anda, prasyarat berikut diperlukan:

  • Lisensi Power BI Pro. Jika Anda belum mendaftar ke Power BI Pro, daftar untuk uji coba gratis sebelum Anda memulai.

  • Penyewa Microsoft Entra Anda sendiri disiapkan. Untuk instruksi tentang cara menyiapkannya, lihat Membuat penyewa Microsoft Entra.

  • Perwakilan layanan (token khusus aplikasi) yang terdaftar di penyewa sebelumnya. Untuk informasi selengkapnya, lihat Menyematkan konten Power BI dengan perwakilan layanan dan rahasia aplikasi. Pastikan untuk mendaftarkan aplikasi sebagai aplikasi web sisi server. Anda mendaftarkan aplikasi web sisi server untuk membuat rahasia aplikasi. Dari proses ini, Anda perlu menyimpan ID aplikasi (ClientID) dan rahasia aplikasi (ClientSecret) untuk langkah-langkah selanjutnya.

  • Aplikasi templat berparameter yang siap untuk penginstalan. Aplikasi templat harus dibuat di penyewa yang sama tempat Anda mendaftarkan aplikasi Anda di ID Microsoft Entra. Untuk informasi selengkapnya, lihat Tips aplikasi templat atau Membuat aplikasi templat di Power BI. Dari aplikasi templat, Anda perlu mencatat informasi berikut untuk langkah-langkah berikutnya:

    • ID Aplikasi, Kunci Paket, dan ID Pemilik seperti yang muncul di URL penginstalan pada akhir proses menentukan properti aplikasi templat saat aplikasi dibuat. Anda juga bisa mendapatkan tautan yang sama dengan memilih Dapatkan tautan di panel Manajemen Rilis pada aplikasi templat.
    • Nama parameter seperti yang didefinisikan dalam model semantik aplikasi templat. Nama parameter adalah string peka huruf besar/kecil dan juga dapat diambil dari tab Parameter Pengaturan saat Anda menentukan properti aplikasi templat atau dari pengaturan model semantik di Power BI.

  • Agar dapat menguji alur kerja otomatisasi Anda, tambahkan perwakilan layanan ke ruang kerja aplikasi templat sebagai Admin.

    Catatan

    Anda dapat menguji aplikasi penginstalan yang telah dikonfigurasi sebelumnya di aplikasi templat jika aplikasi templat siap untuk diinstal, meskipun belum tersedia untuk umum di AppSource. Agar pengguna di luar penyewa Anda dapat menggunakan aplikasi penginstalan otomatis untuk menginstal aplikasi templat Anda, aplikasi templat harus tersedia untuk umum di marketplace aplikasi Power BI. Sebelum Anda mendistribusikan aplikasi templat dengan menggunakan aplikasi penginstalan otomatis yang Anda buat, pastikan untuk menerbitkannya ke Pusat Mitra.

Langkah-langkah utama dan API

Langkah-langkah utama untuk mengotomatiskan konfigurasi penginstalan aplikasi templat dan API yang akan Anda butuhkan, dijelaskan di bagian berikut. Meskipun sebagian besar langkah dilakukan dengan REST API Power BI, contoh kode yang dijelaskan di sini dibuat dengan SDK .NET.

Langkah 1: Buat objek klien Power BI

Menggunakan REST API Power BI mengharuskan Anda mendapatkan token akses untuk perwakilan layanan Anda dari ID Microsoft Entra. Anda diharuskan mendapatkan token akses Microsoft Entra untuk aplikasi Power BI Anda sebelum melakukan panggilan ke REST API Power BI. Untuk membuat klien Power BI dengan token akses, Anda perlu membuat objek klien Power BI, yang memungkinkan Anda berinteraksi dengan REST API Power BI. Anda buat objek klien Power BI dengan membungkus AccessToken dengan objek Microsoft.Rest.TokenCredentials.

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;
using Microsoft.PowerBI.Api.V2;

var tokenCredentials = new TokenCredentials(authenticationResult.AccessToken, "Bearer");

// Create a Power BI client object. It's used to call Power BI APIs.
using (var client = new PowerBIClient(new Uri(ApiUrl), tokenCredentials))
{
    // Your code goes here.
}

Langkah 2: Buat tiket penginstalan

Buat tiket penginstalan, yang akan digunakan saat Anda mengalihkan pengguna ke Power BI. API yang digunakan untuk operasi ini adalah API CreateInstallTicket.

Contoh cara membuat tiket instalasi untuk penginstalan dan konfigurasi aplikasi templat tersedia dari file InstallTemplateApp/InstallAppFunction.cs dalam aplikasi sampel.

Contoh kode berikut menunjukkan cara menggunakan REST API CreateInstallTicket dari aplikasi templat.

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// Create Install Ticket Request.
InstallTicket ticketResponse = null;
var request = new CreateInstallTicketRequest()
{
    InstallDetails = new List<TemplateAppInstallDetails>()
    {
        new TemplateAppInstallDetails()
        {
            AppId = Guid.Parse(AppId),
            PackageKey = PackageKey,
            OwnerTenantId = Guid.Parse(OwnerId),
            Config = new TemplateAppConfigurationRequest()
            {
                Configuration = Parameters
                                    .GroupBy(p => p.Name)
                                    .ToDictionary(k => k.Key, k => k.Select(p => p.Value).Single())
            }
        }
    }
};

// Issue the request to the REST API using .NET SDK.
InstallTicket ticketResponse = await client.TemplateApps.CreateInstallTicketAsync(request);

Langkah 3: Alihkan pengguna ke Power BI dengan tiket

Setelah membuat tiket penginstalan, Anda gunakan tiket tersebut untuk mengalihkan pengguna ke Power BI guna melanjutkan penginstalan dan konfigurasi aplikasi templat. Anda gunakan pengalihan metode POST ke URL penginstalan aplikasi templat, dengan tiket penginstalan di badan permintaannya.

Terdapat berbagai metode yang didokumentasi mengenai cara mengeluarkan pengalihan dengan menggunakan permintaan POST. Pilih satu atau yang lainnya tergantung pada skenario dan bagaimana pengguna Anda berinteraksi dengan portal atau layanan Anda.

Contoh sederhana, sebagian besar digunakan untuk tujuan pengujian, yaitu menggunakan formulir dengan bidang tersembunyi, yang secara otomatis mengirim sendiri saat memuat.

<html>
    <body onload='document.forms["form"].submit()'>
        <!-- form method is POST and action is the app install URL -->
        <form name='form' action='https://app.powerbi.com/....' method='post' enctype='application/json'>
            <!-- value should be the new install ticket -->
            <input type='hidden' name='ticket' value='H4sI....AAA='>
        </form>
    </body>
</html>

Contoh respons aplikasi sampel berikut menyimpan tiket penginstalan dan secara otomatis mengalihkan pengguna ke Power BI. Respons untuk fungsi Azure ini adalah formulir pengiriman otomatis yang sama seperti kita lihat dalam contoh HTML sebelumnya.

...
    return new ContentResult() { Content = RedirectWithData(redirectUrl, ticket.Ticket), ContentType = "text/html" };
}

...

public static string RedirectWithData(string url, string ticket)
{
    StringBuilder s = new StringBuilder();
    s.Append("<html>");
    s.AppendFormat("<body onload='document.forms[\"form\"].submit()'>");
    s.AppendFormat("<form name='form' action='{0}' method='post' enctype='application/json'>", url);
    s.AppendFormat("<input type='hidden' name='ticket' value='{0}' />", ticket);
    s.Append("</form></body></html>");
    return s.ToString();
}

Catatan

Terdapat berbagai metode penggunaan pengalihan browser POST. Anda harus selalu menggunakan metode yang paling aman, yang mana tergantung pada kebutuhan dan batasan layanan Anda. Ingat bahwa beberapa bentuk pengalihan tidak aman dapat mengakibatkan pengguna atau layanan Anda terpapar masalah keamanan.

Langkah 4: Pindahkan otomatisasi Anda ke produksi

Ketika otomatisasi yang Anda rancang sudah siap, pastikan untuk memindahkannya ke produksi.

Konten terkait