Mengekspor laporan Power BI ke file

API exportToFile memungkinkan pengeksporan laporan Power BI menggunakan panggilan REST. Berikut adalah format file yang didukung:

.pptx (PowerPoint)
.pdf
.png
- Saat Anda mengekspor ke .png, laporan dengan beberapa halaman dikompresi menjadi file .zip
- Setiap file di .zip mewakili halaman laporan
- Nama halaman sama dengan nilai pengembalian API Get Pages (Dapatkan Halaman) atau Get Pages in Group (Dapatkan Halaman dalam Grup)

Catatan

Mengekspor laporan Power BI ke file menggunakan API exportToFile tidak didukung untuk Premium Per User (PPU).

Contoh penggunaan

Anda dapat menggunakan fitur ekspor dengan berbagai cara. Berikut adalah beberapa contohnya:

Tombol Send to print (Kirim ke cetak) - Di aplikasi Anda, buat tombol yang memicu tugas ekspor saat diklik. Tugas dapat mengekspor laporan yang ditampilkan sebagai .pdf atau .pptx. Setelah selesai, pengguna dapat menerima file sebagai unduhan. Dengan menggunakan bookmark, Anda dapat mengekspor laporan dalam kondisi tertentu, termasuk filter, slicer, dan pengaturan lain yang sudah dikonfigurasi. Karena API tidak sinkron, mungkin perlu beberapa waktu agar file tersedia.
Lampiran email - Mengirim email otomatis pada interval yang ditetapkan, dengan laporan berformat .pdf terlampir. Skenario ini dapat berguna jika Anda ingin mengotomatiskan pengiriman laporan mingguan ke eksekutif. Untuk informasi selengkapnya, lihat Mengekspor dan mengirim laporan Power BI melalui email dengan Power Automate

Menggunakan API

Persyaratan lisensi

Laporan yang Anda ekspor harus berada di ruang kerja yang didukung oleh kapasitas Premium, Embedded, atau Fabric.
API exportToFiletidak didukung untuk Premium Per Pengguna (PPU).

Pengaturan admin

Sebelum menggunakan API, verifikasi bahwa pengaturan penyewa admin berikut diaktifkan:

Export reports as PowerPoint presentations or PDF documents (Ekspor laporan sebagai presentasi PowerPoint atau dokumen PDF) - Diaktifkan secara default.
Export reports as image files (Ekspor laporan sebagai file gambar) - Diperlukan hanya untuk .png dan dinonaktifkan secara default.

Peristiwa "Penyajian"

Untuk memastikan ekspor tidak dimulai sebelum visual selesai penyajian, gunakan API peristiwa "Penyajian" dan hanya memulai ekspor saat penyajian selesai.

Pemantauan

API bersifat asinkron. Ketika API exportToFile dipanggil, API tersebut memicu tugas ekspor. Setelah memicu tugas ekspor, gunakan polling untuk melacak tugas hingga selesai.

Selama polling, API mengembalikan angka yang mewakili jumlah tugas yang diselesaikan. Pekerjaan dalam setiap tugas ekspor dihitung berdasarkan total ekspor dalam tugas tersebut. Ekspor mencakup mengekspor satu visual atau halaman dengan atau tanpa bookmark. Semua ekspor memiliki bobot yang sama. Jika tugas ekspor Anda termasuk mengekspor laporan dengan 10 halaman, dan hasil polling 70%, itu berarti API memproses tujuh dari 10 halaman dalam tugas ekspor.

Setelah ekspor selesai, panggilan API polling mengembalikan URL Power BI untuk mendapatkan file. URL tersedia selama 24 jam.

Fitur yang didukung

Bagian ini menjelaskan cara menggunakan fitur yang didukung berikut ini:

Memilih halaman yang akan dicetak
Mengekspor satu halaman atau satu visual
Bookmark
Filter
Autentikasi
Keamanan Tingkat Baris (RLS)
Perlindungan data
Pelokalan
Pengikatan dinamis

Memilih halaman yang akan dicetak

Tentukan halaman yang ingin Anda cetak sesuai dengan nilai pengembalian Get Pages atau Get Pages in Group. Anda juga dapat menentukan urutan halaman yang diekspor.

Mengekspor satu halaman atau satu visual

Anda dapat menentukan satu halaman atau satu visual untuk diekspor. Halaman dapat diekspor dengan atau tanpa bookmark.

Tergantung pada jenis ekspor, Anda perlu meneruskan atribut yang berbeda ke objek ExportReportPage. Tabel berikut menentukan atribut mana yang diperlukan untuk setiap pekerjaan ekspor.

