Refresh yang disempurnakan dengan Power BI REST API

Artikel
01/08/2025

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 .

Diagram yang memperlihatkan alur refresh asinkron.

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 `commitModetransactional`, `applyRefreshPolicy` bisa `true` atau `false`. Jika `commitModepartialBatch`, `applyRefreshPolicytrue` 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.

Bagikan melalui

Refresh yang disempurnakan dengan Power BI REST API

URL Dasar

Persyaratan

Otentikasi

POST /refreshes

Parameter

Jawaban

GET /refreshes

Properti respons

Batasi jumlah operasi refresh yang dikembalikan

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

Pertimbangan dan batasan

Operasi refresh standar

Power BI Embedded

Pembuangan model semantik

Batas waktu operasi pembaruan

Sampel kode

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Refresh yang disempurnakan dengan Power BI REST API

URL Dasar

Persyaratan

Otentikasi

POST /refreshes

Parameter

Jawaban

GET /refreshes

Properti respons

Batasi jumlah operasi refresh yang dikembalikan

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

Pertimbangan dan batasan

Operasi refresh standar

Power BI Embedded

Pembuangan model semantik

Batas waktu operasi pembaruan

Sampel kode

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: