Bagikan melalui


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 .

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:

  1. Klon atau unduh repositori.
  2. Buka solusi RestApiSample.
  3. Temukan baris client.BaseAddress = … dan berikan URL dasar Anda.

Sampel kode menggunakan autentikasi prinsipal layanan.