Exportieren eines Power BI-Berichts in eine Datei

Die API exportToFile ermöglicht das Exportieren eines Power BI-Berichts mithilfe eines REST-Aufrufs. Die folgenden Dateiformate werden unterstützt:

• .pptx (PowerPoint)
• .pdf
• .png
  • Beim Exportieren in eine PNG-Datei wird ein Bericht mit mehreren Seiten in eine ZIP-Datei komprimiert.
  • Jede Datei in der ZIP-Datei repräsentiert eine Berichtsseite.
  • Die Seitennamen entsprechen den Rückgabewerten der APIs Seiten abrufen bzw. Seiten in Gruppe abrufen.

Anwendungsbeispiele

Sie können das Exportfeature auf unterschiedliche Weise verwenden. Hier sind einige Beispiele angegeben:

• Schaltfläche zum Drucken: Erstellen Sie eine Schaltfläche in Ihrer Anwendung, die einen Exportauftrag auslöst, wenn darauf geklickt wird. Der Auftrag kann den angezeigten Bericht als PDF- oder PPTX-Datei exportieren. Wenn er abgeschlossen ist, kann der Benutzer die Datei als Download abrufen. Mithilfe von Lesezeichen lässt sich der Bericht in einem bestimmten Zustand exportieren, einschließlich konfigurierter Filter, Slicer und weiterer Einstellungen. Da die API asynchron ausgeführt wird, kann es einige Zeit dauern, bis die Datei verfügbar ist.

• E-Mail-Anlage: Hiermit können E-Mails mit angefügtem Bericht im PDF-Format in festgelegten Intervallen gesendet werden. Dieses Szenario kann hilfreich sein, wenn Sie das Senden wöchentlicher Berichte an Vorgesetzte automatisieren möchten. Weitere Informationen finden Sie unter Exportieren und Senden eines Power BI-Berichts per E-Mail mit Power Automate.

Verwenden der API

Lizenzanforderungen

• Der Bericht, den Sie exportieren, muss sich in einem Arbeitsbereich befinden, der von einer Premium-, Embedded- oder Fabric-Kapazität unterstützt wird.
• Die exportToFile-API wird für Premium-Einzelbenutzerlizenz (PPU) nicht unterstützt.

Administratoreinstellungen

Bevor Sie die API verwenden, vergewissern Sie sich, dass die folgenden Mandanteneinstellungen für den Administrator aktiviert sind:

• Berichte als PowerPoint-Präsentationen oder PDF-Dokumente exportieren: standardmäßig aktiviert.
• Berichte als Bilddateien exportieren: Diese Einstellung ist nur für das PNG-Format erforderlich und standardmäßig deaktiviert.

Rendern von Ereignissen

Um sicherzustellen, dass der Export nicht beginnt, bevor das Rendern des Visuals abgeschlossen ist, verwenden Sie die Ereignis-API „Rendering“, und beginnen Sie nur mit dem Exportieren, wenn das Rendern abgeschlossen ist.

Abruf

Die API wird asynchron ausgeführt. Wenn die API exportToFile aufgerufen wird, löst sie einen Exportauftrag aus. Verwenden Sie nach dem Auslösen des Exportauftrags einen Abrufvorgang, um den Auftrag bis zum Abschluss nachzuverfolgen.

Während des Abrufvorgangs gibt die API eine Zahl zurück, die den Umfang an abgeschlossenen Aufgaben darstellt. Die Arbeit für jedem Exportauftrag wird basierend auf der Gesamtanzahl der im Auftrag enthaltenen Exporte berechnet. Ein Export umfasst das Exportieren eines einzelnen Visuals oder einer Seite mit oder ohne Lesezeichen. Alle Exporte haben dieselbe Gewichtung. Wenn Ihr Exportauftrag beispielsweise das Exportieren eines Berichts mit 10 Seiten umfasst und die Abfrage 70 Seiten zurückgibt, bedeutet dies, dass die API sieben der 10 Seiten des Exportauftrags verarbeitet hat.

Wenn der Export abgeschlossen ist, gibt der API-Aufruf für den Abrufvorgang eine Power BI-URL zurück, unter der die Datei heruntergeladen werden kann. Die URL ist 24 Stunden lang verfügbar.

Unterstützte Features

In diesem Abschnitt wird die Verwendung der folgenden unterstützten Features beschrieben:

• Auswählen der zu druckenden Seiten
• Exportieren einer Seite oder eines einzelnen Visuals
• Bookmarks
• Filter
• Authentifizierung
• Sicherheit auf Zeilenebene
• Datenschutz
• Lokalisierung
• Dynamische Bindung

Auswählen der zu druckenden Seiten

Geben Sie anhand des Rückgabewerts von Seiten abrufen oder Seiten in Gruppe abrufen an, welche Seiten gedruckt werden sollen. Sie können auch die Reihenfolge der Seiten angeben, die Sie exportieren möchten.

Exportieren einer Seite oder eines einzelnen Visuals