Catatan

Mengekspor satu visual memiliki bobot yang sama dengan mengekspor satu halaman (dengan atau tanpa bookmark). Artinya, dalam hal perhitungan sistem, kedua operasi memiliki nilai yang sama.

Atribut	Halaman	Komentar
`bookmark`	Opsional	Gunakan untuk mengekspor halaman dalam status tertentu
`pageName`		Gunakan REST API GetPages atau `getPages` API Klien.
`visualName`		Ada dua cara untuk mendapatkan nama elemen visual: `getVisuals` Gunakan API klien. Dengarkan dan catat peristiwa visualClicked, yang dipicu saat visual dipilih. Untuk informasi selengkapnya, lihat Cara menangani peristiwa .

Bookmark

Bookmark dapat digunakan untuk menyimpan laporan dalam konfigurasi tertentu, termasuk filter yang diterapkan dan status visual laporan. Anda dapat menggunakan API exportToFile untuk mengekspor bookmark laporan secara terprogram, dengan dua cara:

Mengekspor bookmark yang sudah ada

Untuk mengekspor bookmark laporan yang sudah ada, gunakan properti name, pengidentifikasi unik (peka huruf besar/kecil), yang bisa Anda dapatkan menggunakan bookmark API JavaScript.
Mengekspor kondisi laporan

Untuk mengekspor status laporan saat ini, gunakan properti state. Misalnya, Anda dapat menggunakan metode bookmarksManager.capture bookmark untuk mengambil perubahan yang dibuat pengguna tertentu pada laporan, lalu mengekspornya dalam status saat ini menggunakan capturedBookmark.state.

Catatan

Bookmark pribadi dan filter persisten tidak didukung.

Filter

Menggunakan reportLevelFilters di PowerBIReportExportConfiguration, Anda dapat mengekspor laporan dalam kondisi yang difilter.

Untuk mengekspor laporan yang difilter, sisipkan parameter string kueri URL yang ingin Anda gunakan sebagai filter ke ExportFilter. Saat memasukkan string, Anda harus menghapus bagian ?filter= pada parameter kueri URL.

Tabel menyertakan beberapa contoh sintaks string yang dapat Anda teruskan ke ExportFilter.

Filter	Sintaks	Contoh
Nilai dalam kolom	Tabel/Bidang sama dengan 'value'	Toko/Daerah sama dengan 'NC'
Beberapa nilai dalam kolom	Tabel/Bidang di ('value1', 'value2')	Toko/Wilayah di ('NC', 'TN')
Nilai yang berbeda dalam satu bidang, dan nilai yang berbeda di bidang lainnya	PTabel/Bidang1 sama dengan 'value1' dan Tabel/Bidang2 sama dengan 'value2'	Toko/Wilayah sama dengan 'NC' dan Toko/Jaringan sama dengan 'Fashions Direct'

Autentikasi

Anda dapat mengautentikasi menggunakan pengguna (atau pengguna master) atau perwakilan layanan.

Keamanan Tingkat Baris (RLS)

Dengan Keamanan Tingkat Baris (RLS), Anda dapat mengekspor laporan yang memperlihatkan data yang terlihat hanya oleh pengguna tertentu. Misalnya, jika Anda mengekspor laporan penjualan yang ditentukan dengan peran regional, Anda dapat memfilter laporan secara terprogram sehingga hanya wilayah tertentu yang ditampilkan.

Untuk mengekspor menggunakan RLS, Anda harus memiliki izin berikut:

Izin tulis untuk model semantik yang tersambung dengan laporan
Kontributor atau admin ruang kerja tempat laporan berada

Perlindungan data

Format .pdf dan .pptx mendukung label sensitivitas. Jika Anda mengekspor laporan dengan label sensitivitas ke .pdf atau .pptx, file yang diekspor menampilkan laporan dengan label sensitivitasnya.

Laporan dengan label sensitivitas tidak dapat diekspor ke .pdf atau .pptx menggunakan prinsip layanan.

Pelokalan

Saat menggunakan exportToFile API, Anda dapat meneruskan lokal yang Anda inginkan. Pengaturan pelokalan memengaruhi cara laporan ditampilkan, misalnya dengan mengubah pemformatan sesuai dengan lokal yang dipilih.

Pengikatan dinamis

Untuk mengekspor laporan saat terhubung ke model semantik selain model semantik default, tentukan ID himpunan data yang diperlukan pada parameter datasetToBind saat memanggil API. Baca selengkapnya tentang pengikatan dinamis.

