Exportieren Power BI Berichts in die 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
    • Wenn Sie in eine .png exportieren, 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.

Wichtig

Die exporttofile API ist nur für Gen2-Kapazitäten verfügbar. Wenn Sie eine Gen1-Kapazität verwenden, aktualisieren Sie auf Gen2

Anwendungsbeispiele

Sie können das Exportfeature auf verschiedene Arten 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 einen .pptx exportieren. Wenn dies abgeschlossen ist, kann der Benutzer die Datei als Download erhalten. Mithilfe von Textmarken können Sie den Bericht in einem bestimmten Zustand exportieren, einschließlich konfigurierter Filter, Datenschnitten und anderen 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 mit Power Automate

Verwenden der API

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.

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 z. B. das Exportieren eines Berichts mit 10 Seiten umfasst und die Umfrage 70 zurückgibt, bedeutet dies, dass die API sieben aus den 10 Seiten im Exportauftrag 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

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 die einzelnen Exportaufträge erforderlich sind.

Hinweis

Der Export eines einzelnen Visuals wird genauso wie der Export einer Seite (mit oder ohne Lesezeichen) gewichtet. Das bedeutet, dass beide Vorgänge im Hinblick auf Systemberechnungen denselben Wert aufweisen.

Attribut Seite Einzelnes Visual Kommentare
bookmark Optional Does not apply to. Für die Verwendung für den Export einer Seite in einem bestimmten Zustand geeignet
pageName Applies to. Applies to. Verwenden Sie die REST-API GetPages oder die Client-API getPages. Weitere Informationen finden Sie unter Abrufen von Seiten und Visuals.
visualName Does not apply to. Applies to. Es gibt zwei Möglichkeiten, den Namen des Visuals abzurufen:
  • Verwenden Sie die Client-API getVisuals. Weitere Informationen finden Sie unter Abrufen von Seiten und Visuals.
  • Ü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

      Um eine vorhandene Berichtsmarke zu exportieren, verwenden Sie die Eigenschaft, einen eindeutigen (Groß-/Kleinschreibungs-)Bezeichner, den Sie mithilfe der nameJavaScript-API für Textmarken 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.

    Hinweis

    Persönliche Lesezeichen und permanente Filter werden nicht unterstützt.

    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 folgende Tabelle enthält einige Syntaxbeispiele für Zeichenfolgen, die Sie an ExportFilter übergeben können.

    Filter Syntax Beispiel
    Ein Wert in einem Feld Table/Field eq 'value' Store/Territory eq 'NC'
    Mehrere Werte in einem Feld Table/Field in ('value1', 'value2') Store/Territory in ('NC', 'TN')
    Ein eindeutiger Wert in einem Feld und ein anderer eindeutiger Wert in einem anderen Feld Table/Field1 eq 'value1' und Table/Field2 eq 'value2' Store/Territory eq 'NC' und Store/Chain eq 'Fashions Direct'

    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 beispielsweise einen Umsatzbericht exportieren, der mit regionalen Rollen definiert ist, können Sie den Bericht programmgesteuert filtern, sodass nur eine bestimmte Region angezeigt wird.

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

    • Berechtigungen zum Schreiben und erneuten Freigeben für das Dataset, mit dem der Bericht verknüpft ist.
    • Wenn sich der Bericht in einem Arbeitsbereich der Version 1 befindet, müssen Sie Administrator des Arbeitsbereichs sein.
    • Wenn sich der Bericht in einem Arbeitsbereich der Version 2 befindet, müssen Sie Mitglied oder Administrator des Arbeitsbereichs sein.

    Datenschutz

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

    Ein Bericht mit einer Vertraulichkeitsbezeichnung kann nicht in ein .pdf oder einen .pptx mit einem Dienstprinzipal 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.

    Gleichzeitige Anforderungen

    exportToFile unterstützt gleichzeitige Anforderungen für Exportaufträge. Die folgende Tabelle zeigt die Anzahl von Aufträgen, die Sie gleichzeitig ausführen können – je nach SKU, in der sich Ihr Bericht befindet. Gleichzeitige Anforderungen beziehen sich auf Berichtsseiten. Beispielsweise werden 55 Seiten in einer Exportanforderung für eine A4-SKU gleichzeitig verarbeitet. Dieser Prozess dauert ungefähr dieselbe Zeit wie das Senden von 55 Exportanforderungen mit einer Seite.

    Ein Auftrag, bei dem die Anzahl gleichzeitiger Anforderungen überschritten ist, wird nicht abgeschlossen. Wenn Sie beispielsweise 30 Seiten in einer A2-SKU exportieren, werden die ersten 25 Aufträge ausgeführt, und die restlichen fünf warten auf den nächsten Ausführungszyklus.

    Nur fünf Seiten eines Berichts werden gleichzeitig verarbeitet. Wenn Sie beispielsweise einen Bericht mit 50 Seiten exportieren, wird der Exportauftrag in 10 sequenziellen Intervallen verarbeitet. Wenn Sie Ihren Exportauftrag optimieren, sollten Sie möglicherweise einige Aufträge parallel ausführen. Wenn Sie beispielsweise über eine A1-SKU mit einer Begrenzung der Verarbeitung von 20 max. gleichzeitigen Seiten pro Export verfügen, können Sie vier 50 Seitenberichte gleichzeitig verarbeiten. Nur fünf Seiten von jedem Auftrag werden zu einem bestimmten Zeitpunkt verarbeitet. Daher ist die Gesamtzeit, um die vier Aufträge abzuschließen, kürzer als der gesamte Bericht in einem Auftrag zu exportieren.

    Hinweis

    Das Exportieren eines Power BI-Berichts in eine Datei mit der exportToFile-API wird im Zusammenhang mit der Premium-Einzelbenutzerlizenz (PPU) nicht unterstützt.

    Azure-SKU Office-SKU Maximale Anzahl von gleichzeitigen Berichtsseiten
    A1 EM1 20
    A2 EM2 25
    A3 EM3 35
    A4 P1 55
    A5 P2 95
    A6 P3 175
    A71 P41 200
    A81 P51 200

    1 SKUs größer als 100 GB sind in allen Regionen nicht verfügbar. Wenden Sie sich an Ihre*n Microsoft-Account Manager, um die Verwendung dieser SKUs in Regionen anzufordern, in denen sie nicht verfügbar sind.

    Codebeispiele

    Wenn Sie einen Exportauftrag erstellen, sind vier Schritte erforderlich:

    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 die Exportanforderung gesendet haben, verwenden Sie einen Abrufvorgang, um zu ermitteln, wann die Datei bereit sein wird.

    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 exporttofile API ist nur für Gen2-Kapazitäten verfügbar. Wenn Sie eine Gen1-Kapazität verwenden, aktualisieren Sie das Upgrade auf Gen2.
    • Eine Export-API-Vorgangslast wird als langsam ausgeführter Hintergrundvorgang bewertet, wie in der Auswertung der Kapazitätsauslastung in Premium Gen2 beschrieben.
    • Der Bericht, den Sie exportieren möchten, muss sich in Premium- oder Embedded-Kapazität befinden.
    • Das Dataset des Berichts, den Sie exportieren möchten, muss sich in Premium- oder Embedded-Kapazität befinden.
    • Exportierte Berichte können eine Dateigröße von 250 MB nicht überschreiten.
    • Beim Exportieren in .png werden Vertraulichkeitsbezeichnungen nicht unterstützt.
    • Die Anzahl der Exporte (einzelne visuelle oder Berichtsseiten), die in einem exportierten Bericht enthalten sein können, beträgt 50 (nicht einschließlich exportierender Paginated-Berichte). Wenn die Anforderung mehr Exporte umfasst, gibt die API einen Fehler zurück, und der Exportauftrag wird abgebrochen.
    • Persönliche Lesezeichen und beständige Filter werden nicht unterstützt.
    • Dynamische Datasetbindung wird nicht unterstützt.
    • Das Exportieren eines Power BI Berichts in die Datei mithilfe der exportToFile API wird für Premium Pro Benutzer (PPU) nicht unterstützt.
    • Die unten aufgeführten Power BI Visuellen werden nicht unterstützt. Wenn Sie einen Bericht exportieren, der diese Visuellen enthält, werden die Teile des Berichts, die diese Visuellen enthalten, nicht gerendert und ein Fehlersymbol angezeigt.
      • Nicht zertifiziert Power BI benutzerdefinierte Visuellen
      • R-Visuals
      • PowerApps
      • Python-Visuals
      • Power Automate
      • Visual für paginierten Bericht
      • Visio

    Nächste Schritte

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