Sie können eine Seite oder ein einzelnes Visual angeben, das exportiert werden soll. Seiten können mit oder ohne Lesezeichen exportiert werden.

Je nach Exporttyp müssen Sie unterschiedliche Attribute an das Objekt ExportReportPage übergeben. In der folgenden Tabelle ist angegeben, welche Attribute für jeden Exportauftrag erforderlich sind.

Attribut	Seite	Einzelnes Visual	Kommentare
bookmark	Optional		Für die Verwendung für den Export einer Seite in einem bestimmten Zustand geeignet
pageName			Verwenden Sie die REST-API GetPages oder die getPagesClient-API .
visualName			Es gibt zwei Möglichkeiten, den Namen des Visuals abzurufen: Verwenden Sie die getVisualsClient-API. Überwachen und protokollieren Sie das Ereignis visualClicked, das ausgelöst wird, wenn ein Visual ausgewählt wird. Weitere Informationen finden Sie unter Verarbeiten von Ereignissen. .

Lesezeichen

Mithilfe von Lesezeichen können Sie einen Bericht in einer bestimmten Konfiguration speichern. Dies schließt auch die angewandten Filter und den Zustand der Berichtsvisuals ein. Für das programmgesteuerte Exportieren der Lesezeichen eines Berichts können Sie die exportToFile-API auf zwei Arten verwenden:

• Exportieren eines vorhandenen Lesezeichens

  Zum Exportieren eines vorhandenen Berichtslesezeichens verwenden Sie die name-Eigenschaft, einen eindeutigen Bezeichner (unter Berücksichtigung der Groß-/Kleinschreibung), den Sie mithilfe der JavaScript-API für Lesezeichen abrufen können.

• Exportieren des Berichtszustands

  Um den aktuellen Zustand des Berichts zu exportieren, verwenden Sie die state-Eigenschaft. Sie können z. B. die bookmarksManager.capture-Methode eines Lesezeichens verwenden, um die Änderungen zu erfassen, die ein bestimmter Benutzer an einem Bericht vorgenommen hat, und den Bericht dann mit capturedBookmark.state im aktuellen Zustand zu exportieren.

Filter

Unter Verwendung von reportLevelFilters in PowerBIReportExportConfiguration können Sie einen Bericht in einer gefilterten Bedingung exportieren.

Um einen gefilterten Bericht zu exportieren, fügen Sie die Parameter der URL-Abfragezeichenfolge, die Sie als Filter verwenden möchten, in ExportFilter ein. Wenn Sie die Zeichenfolge eingeben, müssen Sie den Teil ?filter= des URL-Abfrageparameters entfernen.

Die Tabelle enthält einige Syntaxbeispiele für Zeichenfolgen, die Sie an ExportFilter übergeben können.

Authentifizierung

Die Authentifizierung kann mit einem Benutzer (oder einem Hauptbenutzer) oder einem Dienstprinzipal erfolgen.

Sicherheit auf Zeilenebene

Mit Sicherheit auf Zeilenebene (Row-Level Security, RLS) können Sie einen Bericht mit Daten exportieren, die nur für bestimmte Benutzer sichtbar sind. Wenn Sie z. B. einen mit regionalen Rollen definierten Umsatzbericht exportieren, können Sie den Bericht programmatisch filtern, so dass nur eine bestimmte Region angezeigt wird.

Zum Exportieren mit RLS benötigen Sie die folgenden Berechtigungen:

• Schreibberechtigungen für das semantische Modell, mit dem der Bericht verbunden ist
• Mitwirkender oder Administrator des Arbeitsbereichs, in dem sich der Bericht befindet

Datenschutz

Die Formate PDF und PPTX unterstützen Vertraulichkeitsbezeichnungen. Wenn Sie einen Bericht mit einer Sensibilitätskennzeichnung in eine .pdf- oder .pptx-Datei exportieren, zeigt die exportierte Datei den Bericht mit der Sensibilitätskennzeichnung an.

Ein Bericht mit einer Vertraulichkeitsbezeichnung kann nicht mithilfe eines Dienstprinzipals in eine PDF- oder PPTX-Datei exportiert werden.

Lokalisierung

Wenn Sie die exportToFile-API verwenden, können Sie Ihr gewünschtes Gebietsschema übergeben. Die Lokalisierungseinstellungen wirken sich auf die Anzeige des Berichts aus. Beispielsweise ändert sich die Formatierung basierend auf dem ausgewählten Gebietsschema.

Dynamische Bindung

Wenn Sie einen Bericht exportieren möchten, während er mit einem anderen semantischen Modell als dem standardmäßigen semantischen Modell verbunden ist, geben Sie beim Aufrufen der API die datasetToBind erforderliche Dataset-ID im Parameter an. Weitere Informationen zur dynamischen Bindung finden Sie hier.

Gleichzeitige Anforderungen

