Export zostavy Power BI do súboru

  • Článok

Rozhranie exportToFile API umožňuje exportovať zostavu Power BI pomocou volania REST. Podporované sú nasledujúce formáty súborov:

  • .pptx (PowerPoint)
  • .Pdf
  • .png

Poznámka

Export zostavy Power BI do súboru pomocou rozhrania API exportToFile nie je pre službu Premium na používateľa (PPU) podporovaný.

Príklady používania

Funkciu exportu môžete použiť niekoľkými spôsobmi. Tu je niekoľko príkladov:

  • Tlačidlo odoslania na tlač – v aplikácii vytvorte tlačidlo, kliknutím na ktoré sa spustí úloha exportu. Úloha môže exportovať zobrazenú zostavu ako .pdf alebo .pptx. Po dokončení môže používateľ súbor prijať ako stiahnutie. Pomocou záložiek môžete zostavu exportovať v konkrétnom stave vrátane nakonfigurovaných filtrov, rýchlych filtrov a ďalších nastavení. Keďže rozhranie API je asynchrónne, môže to nejaký čas trvať, kým bude súbor k dispozícii.

  • Príloha e-mailu – odosielajte automatizované e-maily v nastavených intervaloch s priloženou zostavou vo formáte .pdf. Tento scenár môže byť užitočný, ak chcete automatizovať odosielanie týždennej zostavy vedúcim pracovníkom. Ďalšie informácie nájdete v téme Exportovanie a odosielanie zostáv služby Power BI e-mailom pomocou služby Power Automate

Používanie rozhrania API

Požiadavky na licencie

  • Exportovaná zostava sa musí nachádzať v pracovnom priestore podporovanom kapacitou Premium, Embedded alebo Fabric.
  • Rozhranie exportToFile API nie je podporované pre službu Premium na používateľa.

Nastavenia správcu

Pred použitím rozhrania API overte, či sú povolené nasledujúce nastavenia nájomníka správcu:

  • Exportovať zostavy ako powerpointové prezentácie alebo PDF dokumenty – povolené v predvolenom nastavení.
  • Exportovať zostavy ako obrázkové súbory – vyžaduje sa iba pre súbory .png a zakázané v predvolenom nastavení.

Udalosti "vykresľovania"

Aby ste sa uistili, že export sa nezačína skôr, než sa vizuál dokončí, použite rozhranie API udalostí "Vykresľovanie" a export sa spustí až po dokončení vykresľovania.

Volebných

Rozhranie API je asynchrónne. Pri volaní rozhrania API exportToFile sa spustí úloha exportu. Po spustení úlohy exportu použite vzorkovanie na sledovanie úlohy, kým nebude dokončená.

Počas vzorkovania rozhranie API vráti číslo, ktoré predstavuje dokončené množstvo práce. Práca v každej úlohe exportu sa vypočíta na základe celkového počtu exportov v rámci úlohy. Export zahŕňa export jedného vizuálu alebo strany so záložkami alebo bez záložiek. Všetky exporty majú rovnakú váhu. Ak vaša úloha exportu napríklad zahŕňa export zostavy s 10 stranami a vzorkovanie vráti číslo 70, znamená to, že rozhranie API spracoval sedem z 10 strán v úlohe exportu.

Po dokončení exportu volanie rozhrania API vzorkovania vráti URL adresu služby Power BI na získanie súboru. URL adresa je k dispozícii 24 hodín.

Podporované funkcie

Táto časť popisuje, ako používať tieto podporované funkcie:

Výber strán na tlač

Zadajte strany, ktoré sa majú vytlačiť, podľa vrátenej hodnoty Získať strany alebo Získať strany v skupine . Môžete tiež určiť poradie strán, ktoré exportujete.

Exportovanie strany alebo jedného vizuálu

Môžete zadať stranu alebo jeden vizuál, ktorý sa má exportovať. Strany je možné exportovať so záložkami alebo bez záložiek.

V závislosti od typu exportu musíte preniesť rôzne atribúty do objektu ExportReportPage . Nasledujúca tabuľka určuje, ktoré atribúty sa vyžadujú pre každú úlohu exportu.

