Membuat token sematan
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: |
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: |
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:
- Di portal Power BI, atur titik akhir XMLA ke Baca Saja atau Baca Tulis seperti yang dijelaskan dalam mengaktifkan baca-tulis untuk kapasitas Premium. Anda hanya perlu melakukan ini sekali per kapasitas.
- Membuat token semat multi-sumber daya
- Tentukan semua ID himpunan data dalam permintaan.
- Atur
XmlaPermissions
ke Baca Saja untuk setiap model semantik dalam permintaan. - Untuk setiap sumber data yang diaktifkan Akses Menyeluruh (SSO), berikan blob identitas untuk sumber data di
DatasourceIdentity
.
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.