Share via

Membuat token sematan

  • Artikel

BERLAKU UNTUK: Aplikasi memiliki data Milik pengguna

Menghasilkan token adalah REST API yang memungkinkan Anda membuat token untuk menyematkan laporan Power BI atau model semantik di aplikasi web atau portal. Ini dapat menghasilkan token untuk satu item atau untuk beberapa laporan atau model semantik. Token digunakan untuk mengotorisasi permintaan Anda terhadap layanan Power BI.

API buat token menggunakan identitas tunggal (pengguna master atau perwakilan layanan) untuk menghasilkan token bagi pengguna individu, tergantung pada kredensial pengguna tersebut di aplikasi (identitas yang efektif).

Setelah autentikasi berhasil, akses ke data yang relevan akan diberikan.

Catatan

Menghasilkan token adalah API versi 2 yang lebih baru yang berfungsi untuk laporan dan model semantik, dan satu atau beberapa item. Ini lebih disukai daripada API versi 1 warisan. Untuk dasbor dan petak peta, gunakan Dasbor V1 GenerateTokenInGroup dan Petak Peta GenerateTokenInGroup.

Mengamankan data Anda

Jika Anda menangani data dari beberapa pelanggan, ada dua pendekatan utama untuk mengamankan data Anda: Isolasi berbasis ruang kerja dan isolasi berbasis keamanan tingkat baris. Anda dapat menemukan perbandingan terperinci di antara mereka dalam profil perwakilan layanan dan keamanan tingkat baris.

Sebaiknya gunakan isolasi berbasis ruang kerja dengan profil, tetapi jika Anda ingin menggunakan pendekatan RLS, tinjau bagian RLS di akhir artikel ini.

Izin dan keamanan token

Di API buat token, bagian GenerateTokenRequest menjelaskan izin token.

Tingkat Akses

  • Gunakan parameter allowEdit untuk memberi pengguna izin menampilkan atau mengedit.

  • Tambahkan ID ruang kerja ke token semat untuk memungkinkan pengguna membuat laporan baru (SaveAs atau CreateNew) di ruang kerja tersebut.

Keamanan Tingkat Baris

Dengan Keamanan Tingkat Baris (RLS), identitas yang Anda gunakan dapat berbeda dari identitas perwakilan layanan atau pengguna master yang digunakan untuk menghasilkan token. Dengan menggunakan identitas yang berbeda, Anda dapat menampilkan informasi yang disematkan sesuai dengan pengguna yang Anda targetkan. Misalnya, di aplikasi Anda, Anda dapat meminta pengguna untuk masuk, lalu menampilkan laporan yang hanya berisi informasi penjualan jika pengguna yang masuk adalah karyawan penjualan.

Jika menggunakan RLS, terkadang Anda dapat menghilangkan identitas pengguna (parameter EffectiveIdentity). Saat Anda tidak menggunakan parameter EffectiveIdentity , token memiliki akses ke seluruh database. Metode ini dapat digunakan untuk memberikan akses kepada pengguna seperti admin dan manajer, yang memiliki izin untuk melihat seluruh model semantik. Namun, Anda tidak dapat menggunakan metode ini dalam setiap skenario. Tabel di bawah ini mencantumkan berbagai jenis RLS, dan menunjukkan metode autentikasi yang dapat digunakan tanpa menentukan identitas pengguna.

Tabel ini juga menunjukkan pertimbangan dan batasan yang berlaku untuk setiap jenis RLS.

