Refresh yang disempurnakan dengan Power BI REST API
Anda dapat menggunakan bahasa pemrograman apa pun yang mendukung panggilan REST untuk melakukan operasi refresh model semantik dengan menggunakan Rest API Himpunan Data Refresh Power BI.
Refresh yang dioptimalkan untuk model partisi besar dan kompleks secara tradisional dipanggil dengan metode pemrograman yang menggunakan TOM (Model Objek Tabular), cmdlet PowerShell, atau TMSL (Bahasa Pembuatan Skrip Model Tabular). Namun, metode ini memerlukan koneksi HTTP yang berjalan lama yang tidak dapat diandalkan.
REST API Penyegaran Dataset Power BI dapat melakukan operasi penyegaran model secara asinkron, sehingga koneksi HTTP berdurasi lama dari aplikasi klien tidak perlu. Dibandingkan dengan operasi refresh standar, refresh yang disempurnakan dengan REST API menyediakan lebih banyak opsi penyesuaian dan fitur berikut yang berguna untuk model besar:
- Penerapan batch
- Refresh tingkat tabel dan partisi
- Menerapkan kebijakan refresh bertahap
-
GET
detail refresh - Perbarui status pembatalan
- Konfigurasi batas waktu
Nota
- Sebelumnya, refresh yang ditingkatkan disebut refresh asinkron dengan REST API. Namun, refresh standar yang menggunakan Refresh Dataset REST API juga berjalan secara asinkron berdasarkan sifatnya yang melekat.
- Operasi refresh Power BI REST API yang disempurnakan tidak secara otomatis mengupdate cache tile. Cache ubin peta hanya diperbarui saat pengguna mengakses laporan.
URL Dasar
URL dasar dalam format berikut:
https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes
Anda dapat menambahkan sumber daya dan operasi ke URL dasar berdasarkan parameter. Dalam diagram berikut, Grup, Himpunan Data, dan Refresh merupakan koleksi. Grup, Himpunan Data, dan Refresh adalah objek .
Persyaratan
Anda memerlukan persyaratan berikut untuk menggunakan REST API:
- Model semantik dalam Power BI Premium, Premium per pengguna, atau Power BI Embedded.
- ID grup dan ID himpunan data untuk digunakan dalam URL permintaan.
- Dataset.ReadWrite.All ruang lingkup izin.
Jumlah refresh dibatasi per batasan umum untuk refresh berbasis API untuk model Pro dan Premium.
Otentikasi
Semua panggilan harus mengautentikasi dengan token Microsoft Entra ID OAuth 2 yang valid di header Otorisasi. Token harus memenuhi persyaratan berikut:
- Pilih menjadi token pengguna atau principal layanan aplikasi.
- Atur audiens dengan benar ke
https://api.powerbi.com
. - Digunakan oleh pengguna atau aplikasi yang memiliki izin yang memadai pada model.
Nota
Modifikasi REST API tidak mengubah izin yang saat ini ditentukan untuk refresh model.
POST /refreshes
Untuk melakukan refresh, gunakan kata kerja POST pada koleksi /refreshes untuk menambahkan objek refresh baru ke koleksi. Header Lokasi dalam respons menyertakan requestId
. Karena operasi ini asinkron, aplikasi klien dapat memutuskan sambungan dan menggunakan requestId
untuk memeriksa status nanti jika perlu.
Kode berikut menunjukkan contoh permintaan:
POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes
Isi permintaan mungkin menyerupai contoh berikut:
{
"type": "Full",
"commitMode": "transactional",
"maxParallelism": 2,
"retryCount": 2,
"timeout": "02:00:00",
"objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer"
},
{
"table": "DimDate"
}
]
}
Nota
Layanan hanya menerima satu operasi refresh sekaligus untuk model. Jika ada refresh yang sedang berjalan dan permintaan lain dikirimkan, kode status HTTP 400 Bad Request
akan ditampilkan.
Parameter
Untuk melakukan operasi refresh yang ditingkatkan, Anda harus menentukan satu atau beberapa parameter dalam isi permintaan. Parameter yang ditentukan dapat menentukan nilai default atau opsional. Saat permintaan menentukan parameter, semua parameter lain berlaku untuk operasi dengan nilai defaultnya. Jika permintaan tidak menentukan parameter, semua parameter menggunakan nilai defaultnya, dan operasi refresh standar terjadi.
Nama | Jenis | Standar | Deskripsi |
---|---|---|---|
type |
Enum | automatic |
Jenis pemrosesan yang akan dilakukan. Jenis sejalan dengan jenis perintah refresh TMSL: full , clearValues , calculate , dataOnly , automatic , dan defragment . Jenis add tidak didukung. |
commitMode |
Enum | transactional |
Menentukan apakah akan menghasilkan objek dalam batch atau hanya ketika selesai. Mode adalah transactional dan partialBatch . Saat menggunakan partialBatch operasi refresh tidak terjadi dalam satu transaksi. Setiap perintah diterapkan satu per satu. Jika ada kegagalan, model mungkin kosong atau hanya menyertakan subset data. Untuk melindungi dari kegagalan dan menyimpan data yang ada dalam model sebelum operasi dimulai, jalankan operasi dengan commitMode = transactional . |
maxParallelism |
Int | 10 |
Menentukan jumlah maksimum utas yang dapat menjalankan perintah pemrosesan secara paralel. Nilai ini selaras dengan properti MaxParallelism yang dapat diatur dalam perintah Sequence TMSL atau dengan menggunakan metode lain. |
retryCount |
Int | 0 |
Berapa kali operasi mencoba kembali sebelum gagal. |
objects |
Array | Seluruh model | Sekumpulan objek untuk diproses. Setiap objek mencakup table saat memproses seluruh tabel, atau table dan partition saat memproses partisi. Jika tidak ada objek yang ditentukan, seluruh model akan di-refresh. |
applyRefreshPolicy |
Boolean | true |
Jika kebijakan refresh bertahap ditentukan, menentukan apakah akan menerapkan kebijakan. Mode true atau false . Jika kebijakan tidak diterapkan, proses penuh tidak mengubah definisi partisi, dan sepenuhnya menyegarkan kembali semua partisi dalam tabel. Jika commitMode transactional , applyRefreshPolicy bisa true atau false . Jika commitMode partialBatch , applyRefreshPolicy true tidak didukung, dan applyRefreshPolicy harus diatur ke false . |
effectiveDate |
Tanggal | Tanggal saat ini | Jika kebijakan refresh bertahap diterapkan, parameter effectiveDate akan mengambil alih tanggal saat ini. Jika tidak ditentukan, hari ini ditentukan menggunakan konfigurasi zona waktu di bawah 'Refresh'. |
timeout |
String | 05:00:00 (5 jam) | Jika timeout ditentukan, setiap upaya penyegaran data pada model semantik mematuhi batas waktu tersebut. Satu permintaan refresh dapat mencakup beberapa upaya jika retryCount ditentukan, yang dapat menyebabkan total durasi refresh melebihi batas waktu yang ditentukan. Misalnya, menetapkan timeout selama 1 jam dan retryCount sebesar 2 dapat menghasilkan total durasi penyegaran hingga 3 jam. Pengguna dapat menyesuaikan timeout untuk mempersingkat durasi refresh untuk deteksi kegagalan yang lebih cepat atau memperluasnya di luar default 5 jam untuk refresh data yang lebih kompleks. Namun, total durasi refresh, termasuk percobaan ulang, tidak boleh melebihi 24 jam. |
Jawaban
202 Accepted
Respons juga menyertakan bidang header tanggapan Location
untuk mengarah pemanggil ke operasi pembaruan yang telah dibuat dan diterima.
Location
adalah lokasi dari sumber daya baru yang dibuat oleh permintaan tersebut, yang mencakup requestId
yang dibutuhkan oleh beberapa operasi penyegaran yang ditingkatkan. Misalnya, dalam respons berikut, requestId
adalah pengidentifikasi terakhir dalam respons 87f31ef7-1e3a-4006-9b0b-191693e79e9e
.
x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e
GET /refreshes
Gunakan kata kerja GET pada koleksi /refreshes untuk mencantumkan operasi refresh historis, saat ini, dan tertunda.
Isi respons mungkin terlihat seperti contoh berikut:
[
{
"requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
"refreshType": "ViaEnhancedApi",
"startTime": "2020-12-07T02:06:57.1838734Z",
"endTime": "2020-12-07T02:07:00.4929675Z",
"status": "Completed",
"extendedStatus": "Completed"
},
{
"requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
"startTime": "2020-12-07T01:05:54.157324Z",
"refreshType": "ViaEnhancedApi",
"status": "Unknown"
}
{
"requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
"refreshType": "ViaEnhancedApi",
"startTime": "2020-12-07T01:05:54.157324Z",
"status": "Unknown",
"extendedStatus": "NotStarted"
}
]
Nota
Power BI mungkin menghilangkan permintaan jika ada terlalu banyak permintaan dalam waktu singkat. Power BI melakukan refresh, mengantrekan permintaan berikutnya, dan menghilangkan semua permintaan lainnya. Secara desain, Anda tidak dapat memeriksa status pada permintaan yang dibatalkan.
Properti respons
Nama | Jenis | Deskripsi |
---|---|---|
requestId |
Guid | Pengidentifikasi permintaan refresh. Anda perlu requestId untuk memeriksa status operasi refresh individual atau membatalkan operasi refresh yang sedang berlangsung. |
refreshType |
String |
OnDemand menunjukkan bahwa refresh dipicu secara interaktif melalui portal Power BI.Scheduled menunjukkan bahwa jadwal penyegaran model memicu penyegaran. ViaApi menunjukkan bahwa panggilan API memicu refresh. ViaEnhancedApi menunjukkan bahwa panggilan API memicu refresh yang ditingkatkan. |
startTime |
Tali | Tanggal dan waktu mulai refresh. |
endTime |
Tali | Tanggal dan waktu refresh berakhir. |
status |
Tali |
Completed menunjukkan operasi refresh berhasil diselesaikan. Failed menunjukkan operasi refresh gagal. Unknown menunjukkan bahwa status penyelesaian tidak dapat ditentukan. Dengan status ini, endTime kosong. Disabled menunjukkan bahwa refresh dinonaktifkan oleh refresh selektif. Cancelled menunjukkan bahwa refresh berhasil dibatalkan. |
extendedStatus |
Tali | Menambah properti status untuk memberikan informasi lebih lanjut. |
Nota
Dalam Azure Analysis Services, hasil status
yang telah selesai adalah succeeded
. Jika Anda memigrasikan solusi Azure Analysis Services ke Power BI, Anda mungkin harus mengubah solusi Anda.
Batasi jumlah operasi refresh yang dikembalikan
REST API Power BI mendukung pembatasan jumlah entri yang diminta dalam sejarah penyegaran dengan menggunakan parameter opsional $top
. Jika tidak ditentukan, defaultnya adalah semua entri yang tersedia.
GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}
GET /refreshes/<requestId>
Untuk memeriksa status operasi refresh, gunakan kata kerja GET pada objek refresh dengan menentukan requestId
. Jika operasi sedang berlangsung, status
mengembalikan InProgress
, seperti dalam contoh isi respons berikut:
{
"startTime": "2020-12-07T02:06:57.1838734Z",
"endTime": "2020-12-07T02:07:00.4929675Z",
"type": "Full",
"status": "InProgress",
"currentRefreshType": "Full",
"objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer",
"status": "InProgress"
},
{
"table": "DimDate",
"partition": "DimDate",
"status": "InProgress"
}
]
}
DELETE /refreshes/<requestId>
Untuk membatalkan operasi refresh yang sedang berlangsung, gunakan perintah DELETE pada objek refresh dengan menyebutkan requestId
.
Misalnya
DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac
Pertimbangan dan batasan
Operasi refresh memiliki pertimbangan dan batasan berikut:
Operasi refresh standar
- Anda tidak dapat membatalkan refresh model terjadwal atau sesuai permintaan yang dipicu dengan memilih tombol refresh di portal, menggunakan
DELETE /refreshes/<requestId>
. - Refresh model terjadwal dan sesuai permintaan yang dipicu dengan memilih tombol refresh di portal, tidak mendukung mendapatkan detail operasi refresh menggunakan
GET /refreshes/<requestId>
. - Dapatkan rincian dan Batalkan adalah operasi baru untuk pembaruan yang disempurnakan saja. Refresh standar tidak mendukung operasi ini.
Power BI Embedded
Jika kapasitas dijeda secara manual di portal Power BI atau dengan menggunakan PowerShell, atau terjadi pemadaman sistem, status operasi refresh yang ditingkatkan yang sedang berlangsung tetap InProgress
selama maksimal enam jam. Jika kapasitas pulih dalam waktu enam jam, operasi refresh akan dilanjutkan secara otomatis. Jika kapasitas dilanjutkan setelah lebih dari enam jam, operasi refresh mungkin mengembalikan kesalahan timeout. Anda kemudian harus memulai ulang operasi refresh.
Pembuangan model semantik
Power BI menggunakan manajemen memori dinamis untuk mengoptimalkan memori kapasitas. Jika model dikeluarkan dari memori selama operasi refresh, kesalahan berikut mungkin kembali:
{
"messages": [
{
"code": "0xC11C0020",
"message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
"type": "Error"
}
]
}
Solusinya adalah menjalankan kembali operasi refresh. Untuk mempelajari selengkapnya tentang manajemen memori dinamis dan penghapusan model, lihat Penghapusan Model.
Batas waktu operasi pembaruan
Operasi refresh dapat mencakup beberapa upaya jika retryCount
ditentukan. Setiap upaya memiliki batas waktu default 5 jam, yang dapat disesuaikan menggunakan parameter timeout
. Total durasi refresh, termasuk percobaan ulang, tidak boleh melebihi 24 jam.
Jika retryCount
menentukan angka, operasi pembaruan baru dimulai dengan batas waktu. Layanan mencoba kembali operasi ini hingga berhasil, atau mencapai batas retryCount
, atau mencapai maksimum 24 jam sejak percobaan pertama.
Anda dapat menyesuaikan timeout
untuk mempersingkat durasi refresh untuk deteksi kegagalan yang lebih cepat atau memperluasnya di luar default 5 jam untuk refresh data yang lebih kompleks.
Saat merencanakan refresh model semantik Anda dengan Refresh Himpunan Data REST API, pertimbangkan batas waktu dan parameter retryCount. Refresh dapat melebihi batas waktu jika upaya awal gagal dan retryCount diatur ke 1 atau lebih. Jika Anda meminta refresh dengan "retryCount": 1, dan upaya pertama gagal setelah 4 jam, upaya kedua dimulai. Jika ini berhasil dalam 3 jam, total waktu untuk refresh adalah 7 jam.
Jika operasi refresh gagal secara teratur, melebihi batas waktu habis, atau melebihi waktu operasi refresh yang berhasil yang Anda inginkan, pertimbangkan untuk mengurangi jumlah data yang di-refresh dari sumber data. Anda dapat membagi refresh menjadi beberapa permintaan, misalnya permintaan untuk setiap tabel. Anda juga dapat menentukan partialBatch dalam parameter commitMode.
Sampel kode
Untuk sampel kode C# untuk memulai, lihat RestApiSample di GitHub.
Untuk menggunakan sampel kode:
- Klon atau unduh repositori.
- Buka solusi RestApiSample.
- Temukan baris
client.BaseAddress = …
dan berikan URL dasar Anda.
Sampel kode menggunakan autentikasi prinsipal layanan.