Export sestavy Power BI do souboru

  • Článek

Rozhraní exportToFile API umožňuje exportovat sestavu Power BI pomocí volání REST. Podporují se následující formáty souborů:

Poznámka:

Export sestavy Power BI do souboru pomocí rozhraní API exportToFile se nepodporuje pro premium na uživatele (PPU).

Příklady použití

Funkci exportu můžete použít několika způsoby. Tady je několik příkladů:

  • Tlačítko Odeslat k tisku – V aplikaci vytvořte tlačítko, které po kliknutí na aktivuje úlohu exportu. Úloha může exportovat zobrazenou sestavu jako soubor .pdf nebo .pptx. Po dokončení může uživatel soubor přijmout jako stažení. Pomocí záložek můžete sestavu exportovat do určitého stavu, včetně nakonfigurovaných filtrů, průřezů a dalších nastavení. Vzhledem k tomu, že je rozhraní API asynchronní, může být soubor k dispozici až po určité době.

  • Příloha e-mailu – v nastavených intervalech pošlete automatizovaný e-mail s připojenou sestavou .pdf. Tento scénář může být užitečný, pokud chcete automatizovat odesílání týdenních sestav vedoucím pracovníkům. Další informace najdete v tématu Export a odeslání sestavy Power BI e-mailem pomocí Power Automate.

Použití rozhraní API

Požadavky na licenci

  • Sestava, kterou exportujete, se musí nacházet v pracovním prostoru s podporou kapacity Premium, Embedded nebo Fabric.
  • Rozhraní exportToFile API není podporováno pro Premium na uživatele (PPU).

Nastavení správce

Před použitím rozhraní API ověřte, že jsou povolená následující nastavení tenanta správce:

  • Export sestav jako powerpointových prezentací nebo dokumentů PDF – ve výchozím nastavení je povoleno.
  • Exportovat sestavy jako soubory obrázků – Vyžaduje se jenom pro soubory .png a ve výchozím nastavení je zakázáno.

Události vykreslování

Abyste měli jistotu, že export nezačne před dokončením vykreslování vizuálu, použijte rozhraní API pro vykreslování událostí a export zahajte pouze po dokončení vykreslování.

cyklické dotazování

Rozhraní API je asynchronní. Při volání rozhraní API exportToFile aktivuje úlohu exportu. Po aktivaci úlohy exportu můžete pomocí dotazování sledovat úlohu, dokud se nedokončí.

Během dotazování vrátí rozhraní API číslo, které představuje množství dokončené práce. Práce v každé úloze exportu se vypočítá na základě celkového počtu exportů v úloze. Export zahrnuje export jednoho vizuálu nebo stránky se záložkami nebo bez záložek. Všechny exporty mají stejnou váhu. Pokud například vaše úloha exportu zahrnuje export sestavy s 10 stránkami a dotazování vrátí 70, znamená to, že rozhraní API zpracovalo sedm z 10 stránek v úloze exportu.

Po dokončení exportu volání rozhraní API pro dotazování vrátí adresu URL Power BI pro získání souboru. Adresa URL je k dispozici po dobu 24 hodin.

Podporované funkce

Tato část popisuje, jak používat následující podporované funkce:

Výběr stránek, které se mají vytisknout

Zadejte stránky, které chcete vytisknout, podle návratové hodnoty Získat stránky nebo Získat stránky ve skupině . Můžete také zadat pořadí stránek, které exportujete.

Export stránky nebo jednoho vizuálu

Můžete zadat stránku nebo jeden vizuál, který se má exportovat. Stránky je možné exportovat se záložkami nebo bez nich.

V závislosti na typu exportu musíte předat různé atributy ExportReportPage objektu. Následující tabulka určuje, které atributy jsou požadovány pro každou úlohu exportu.

Poznámka:

Export jednoho vizuálu má stejnou váhu jako export stránky (se záložkami nebo bez). To znamená, že pokud jde o systémové výpočty, obě operace mají stejnou hodnotu.

