Bagikan melalui

Refresh yang disempurnakan dengan Power BI REST API

  • Artikel

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 Himpunan Data Refresh Power BI dapat melakukan operasi refresh model secara asinkron, sehingga koneksi HTTP yang berjalan lama dari aplikasi klien tidak diperlukan. Dibandingkan dengan operasi refresh standar, refresh yang disempurnakan dengan REST API menyediakan lebih banyak opsi kustomisasi dan fitur berikut yang berguna untuk model besar:

  • Penerapan batch
  • Refresh tingkat partisi dan tabel
  • Menerapkan kebijakan refresh bertahap
  • GET detail refresh
  • Refresh pembatalan

Catatan

  • 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 me-refresh cache petak peta. Cache petak peta hanya di-refresh 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 adalah koleksi. Grup, Himpunan Data, dan Refresh adalah objek.

Diagram that shows asynchronous refresh flow.

Persyaratan

Anda memerlukan persyaratan berikut untuk menggunakan REST API:

  • Model semantik di Power BI Premium, Premium per pengguna, atau Power BI Embedded.
  • ID grup dan ID himpunan data untuk digunakan dalam URL permintaan.
  • Cakupan izin Dataset.ReadWrite.All .

Jumlah refresh dibatasi per batasan umum untuk refresh berbasis API untuk model Pro dan Premium.

Autentikasi

Semua panggilan harus mengautentikasi dengan token Microsoft Entra ID OAuth 2 yang valid di header Otorisasi. Token harus memenuhi persyaratan berikut:

  • Jadilah token pengguna atau perwakilan layanan aplikasi.
  • Atur audiens dengan benar ke https://api.powerbi.com.
  • Digunakan oleh pengguna atau aplikasi yang memiliki izin yang memadai pada model.

Catatan

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 tidak sinkron, 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,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Catatan

Layanan hanya menerima satu operasi refresh pada satu waktu untuk model. Jika ada refresh yang sedang berjalan dan permintaan lain dikirimkan, 400 Bad Request kode status HTTP 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 Default Deskripsi
type Enum automatic Jenis pemrosesan yang akan dilakukan. Jenis selaras dengan jenis perintah refresh TMSL: full, , clearValues, dataOnlycalculate, automatic, dan defragment. add Jenis tidak didukung.
commitMode Enum transactional Menentukan apakah akan menerapkan 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 MaxParallelism properti yang dapat diatur dalam perintah TMSL Sequence atau dengan menggunakan metode lain.
retryCount Int 0 Berapa kali operasi mencoba kembali sebelum gagal.
objects Array Seluruh model Array objek yang akan 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 adalah true atau false. Jika kebijakan tidak diterapkan, proses penuh membuat definisi partisi tidak berubah, dan sepenuhnya me-refresh semua partisi dalam tabel.

Jika commitMode adalah transactional, applyRefreshPolicy bisa atau truefalse. Jika commitMode adalah partialBatch, applyRefreshPolicy tidak true didukung, dan applyRefreshPolicy harus diatur ke false.
effectiveDate Date Tanggal saat ini Jika kebijakan refresh bertahap diterapkan, parameter effectiveDate akan mengambil alih tanggal saat ini. Jika tidak ditentukan, UTC digunakan untuk menentukan hari ini.

Respons

202 Accepted

Respons juga menyertakan Location bidang header respons untuk mengarahkan pemanggil ke operasi refresh yang dibuat dan diterima. Location adalah lokasi sumber daya baru yang dibuat permintaan, yang mencakup requestId yang diperlukan beberapa operasi refresh yang disempurnakan. 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",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Catatan

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 mengkueri status pada permintaan yang dihilangkan.

Properti respons

Nama Tipe Deskripsi
requestId Guid Pengidentifikasi permintaan refresh. Anda perlu requestId mengkueri status operasi refresh individual atau membatalkan operasi refresh yang sedang berlangsung.
refreshType String OnDemand menunjukkan refresh dipicu secara interaktif melalui portal Power BI.
Scheduled menunjukkan bahwa jadwal refresh model memicu refresh.
ViaApi menunjukkan bahwa panggilan API memicu refresh.
ViaEnhancedApi menunjukkan bahwa panggilan API memicu refresh yang ditingkatkan.
startTime String Tanggal dan waktu mulai refresh.
endTime String Tanggal dan waktu refresh berakhir.
status String 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 String status Menambah properti untuk memberikan informasi lebih lanjut.

Catatan

Di Azure Analysis Services, hasil yang selesai status 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 riwayat refresh 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"
        }
    ]
}

HAPUS /refreshes/<requestId>

Untuk membatalkan operasi refresh yang sedang berlangsung, gunakan kata kerja DELETE pada objek refresh dengan menentukan requestId.

Contohnya,

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 manual terjadwal atau sesuai permintaan dengan menggunakan DELETE /refreshes/<requestId>.
  • Refresh model manual terjadwal dan sesuai permintaan tidak mendukung mendapatkan detail operasi refresh dengan menggunakan GET /refreshes/<requestId>.
  • Dapatkan detail dan Batalkan adalah operasi baru untuk refresh 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 dilanjutkan dalam waktu enam jam, operasi refresh akan dilanjutkan secara otomatis. Jika kapasitas dilanjutkan setelah lebih dari enam jam, operasi refresh mungkin mengembalikan kesalahan waktu habis. Anda kemudian harus memulai ulang operasi refresh.

Pengeluaran 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 pengeluaran model, lihat Pengeluaran model.

Menyegarkan batas waktu operasi

Jumlah waktu maksimum untuk operasi refresh tunggal adalah lima jam. Jika operasi refresh tidak berhasil diselesaikan dalam batas lima jam, dan retryCount tidak ditentukan atau ditentukan sebagai 0 (default) dalam isi permintaan, kesalahan waktu habis akan kembali.

Jika retryCount menentukan 1 atau nomor lain, operasi refresh baru dengan batas lima jam dimulai. Jika operasi coba lagi ini gagal, layanan terus mencoba kembali operasi refresh hingga jumlah percobaan ulang terbesar yang ditentukan, atau batas waktu pemrosesan refresh yang retryCount disempurnakan 24 jam dari awal permintaan refresh pertama.

Saat Anda merencanakan solusi refresh model yang disempurnakan dengan Refresh Himpunan Data REST API, penting untuk mempertimbangkan batas waktu dan parameter ini retryCount . Penyelesaian refresh yang berhasil dapat melebihi lima jam jika operasi refresh awal gagal dan retryCount menentukan 1 atau lebih.

Misalnya, jika Anda meminta operasi refresh dengan "retryCount": 1, dan operasi coba lagi awal gagal empat jam dari waktu mulai, operasi refresh kedua untuk permintaan tersebut dimulai. Jika operasi refresh kedua berhasil dalam tiga jam, total waktu untuk keberhasilan eksekusi permintaan refresh adalah tujuh jam.

Jika operasi refresh gagal secara teratur, melebihi batas waktu lima jam, 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 commitMode parameter .

Sampel kode

Untuk sampel kode C# untuk memulai, lihat RestApiSample di GitHub.

Untuk menggunakan sampel kode:

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

Sampel ini menggunakan autentikasi perwakilan layanan.

Konten terkait