Poznámka

Exportovanie jedného vizuálu má rovnakú váhu ako export strany (so záložkami alebo bez záložiek). To znamená, že z hľadiska systémových výpočtov majú obe operácie rovnakú hodnotu.

Atribút Stránka Jeden vizuál Komentáre
bookmark Voliteľné Does not apply to. Používa sa na exportovanie stránky v konkrétnom stave
pageName Applies to. Applies to. Použite rozhranie GetPages REST API alebo klientske getPages rozhranie API.
visualName Does not apply to. Applies to. Názov vizuálu možno získať dvoma spôsobmi:
  • Použite rozhranie getVisuals API klienta.
  • Poslúchnite a zapíšte do denníka udalosť visualClicked, ktorá sa spustí po výbere vizuálu. Ďalšie informácie nájdete v téme Spracovanie udalostí.
    • .

    Záložky

    Záložky možno použiť na uloženie zostavy v konkrétnej konfigurácii vrátane použitých filtrov a stavu vizuálov zostavy. Pomocou rozhrania API exportToFile môžete programovaním exportovať záložku zostavy dvoma spôsobmi:

    Poznámka

    Osobné záložky a trvalé filtre nie sú podporované.

    Filtre

    Pomocou reportLevelFilters položky v konfigurácii PowerBIReportExportConfiguration môžete zostavu exportovať vo filtrovanej podmienke.

    Ak chcete exportovať filtrovanú zostavu, vložte parametre reťazca dotazu URL, ktorý chcete použiť ako filter, do položky ExportFilter. Keď zadáte reťazec, musíte odstrániť ?filter= časť parametra dotazu URL adresy.

    Tabuľka obsahuje niekoľko príkladov syntaxe reťazcov, ktoré môžete preniesť do .ExportFilter

    Filter Syntax Príklad
    Hodnota v poli Table/Field eq 'value' Store/Territory eq 'NC'
    Viaceré hodnoty v poli Table/Field in ('value1', 'value2') Store/Territory in ('NC', 'TN')
    Jedinečná hodnota v jednom poli a iná jedinečná hodnota v inom poli Table/Field1 eq 'value1' a Table/Field2 eq 'value2' Store/Territory eq 'NC' a Store/Chain eq 'Fashions Direct'

    Overovanie

    Overovanie môžete vykonať pomocou používateľa (alebo hlavného používateľa) alebo objektu služby.

    Zabezpečenie na úrovni riadkov

    So zabezpečením na úrovni riadkov (RLS) môžete exportovať zostavu, v ktorej sa zobrazujú údaje viditeľné len pre určitých používateľov. Ak napríklad exportujete zostavu predaja definovanú s rolami pre oblasti, môžete naprogramovať filtrovanie zostavy tak, aby sa zobrazila len určitá oblasť.

    Ak chcete exportovať pomocou zabezpečenia na úrovni riadkov, musíte mať nasledujúce povolenia:

    • Zapisovať a opätovne zdieľať povolenia pre sémantický model, ku ktorému je zostava pripojená
    • Člen pracovného priestoru alebo správca pracovného priestoru, v ktorom sa zostava nachádza

    Ochrana údajov

    Formáty .pdf a .pptx podporujú označenia citlivosti. Ak exportujete zostavu s označením citlivosti do súboru .pdf alebo .pptx, exportovaný súbor zobrazí zostavu s jej označením citlivosti.

    Zostavu s označením citlivosti nie je možné exportovať do súboru .pdf ani .pptx pomocou objektu služby.

    Lokalizácia

    Pri používaní rozhrania exportToFile API môžete zadajte požadované miestne nastavenie. Nastavenia lokalizácie ovplyvňujú spôsob zobrazenia zostavy, napríklad zmenou formátovania podľa vybratého miestneho nastavenia.

    Dynamická väzba

    Ak chcete exportovať zostavu, keď je pripojená k sémantickému modelu, iný ako predvolený sémantický model, zadajte požadované ID množiny údajov v datasetToBind parametri pri volaní rozhrania API. Prečítajte si viac o dynamickej väzbe.

    Súbežné žiadosti

    Rozhranie exportToFile API podporuje obmedzený počet súbežných požiadaviek. Maximálny počet podporovaných súbežných požiadaviek je 500 na kapacitu. Ak sa chcete vyhnúť prekročeniu limitu a výskytu chyby Too Many Requests (429), rozmiestnite zaťaženie v čase alebo v rámci kapacít. Súbežne sa spracuje iba päť strán zostavy. Ak napríklad exportujete zostavu s 50 stranami, úloha exportu sa spracuje v 10 sekvenčných intervaloch. Pri optimalizácii exportu môžete zvážiť vykonanie niekoľkých úloh súčasne.

    Príklady kódu

    Pri vytváraní úlohy exportu postupujte podľa štyroch krokov:

    1. Odoslanie žiadosti o export.
    2. Vzorkovanie.
    3. Načítajte súbor.
    4. Používanie streamu súborov.

    Táto časť obsahuje príklady každého kroku.

    Krok 1 – odoslanie žiadosti o export

    Prvým krokom je odoslanie žiadosti o export. V tomto príklade sa odošle žiadosť o export konkrétnej strany.

    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;
}

    Krok 2 – vzorkovanie

    Po odoslaní žiadosti o export použite vzorkovanie a identifikujte, kedy bude čakajúci exportovaný súbor pripravený.

    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;
}

    Krok 3 – na získanie súboru

    Keď vzorkovanie vráti URL adresu, prijatý súbor môžete načítať pomocou tohto príkladu.

    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;
}

    Krok 4 – Používanie streamu súborov

    Keď máte stream súborov, môžete s ním pracovať spôsobom, ktorý najlepšie vyhovuje vašim potrebám. Môžete ho napríklad odoslať e-mailom alebo ho použiť na stiahnutie exportovaných zostáv.

    Komplexný príklad

    Toto je komplexný príklad exportu zostavy. Tento príklad obsahuje tieto fázy:

    1. Odoslanie žiadosti o export.
    2. Vzorkovanie.
    3. Načítajte súbor.
    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;
    }
}

    Dôležité informácie a obmedzenia

    • Zaťaženie operácií rozhrania API exportu sa vyhodnotí ako pomaly spustená operácia na pozadí, ako je popísané v časti Vyhodnocovanie zaťaženia kapacity Premium.
    • Všetky súvisiace sémantické modely v exportovanej zostave sa musia nachádzať v kapacite Premium alebo Embedded, vrátane sémantických modelov s pripojením Direct Query.
    • Exportované zostavy nemôžu prekročiť veľkosť súboru 250 MB.
    • Pri exporte do súboru .png sa označenia citlivosti nepodporujú.
    • Počet exportov (jednotlivých vizuálov alebo strán zostavy), ktoré možno zahrnúť do jednej exportovanej zostavy, je 50 (bez exportu stránkovaných zostáv). Ak žiadosť zahŕňa viac exportov, rozhranie API vráti chybu a úloha exportu sa zruší.
    • Osobné záložky a trvalé filtre nie sú podporované pre export zostavy Power BI do súboru.
    • Rozhranie exportToFile API exportuje zostavu s predvolenou hodnotou, ak sa používa bez záložiek alebo zostáv ReportLevelFilters.
    • Tu uvedené vizuály služby Power BI nie sú podporované. Keď exportujete zostavu obsahujúcu tieto vizuály, nevykreslia sa časti zostavy, ktoré obsahujú tieto vizuály, a zobrazí sa symbol chyby.
      • Necertifikované vlastné vizuály Power BI
      • Vizuály R
      • PowerApps
      • Vizuály v jazyku Python
      • Power Automate
      • Vizuál stránkovanej zostavy
      • Visio
      • Vizuály ArcGIS

    Súvisiaci obsah

    Získajte ďalšie informácie o vkladaní obsahu pre zákazníkov a organizáciu:

    Máte ďalšie otázky? Vyskúšajte Komunita Power BI