Atribut Page Jeden vizuál Poznámky
bookmark Volitelné Does not apply to. Slouží k exportu stránky v určitém stavu.
pageName Applies to. Applies to. Použijte rozhraní REST API GetPages nebo getPages klientské rozhraní API.
visualName Does not apply to. Applies to. Název vizuálu můžete získat dvěma způsoby:
  • getVisuals Použijte klientské rozhraní API.
  • Naslouchejte a protokolujte událost visualClicked , která se aktivuje při výběru vizuálu. Další informace naleznete v tématu Zpracování událostí
    • .

    Záložky

    Záložky lze použít k uložení sestavy v konkrétní konfiguraci, včetně použitých filtrů a stavu vizuálů sestavy. Rozhraní API exportToFile můžete použít k programovému exportu záložky sestavy dvěma způsoby:

    • Export existující záložky

      Pokud chcete exportovat existující záložku name sestavy, použijte vlastnost, jedinečný identifikátor (rozlišující malá a velká písmena), který můžete získat pomocí javascriptového rozhraní API záložek.

    • Export stavu sestavy

      Pokud chcete exportovat aktuální stav sestavy, použijte state vlastnost. Pomocí metody záložky bookmarksManager.capture můžete například zachytit změny provedené konkrétním uživatelem v sestavě a pak ho exportovat do aktuálního stavu pomocí capturedBookmark.state.

    Poznámka:

    Osobní záložky a trvalé filtry se nepodporují.

    Filtry

    V reportLevelFilters PowerBIReportExportConfiguration můžete exportovat sestavu ve filtrované podmínce.

    Pokud chcete exportovat filtrovanou sestavu, vložte do exportfilteru parametry řetězce dotazu URL, které chcete použít jako filtr. Při zadávání řetězce je nutné odebrat ?filter= část parametru dotazu adresy URL.

    Tabulka obsahuje několik příkladů syntaxe řetězců, které ExportFiltermůžete předat .

    Filtr Syntaxe Příklad
    Hodnota v poli Table/Field eq 'value' Store/Territory eq 'NC'
    Více hodnot v poli Table/Field in ('value1', 'value2') Store/Territory in ('NC', 'TN')
    Jedinečná hodnota v jednom poli a jiná odlišná hodnota v jiném poli Table/Field1 eq 'value1' and Table/Field2 eq 'value2' Store/Territory eq 'NC' and Store/Chain eq 'Fashions Direct'

    Ověřování

    Můžete se ověřit pomocí uživatele (nebo hlavního uživatele) nebo instančního objektu.

    Zabezpečení na úrovni řádků (RLS)

    Pomocí zabezpečení na úrovni řádků (RLS) můžete exportovat sestavu zobrazující data, která jsou viditelná jenom určitým uživatelům. Pokud například exportujete sestavu prodeje definovanou s regionálními rolemi, můžete sestavu programově filtrovat tak, aby se zobrazila jenom určitá oblast.

    Pokud chcete exportovat pomocí zabezpečení na úrovni řádků, musíte mít následující oprávnění:

    • Oprávnění k zápisu a opětovnému sdílení pro sémantický model, ke kterému je sestava připojená
    • Člen pracovního prostoru nebo správce pracovního prostoru, ve kterém se sestava nachází

    Ochrana dat

    Formáty .pdf a .pptx podporují popisky citlivosti. Pokud exportujete sestavu s popiskem citlivosti do souboru .pdf nebo .pptx, exportovaný soubor zobrazí sestavu s popiskem citlivosti.

    Sestavu s popiskem citlivosti nelze exportovat do souboru .pdf nebo .pptx pomocí instančního objektu.

    Lokalizace

    Při použití exportToFile rozhraní API můžete předat požadované národní prostředí. Nastavení lokalizace ovlivňuje způsob zobrazení sestavy, například změnou formátování podle vybraného místního nastavení.

    Dynamická vazba

    Pokud chcete exportovat sestavu, když je připojená k sémantickému modelu, jiný než výchozí sémantický model, zadejte v parametru datasetToBind při volání rozhraní API požadované ID datové sady. Přečtěte si další informace o dynamické vazbě.

    Souběžné požadavky

    Rozhraní exportToFile API podporuje omezený počet souběžných požadavků. Maximální počet podporovaných souběžných požadavků je 500 na kapacitu. Pokud se chcete vyhnout překročení limitu a získání chyby Příliš mnoho požadavků (429), distribuujte zatížení v průběhu času nebo napříč kapacitami. Současně se zpracovává pouze pět stránek sestavy. Pokud například exportujete sestavu s 50 stránkami, úloha exportu se zpracuje v 10 sekvenčních intervalech. Při optimalizaci úlohy exportu můžete zvážit paralelní spuštění několika úloh.

    Příklady kódu

    Při vytváření úlohy exportu je potřeba provést čtyři kroky:

    1. Odeslání žádosti o export
    2. Dotazování.
    3. Načítá se soubor.
    4. Pomocí datového proudu souboru.

    Tato část obsahuje příklady pro každý krok.

    Krok 1 – odeslání žádosti o export

    Prvním krokem je odeslání žádosti o export. V tomto příkladu se odešle požadavek na export pro konkrétní stránku.

    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 – dotazování

    Po odeslání žádosti o export použijte dotazování k identifikaci, kdy je soubor exportu, na který čekáte, připravený.

    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 – získání souboru

    Jakmile dotazování vrátí adresu URL, použijte tento příklad k získání přijatého souboru.

    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žití streamu souboru

    Když máte datový proud souboru, můžete ho zpracovat tak, jak nejlépe vyhovuje vašim potřebám. Můžete ho například poslat e-mailem nebo ho použít ke stažení exportovaných sestav.

    Kompletní příklad

    Toto je kompletní příklad pro export sestavy. Tento příklad zahrnuje následující fáze:

    1. Odeslání žádosti o export
    2. Dotazování.
    3. Načítá se soubor.
    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;
    }
}

    Úvahy a omezení

    • Načtení operace exportu rozhraní API se vyhodnocuje jako pomalé operace na pozadí, jak je popsáno v vyhodnocení zatížení kapacity Premium.
    • Všechny související sémantické modely v sestavě, kterou exportujete, musí být umístěné v kapacitě Premium nebo Embedded, včetně sémantických modelů s připojením Direct Query.
    • Exportované sestavy nesmí překročit velikost souboru 250 MB.
    • Při exportu do souboru .png se popisky citlivosti nepodporují.
    • Počet exportů (jeden vizuál nebo stránky sestavy), které je možné zahrnout do jedné exportované sestavy, je 50 (nezahrnuje export stránkovaných sestav). Pokud požadavek obsahuje další exporty, rozhraní API vrátí chybu a úloha exportu se zruší.
    • Osobní záložky a trvalé filtry nejsou podporované pro export sestavy Power BI do souboru.
    • Rozhraní exportToFile API exportuje sestavu s výchozí hodnotou, pokud se používá bez záložek nebo reportLevelFilters.
    • Zde uvedené vizuály Power BI nejsou podporované. Při exportu sestavy obsahující tyto vizuály se části sestavy, které tyto vizuály obsahují, nevykreslí a zobrazí symbol chyby.
      • Necertifikované vlastní vizuály Power BI
      • Vizuály jazyka R
      • PowerApps
      • Vizuály Pythonu
      • Power Automate
      • Vizuál stránkované sestavy
      • Visio
      • Vizuály ArcGIS

    Související obsah

    Přečtěte si, jak vložit obsah pro vaše zákazníky a vaši organizaci:

    Další otázky? Vyzkoušejte Komunita Power BI