Jenis RLS Apakah saya dapat membuat token semat tanpa menentukan ID pengguna yang efektif? Pertimbangan dan batasan
Keamanan Tingkat Baris Cloud (Cloud RLS) ✔ Pengguna master
✖ Perwakilan layanan
RDL (laporan berpaginasi) ✖ Pengguna master
✔ Perwakilan layanan		 Anda tidak dapat menggunakan pengguna master untuk menghasilkan token semat untuk RDL.
Azure Analysis Services (AS) pada koneksi langsung lokal ✔ Pengguna master
✖ Perwakilan layanan		 Pengguna yang menghasilkan token semat juga memerlukan salah satu izin berikut:
  • Izin admin gateway
  • Sumber data meniru izin (ReadOverrideEffectiveIdentity)
    		•
    Koneksi langsung Layanan Analisis (AS) Azure ✔ Pengguna master
    ✖ Perwakilan layanan    		 Identitas pengguna yang menghasilkan token semat tidak dapat diganti. Data kustom dapat digunakan untuk menerapkan RLS dinamis atau pemfilteran aman.

    Catatan: Perwakilan layanan harus memberikan ID objeknya sebagai identitas efektif (nama pengguna RLS).
    Akses Menyeluruh (SSO) ✔ Pengguna master
    ✖ Perwakilan layanan    		 Identitas eksplisit (SSO) dapat disediakan menggunakan properti blob identitas dalam objek identitas yang efektif
    SSO dan cloud RLS ✔ Pengguna master
    ✖ Perwakilan layanan    		 Anda harus memberikan berikut ini:
  • Identitas eksplisit (SSO) dalam properti blob identitas pada objek identitas yang efektif
  • Identitas efektif (RLS) (nama pengguna)
    		•

    Catatan

    Perwakilan layanan harus selalu memberikan informasi berikut:

    • Identitas untuk item apa pun dengan model semantik RLS.
    • Untuk model semantik SSO, identitas RLS yang efektif dengan identitas kontekstual (SSO) yang ditentukan.

    DirectQuery untuk model semantik Power BI

    Untuk menyematkan laporan Power BI yang memiliki model semantik dengan koneksi Direct Query ke model semantik Power BI lain, lakukan hal berikut:

    Memperbarui token sebelum kedaluwarsa

    Token dilengkapi dengan batas waktu. Ini berarti bahwa setelah menyematkan item Power BI, Anda memiliki waktu terbatas untuk berinteraksi dengannya. Untuk memberi pengguna Anda pengalaman berkelanjutan, perbarui (atau refresh) token sebelum kedaluwarsa.

    Dasbor dan petak peta

    Buat token berfungsi untuk laporan dan model semantik. Untuk menghasilkan token semat untuk dasbor atau petak peta, gunakan API GenerateTokenInGroup atau Ubin GenerateTokenInGroup versi 1. API ini menghasilkan token hanya untuk satu item pada satu waktu. Anda tidak dapat membuat token untuk beberapa item.

    Untuk API ini:

    • Gunakan parameter accessLevel untuk menentukan tingkat akses pengguna.

      • Lihat - Memberi pengguna izin melihat.

      • Edit - Memberi pengguna izin melihat dan mengedit (hanya berlaku saat membuat token semat untuk laporan).

      • Buat - Berikan izin pengguna untuk membuat laporan baru (hanya berlaku saat membuat token semat untuk membuat laporan). Untuk pembuatan laporan, Anda juga harus menentukan parameter datasetId.

    • Gunakan boolean allowSaveAs untuk memungkinkan pengguna menyimpan laporan sebagai laporan baru. Pengaturan ini diatur ke false secara default, dan hanya berlaku saat membuat token semat untuk laporan.

    Pertimbangan dan batasan

    • Untuk alasan keamanan, masa pakai token semat diatur ke sisa masa pakai token Microsoft Entra yang digunakan untuk memanggil GenerateToken API. Oleh karena itu, jika Anda menggunakan token Microsoft Entra yang sama untuk menghasilkan beberapa token semat, masa pakai token semat yang dihasilkan akan lebih pendek dengan setiap panggilan.

    • Jika model semantik dan item yang akan disematkan berada di dua ruang kerja yang berbeda, perwakilan layanan atau pengguna master harus setidaknya menjadi anggota dari kedua ruang kerja.

    • Anda tidak dapat membuat token semat untuk Ruang kerja saya.

    Konten terkait