Permintaan bersamaan

exportToFile API mendukung sejumlah permintaan bersamaan yang terbatas. Jumlah maksimum permintaan bersamaan yang didukung adalah 500 per kapasitas. Untuk menghindari melebihi batas dan mendapatkan kesalahan Terlalu Banyak Permintaan (429), distribusikan beban seiring waktu atau di antara berbagai kapasitas. Hanya lima halaman laporan yang diproses secara bersamaan. Misalnya, jika Anda mengekspor laporan dengan 50 halaman, pekerjaan ekspor diproses dalam 10 interval berurutan. Saat mengoptimalkan tugas ekspor, Anda mungkin ingin mempertimbangkan untuk menjalankan beberapa tugas secara paralel.

Contoh kode

Saat Anda membuat tugas ekspor, ada empat langkah yang harus diikuti:

Mengirimkan permintaan ekspor.
Polling.
Mendapatkan file.
Menggunakan berkas aliran

Bagian ini menyediakan contoh untuk setiap langkah.

Langkah 1 - mengirimkan permintaan ekspor

Langkah pertama adalah mengirim sebuah permintaan ekspor. Dalam contoh ini, permintaan ekspor dikirim untuk halaman tertentu.

private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId,
    FileFormat format,
    IList<string> pageNames = null, /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
    var powerBIReportExportConfiguration = new PowerBIReportExportConfiguration
    {
        Settings = new ExportReportSettings
        {
            Locale = "en-us",
        },
        // Note that page names differ from the page display names
        // To get the page names use the GetPages REST API
        Pages = pageNames?.Select(pn => new ExportReportPage(Name = pn)).ToList(),
        // ReportLevelFilters collection needs to be instantiated explicitly
        ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

    };

    var exportRequest = new ExportReportRequest
    {
        Format = format,
        PowerBIReportConfiguration = powerBIReportExportConfiguration,
    };

    // The 'Client' object is an instance of the Power BI .NET SDK
    var export = await Client.Reports.ExportToFileInGroupAsync(groupId, reportId, exportRequest);

    // Save the export ID, you'll need it for polling and getting the exported file
    return export.Id;
}

Langkah 2 - polling

Setelah Anda mengirim permintaan ekspor, gunakan polling untuk mengidentifikasi kapan file ekspor yang Anda tunggu sudah siap.

