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 Pengguna (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 bookmark, Anda dapat mengekspor laporan dalam status tertentu, termasuk filter, pemotong, dan pengaturan lain yang dikonfigurasi. Karena API tidak sinkron, mungkin perlu beberapa waktu agar file tersedia.

• Lampiran email - Mengirim email otomatis pada interval yang ditetapkan, dengan laporan .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.
• exportToFile API, tidak 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.

Polling

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

Selama polling, API mengembalikan angka yang mewakili jumlah tugas yang diselesaikan. Tugas di setiap tugas ekspor dihitung berdasarkan total ekspor dalam tugas. Ekspor mencakup mengekspor satu visual atau halaman dengan atau tanpa bookmark. Semua ekspor memiliki bobot yang sama. Jika misalnya, pekerjaan ekspor Anda termasuk mengekspor laporan dengan 10 halaman, dan polling mengembalikan 70, itu berarti API memproses tujuh dari 10 halaman dalam pekerjaan 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 (Dapatkan Halaman) atau Get Pages in Group (Dapatkan Halaman dalam Grup). 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	Satu visual	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 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 status 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 bidang	Tabel/Bidang sama dengan 'value'	Penyimpanan/Wilayah sama dengan 'NC'
Beberapa nilai dalam bidang	Tabel/Bidang di ('value1', 'value2')	Penyimpanan/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'	Penyimpanan/Wilayah sama dengan 'NC' dan Penyimpanan/Rantai 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 perwakilan 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 tersambung ke model semantik, lalu model semantik default, tentukan ID himpunan data yang datasetToBind diperlukan dalam parameter 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 dari waktu ke waktu atau di seluruh 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:

1. Mengirimkan permintaan ekspor.
2. Polling.
3. Mendapatkan file.
4. Menggunakan stream file.

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:

1. Mengirim permintaan ekspor.
2. Polling.
3. 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 dievaluasi sebagai operasi latar belakang yang berjalan lambat, seperti yang dijelaskan dalam evaluasi beban kapasitas Premium.
• Semua model semantik terkait dalam laporan yang Anda ekspor harus berada pada kapasitas Premium atau Tersemat, 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 (visual tunggal atau halaman laporan) yang dapat disertakan dalam satu laporan yang diekspor adalah 50 (tidak termasuk mengekspor laporan paginated). Jika permintaan menyertakan lebih banyak ekspor, API mengembalikan kesalahan dan tugas ekspor dibatalkan.
• Marka buku pribadi dan filter persisten tidak didukung untuk ekspor 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 beberapa model semantik komposit, yang memiliki setidaknya satu sumber data eksternal dengan akses menyeluruh (SSO) diaktifkan, tidak didukung. Saat mengekspor, visual mungkin tidak dirender dengan benar.
• 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
  • Visual R
  • PowerApps
  • Visual Python
  • Power Automate
  • Visual laporan bernomor halaman
  • Visio
  • Visual ArcGIS

Konten terkait

Tinjau cara menyematkan konten untuk pelanggan dan organisasi Anda:

• Mengekspor laporan bernomor halaman ke file
• Sematkan untuk pelanggan Anda
• Menyematkan untuk organisasi Anda
• Mengekspor dan mengirim laporan Power BI melalui email dengan Power Automate

Pertanyaan Lainnya? Coba Komunitas Power BI