Die exportToFile-API unterstützt eine begrenzte Anzahl gleichzeitiger Anforderungen. Die maximal zulässige Anzahl gleichzeitiger Anforderungen beträgt 500 pro Kapazität. Um zu verhindern, dass der Grenzwert überschritten und der Fehler Zu viele Anforderungen (429) auftritt, versuchen Sie, die Last entweder über die Zeit oder die Kapazitäten zu verteilen. Nur fünf Seiten eines Berichts werden gleichzeitig verarbeitet. Wenn Sie beispielsweise einen Bericht mit 50 Seiten exportieren, wird der Exportauftrag in 10 aufeinander folgenden Intervallen verarbeitet. Beim Optimieren Ihres Exportauftrags kann es sinnvoll sein, die parallele Ausführung einiger Aufträge in Erwägung zu ziehen.

Codebeispiele

Beim Erstellen eines Exportauftrags müssen vier Schritte ausgeführt werden:

1. Senden einer Exportanforderung
2. Abrufvorgang
3. Herunterladen der Datei
4. Verwenden des Dateidatenstreams

Der folgende Abschnitt enthält Beispiele für jeden Schritt.

Schritt 1: Senden einer Exportanforderung

Der erste Schritt besteht darin, eine Exportanforderung zu senden. In diesem Beispiel wird eine Exportanforderung für eine bestimmte Seite gesendet.

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

Schritt 2: Abrufvorgang

Nachdem Sie eine Exportanforderung gesendet haben, können Sie mithilfe der Abfrage feststellen, wann die erwartete Exportdatei fertig ist.

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

Schritt 3: Herunterladen der Datei

Sobald der Abrufvorgang eine URL zurückgibt, verwenden Sie dieses Beispiel, um die empfangene Datei herunterzuladen.

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

Schritt 4: Verwenden des Dateistreams

Wenn Sie über den Dateistream verfügen, können Sie ihn Ihren Anforderungen entsprechend verarbeiten. Beispielsweise können Sie ihn per E-Mail senden oder zum Herunterladen der exportierten Berichte verwenden.

Vollständiges Beispiel

Hier finden Sie ein vollständiges Beispiel für den Export eines Berichts. Das Beispiel umfasst die folgenden Phasen:

1. Senden einer Exportanforderung
2. Abrufvorgang
3. Herunterladen der Datei

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

Überlegungen und Einschränkungen

• Die Belastung eines Export-API-Vorgangs wird als langsam laufender Hintergrundvorgang bewertet, wie in der Auswertung der Premium-Kapazitätsbelastung beschrieben.
• Alle zugehörigen Datasets im Bericht, den Sie exportieren, müssen sich in einer Premium- oder Embedded-Kapazität befinden, einschließlich semantische Modelle mit einer direkten Abfrageverbindung.
• Exportierte Berichte dürfen eine Dateigröße von 250 MB nicht überschreiten.
• Beim Exportieren in das PNG-Format werden Vertraulichkeitsbezeichnungen nicht unterstützt.
• Es können 50 Exporte (einzelne viseulle Elemente oder Berichtsseiten) in einem exportierten Bericht enthalten sein. Dies schließt nicht das Exportieren von paginierten Berichten ein. Wenn die Anforderung mehr Exporte umfasst, gibt die API einen Fehler zurück, und der Exportauftrag wird abgebrochen.
• Persönliche Lesezeichen und permanente Filter werden für den Power BI-Berichtsexport in die Datei nicht unterstützt.
• Die exportToFile API exportiert den Bericht mit dem Standardwert, wenn er ohne Textmarke oder reportLevelFilter verwendet wird.
• Das Exportieren eines Power BI-Berichts, der mit einem oder mehreren zusammengesetzten semantischen Modell verbunden ist, das mindestens eine externe Datenquelle mit aktiviertem Einmaliges Anmelden (Single Sign-On, SSO) aufweist, wird nicht unterstützt. Beim Exportieren werden visuelle Elemente möglicherweise nicht ordnungsgemäß gerendert.
• Die hier aufgeführten Power BI-Visualisierungen werden nicht unterstützt. Wenn Sie einen Bericht exportieren, der dieses Bildmaterial enthält, werden die Teile des Berichts, die dieses Bildmaterial enthalten, nicht gerendert und ein Fehlersymbol angezeigt.
  • Nicht zertifizierte benutzerdefinierte Power BI-Visuals
  • R-Visuals
  • PowerApps
  • Python-Visuals
  • Power Automate
  • Visual für paginierten Bericht
  • Visio
  • Visuelle ArcGIS-Elemente

Zugehöriger Inhalt

Sehen Sie sich an, wie Sie Inhalte für Ihre Kunden und Ihre Organisation einbetten:

• Exportieren des paginierten Berichts in eine Datei
• Inhalte für Ihre Kunden einbetten
• Embed for your organization (Einbetten für Ihre Organisation)
• Exportieren und Senden eines Power BI-Berichts per E-Mail mit Power Automate

Weitere Fragen? Wenden Sie sich an die Power BI-Community.