private async Task<HttpOperationResponse<Export>> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the PostExportRequest response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    HttpOperationResponse<Export> httpMessage = null;
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int c_secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations 
            return null;
        }

        // The 'Client' object is an instance of the Power BI .NET SDK
        httpMessage = await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
        exportStatus = httpMessage.Body;

        // You can track the export progress using the PercentComplete that's part of the response
        SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(), exportStatus.PercentComplete);
        if (exportStatus.Status == ExportState.Running || exportStatus.Status == ExportState.NotStarted)
        {
            // The recommended waiting time between polling requests can be found in the RetryAfter header
            // Note that this header is not always populated
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;
            await Task.Delay(retryAfterInSec * c_secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return httpMessage;
}

Langkah 3 - mendapatkan file

Setelah polling mengembalikan URL, gunakan contoh ini untuk mendapatkan file yang diterima.

private async Task<ExportedFile> GetExportedFile(
    Guid reportId,
    Guid groupId,
    Export export /* Get from the PollExportRequest response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        // The 'Client' object is an instance of the Power BI .NET SDK
        var fileStream = await Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
        return new ExportedFile
        {
            FileStream = fileStream,
            FileSuffix = export.ResourceFileExtension,
        };
    }
    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string FileSuffix;
}

Langkah 4 - Menggunakan stream file

Saat memiliki stream file, Anda dapat menanganinya dengan cara yang paling sesuai dengan kebutuhan. Misalnya, Anda dapat mengirim email atau menggunakannya untuk mengunduh laporan yang diekspor.

Contoh ujung-ke-ujung

Ini adalah contoh menyeluruh untuk mengekspor laporan. Contoh ini mencakup tahapan berikut:

Mengirim permintaan ekspor.
Polling.
Mendapatkan file.

private async Task<ExportedFile> ExportPowerBIReport(
	Guid reportId,
	Guid groupId,
	FileFormat format,
	int pollingtimeOutInMinutes,
	CancellationToken token,
	IList<string> pageNames = null,  /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
	const int c_maxNumberOfRetries = 3; /* Can be set to any desired number */
	const int c_secToMillisec = 1000;
	try
	{
		Export export = null;
		int retryAttempt = 1;
		do
		{
			var exportId = await PostExportRequest(reportId, groupId, format, pageNames, urlFilter);
			var httpMessage = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
			export = httpMessage.Body;
			if (export == null)
			{
				// Error, failure in exporting the report
				return null;
			}
			if (export.Status == ExportState.Failed)
			{
				// Some failure cases indicate that the system is currently busy. The entire export operation can be retried after a certain delay
				// In such cases the recommended waiting time before retrying the entire export operation can be found in the RetryAfter header
				var retryAfter = httpMessage.Response.Headers.RetryAfter;
				if(retryAfter == null)
				{
				    // Failed state with no RetryAfter header indicates that the export failed permanently
				    return null;
                }

                var retryAfterInSec = retryAfter.Delta.Value.Seconds;
                await Task.Delay(retryAfterInSec * c_secToMillisec);
            }
        }
        while (export.Status != ExportState.Succeeded && retryAttempt++ < c_maxNumberOfRetries);

        if (export.Status != ExportState.Succeeded)
        {
            // Error, failure in exporting the report
            return null;
        }

        var exportedFile = await GetExportedFile(reportId, groupId, export);

        // Now you have the exported file stream ready to be used according to your specific needs
        // For example, saving the file can be done as follows:
        /*
            var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;

            using (var fileStream = File.Create(pathOnDisk))
            {
                exportedFile.FileStream.CopyTo(fileStream);
            }
        */

        return exportedFile;
    }
    catch
    {
        // Error handling
        throw;
    }
}

Pertimbangan dan batasan

Beban operasi API ekspor dinilai sebagai operasi latar belakang yang berjalan lambat, sebagaimana dijelaskan dalam evaluasi beban kapasitas Premium.
Semua model semantik terkait dalam laporan yang Anda ekspor harus berada di kapasitas Fabric, Premium, atau Embedded, termasuk model semantik dengan koneksi Direct Query.
Laporan yang diekspor tidak boleh melebihi ukuran file 250 MB.
Saat mengekspor ke .png, label sensitivitas tidak didukung.
Jumlah ekspor yang diperbolehkan (visual tunggal atau halaman laporan) yang dapat disertakan dalam satu laporan ekspor adalah 50 (tidak termasuk ekspor laporan terpaginasikan). Jika permintaan menyertakan lebih banyak ekspor, API mengembalikan kesalahan dan tugas ekspor dibatalkan.
Penanda halaman pribadi dan filter persisten tidak didukung untuk mengekspor laporan Power BI ke file.
exportToFile API mengekspor laporan dengan nilai default jika digunakan tanpa bookmark atau reportLevelFilters.
Mengekspor laporan Power BI yang tersambung ke satu atau lebih model semantik komposit, yang memiliki setidaknya satu sumber data eksternal dengan single sign-on (SSO) yang diaktifkan, tidak didukung. Saat mengekspor, visual mungkin tidak dirender dengan benar.
Saat mengekspor laporan dengan pengikatan dinamis menggunakan exportToFile REST API, model semantik yang terikat secara dinamis tidak dapat menjadi model komposit dengan kueri langsung ke SQL Server Analysis Services (SSAS).
Visual Power BI yang tercantum di sini tidak didukung. Saat Anda mengekspor laporan yang berisi visual ini, bagian laporan yang berisi visual ini tidak dirender, dan menampilkan simbol kesalahan.
- Visual kustom Power BI tidak bersertifikat
- Visualisasi R
- PowerApps
- Visual Python
- Power Automate
- Visual laporan berhalaman
- Visio
- Visual ArcGIS

Tinjau cara menyematkan konten untuk pelanggan dan organisasi Anda:

Pertanyaan Lainnya? Coba Komunitas Power BI

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-02-25

Mengekspor laporan Power BI ke file

Contoh penggunaan

Menggunakan API

Persyaratan lisensi

Pengaturan admin

Peristiwa "Penyajian"

Pemantauan​

Fitur yang didukung

Memilih halaman yang akan dicetak

Mengekspor satu halaman atau satu visual

Bookmark

Filter

Autentikasi

Keamanan Tingkat Baris (RLS)

Perlindungan data

Pelokalan

Pengikatan dinamis

Permintaan bersamaan

Contoh kode

Langkah 1 - mengirimkan permintaan ekspor

Langkah 2 - polling

Langkah 3 - mendapatkan file

Langkah 4 - Menggunakan stream file

Contoh ujung-ke-ujung

Pertimbangan dan batasan

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan:

Pemantauan