Export sestavy Power BI do souboru

Článek
11/17/2024

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

.pptx (PowerPoint)
.Pdf
.png
- Při exportu do .png se sestava s více stránkami zkomprimuje do souboru .zip.
- Každý soubor v .zip představuje stránku sestavy.
- Názvy stránek jsou stejné jako návratové hodnoty rozhraní API pro získání stránek nebo získání stránek v rozhraních API skupiny .

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 .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 – Odešlete automatizovaný e-mail v nastavených intervalech 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 .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
Export stránky nebo jednoho vizuálu
Bookmarks
Filtry
Authentication
Zabezpečení na úrovni řádků (RLS)
Ochrana dat
Lokalizace
Dynamická vazba

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	Komentáře
`bookmark`	Volitelné	Slouží k exportu stránky v určitém stavu.
`pageName`		Použijte rozhraní REST API GetPages nebo `getPages` klientské rozhraní API.
`visualName`		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 .

Filtrovat	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 pro sémantický model, ke kterému je sestava připojená
Přispěvatel 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 .pdf nebo .pptx, exportovaný soubor zobrazí sestavu s popiskem citlivosti.

Sestavu s popiskem citlivosti nejde exportovat do .pdf ani do .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:

Odeslání žádosti o export
Dotazování.
Načítá se soubor.
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:

Odeslání žádosti o export
Dotazování.
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 .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.
Export sestavy Power BI, která je připojená k jednomu nebo více sémantickým modelům, který má aspoň jeden externí zdroj dat s povoleným jednotným přihlašováním( SSO), se nepodporuje. Při exportu se vizuály nemusí vykreslit správně.
Při exportu sestavy s dynamickou vazbou pomocí exportToFile rozhraní REST API nemůže být dynamicky vázaný sémantický model složený model s přímým dotazem na Služba Analysis Services serveru SQL (SSAS).
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

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

Sdílet prostřednictvím

Export sestavy Power BI do souboru

Příklady použití

Použití rozhraní API

Požadavky na licenci

Nastavení správce

Události vykreslování

cyklické dotazování

Podporované funkce

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

Export stránky nebo jednoho vizuálu

Záložky

Filtry

Ověřování

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

Ochrana dat

Lokalizace

Dynamická vazba

Souběžné požadavky

Příklady kódu

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

Krok 2 – dotazování

Krok 3 – získání souboru

Krok 4 – Použití streamu souboru

Kompletní příklad

Úvahy a omezení

Váš názor

Další materiály

Sdílet prostřednictvím

Export sestavy Power BI do souboru

Příklady použití

Použití rozhraní API

Požadavky na licenci

Nastavení správce

Události vykreslování

cyklické dotazování

Podporované funkce

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

Export stránky nebo jednoho vizuálu

Záložky

Filtry

Ověřování

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

Ochrana dat

Lokalizace

Dynamická vazba

Souběžné požadavky

Příklady kódu

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

Krok 2 – dotazování

Krok 3 – získání souboru

Krok 4 – Použití streamu souboru

Kompletní příklad

Úvahy a omezení

Související obsah

Váš názor

Další materiály