Paginierte Berichte in Datei exportieren

Artikel
02/06/2025

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

.pptx (PowerPoint)
.pdf (und barrierefreie PDF- oder PDF/UA-Dokumente)
.xlsx (Excel)
.docx (Word)
.csv
.xml
.mhtml
Bild
Legen Sie beim Exportieren in ein Bild das Bildformat über die OutputFormat-Formateinstellung fest. Die unterstützten OutputFormat Werte sind:
- .tiff (Standard)
- .bmp
- .emf
- .gif
- .jpeg
- .png

Verwendungsbeispiele

Sie können das Exportfeature auf verschiedene Weise verwenden. Hier sind ein paar Beispiele:

Schaltfläche "An Druck senden" – Erstellen Sie in Ihrer Anwendung eine Schaltfläche, die beim Klicken auf einen Exportauftrag ausgelöst wird. Der Auftrag kann den angezeigten Bericht als PDF- oder PPTX-Datei exportieren. Nach Abschluss des Vorgangs kann der Benutzer die Datei als Download erhalten. Mithilfe von Berichtsparametern und Formateinstellungen können Sie den Bericht in einem bestimmten Zustand exportieren, einschließlich gefilterter Daten, benutzerdefinierter Seitengrößen und anderer formatspezifischer Einstellungen. Da die API asynchron ist, 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 nützlich sein, wenn Sie das Senden eines wöchentlichen Berichts an Führungskräfte automatisieren möchten.

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 bietet eingeschränkte Unterstützung in Premium-Einzelbenutzerlizenz (PPU).

Ereignisse rendern

Um sicherzustellen, dass der Export nicht beginnt, bevor das visuelle Rendering abgeschlossen ist, verwenden Sie die "Rendering"-Ereignis-API, und beginnen Sie den Export nur, wenn das Rendern abgeschlossen ist.

Abfrage

Die API ist asynchron. Wenn die exportToFile--API 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.

Wenn der Export abgeschlossen ist, liefert der Abfrage-API-Aufruf eine Power BI-URL zum Abrufen der Datei. Die URL ist 24 Stunden verfügbar.

Unterstützte Features

Formateinstellungen

Geben Sie verschiedene Formateinstellungen für jedes Dateiformat an. Die unterstützten Eigenschaften und Werte entsprechen Device Info-Parametern für URL-Parameter des paginierten Berichts.

Hier sind zwei Beispiele. Der erste dient zum Exportieren der ersten vier Seiten eines Berichts mithilfe der Berichtsseitengröße in eine .pptx Datei. Das zweite Beispiel dient zum Exportieren der dritten Seite eines Berichts in eine .jpeg Datei.

Exportieren der ersten vier Seiten in eine PPTX-Datei

{
      "format": "PPTX",
      "paginatedReportConfiguration":{
            "formatSettings":{
                  "UseReportPageSize": "true",
                  "StartPage": "1",
                  "EndPage": "4"
            }
      }
}

Exportieren der dritten Seite in eine .jpeg

{
      "format": "IMAGE",
      "paginatedReportConfiguration":{
            "formatSettings":{
                  "OutputFormat": "JPEG",
                  "StartPage": "3",
                  "EndPage": "3"
            }
      }
}

Berichtsparameter

Sie können die exportToFile-API verwenden, um einen Bericht programmgesteuert mit einer Reihe von Berichtsparametern zu exportieren. Dieser Export erfolgt über die Eigenschaften der Berichtsparameter.

Hier ist ein Beispiel zum Festlegen von Berichtsparameterwerten.

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "parameterValues":[
                  {"name": "State", "value": "WA"},
                  {"name": "City", "value": "Seattle"},
                  {"name": "City", "value": "Bellevue"},
                  {"name": "City", "value": "Redmond"}
            ]
      }
}

Authentifizierung

Die Authentifizierung kann mit einer benutzenden Person (oder einem Hauptbenutzer) oder einem Dienstprinzipal erfolgen.

Sicherheit auf Zeilenebene (Row Level Security, RLS)

Wenn Sie ein Power BI-Semantikmodell als Datenquelle verwenden, bei dem die Zeilenebenensicherheit (Row Level Security, RLS) definiert ist, können Sie einen Bericht exportieren, der nur die Daten anzeigt, die 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 mithilfe von RLS benötigen Sie Leseberechtigungen für das Power BI-Semantikmodell, das der Bericht als Datenquelle verwendet.

Hier ist ein Beispiel für die Bereitstellung eines effektiven Benutzernamens für RLS.

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "identities": [
                  {"username": "john@contoso.com"}
            ]
      }
}

Einmaliges Anmelden (Single Sign-On, SSO) für SQL und Dataverse

In Power BI haben Sie die Möglichkeit, OAuth mit SSO festzulegen. Wenn Sie dies tun, werden die Anmeldeinformationen für den Benutzer, der den Bericht anzeigt, zum Abrufen von Daten verwendet. Das Zugriffstoken im Anforderungsheader wird nicht für den Zugriff auf die Daten verwendet. Das Token muss zusammen mit der effektiven Identität im Post-Text übergeben werden.

Das Abrufen des richtigen Zugriffstokens für die Ressource, auf die Sie zugreifen möchten, kann manchmal schwierig sein.

Für Azure SQL ist die Ressource https://database.windows.net.
Bei Dataverse ist die Ressource die https:// Adresse für Ihre Umgebung. Beispiel: https://contoso.crm.dynamics.com.

Greifen Sie mithilfe der AuthenticationContext.AcquireTokenAsync-Methode auf die Token-API zu.

Hier ist ein Beispiel für die Bereitstellung einer effektiven Identität (Benutzername) mit einem Zugriffstoken.

{
       "format":"PDF",
       "paginatedReportConfiguration":{
          "formatSettings":{
             "AccessiblePDF":"true",
             "PageHeight":"11in",
             "PageWidth":"8.5in",
             "MarginBottom":"2in"
          },
          "identities":[
             {
                "username":"john@contoso.com",
                "identityBlob": {
                "value": "eyJ0eX....full access token"
         }
        }
     ]
   }
}

Gleichzeitige Anforderungen

Die exportToFile unterstützt eine begrenzte Anzahl gleichzeitiger Anforderungen. Die maximale Anzahl gleichzeitiger Anforderungen zum Rendern paginierter Berichte beträgt 500. Um eine Überschreitung des Grenzwerts zu vermeiden und einen Fehler 'Zu viele Anfragen' (429) zu vermeiden, verteilen Sie die Last entweder über die Zeit oder über verschiedene Kapazitäten.

Bei Premium Per User (PPU) erlaubt die exportToFile-API nur eine Anfrage innerhalb eines Fünf-Minuten-Fensters. Mehrere Anforderungen innerhalb des fünfminütigen Fensters führen zu einem Zu viele Anforderungen (429) Fehler.

Codebeispiele

Das in den Codebeispielen verwendete Power BI-API-SDK kann hierheruntergeladen werden.

Wenn Sie einen Exportauftrag erstellen, müssen Sie drei Schritte ausführen:

Senden einer Exportanforderung.
Abfrage.
Abrufen der Datei.

Dieser 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 einen bestimmten Seitenbereich, eine Größe und einen Berichtparameterwert gesendet.

private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId)
{
    // For documentation purposes the export configuration is created in this method
    // Ordinarily, it would be created outside and passed in
    var paginatedReportExportConfiguration = new PaginatedReportExportConfiguration()
    {
        FormatSettings = new Dictionary<string, string>()
        {
            {"PageHeight", "14in"},
            {"PageWidth", "8.5in" },
            {"StartPage", "1"},
            {"EndPage", "4"},
        },
        ParameterValues = new List<ParameterValue>()
        {
            { new ParameterValue() {Name = "State", Value = "WA"} },
            { new ParameterValue() {Name = "City", Value = "Redmond"} },
        },
    };

    var exportRequest = new ExportReportRequest
    {
        Format = FileFormat.PDF,
        PaginatedReportExportConfiguration = paginatedReportExportConfiguration,
    };

    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 – Abfragen

Nachdem Sie eine Exportanforderung gesendet haben, verwenden Sie die Abfrage, um zu ermitteln, wann die Exportdatei, auf die Sie warten, bereit ist.

private async Task<Export> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the ExportToAsync response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations
            return null;
        }

        var httpMessage = 
            await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
            
        exportStatus = httpMessage.Body;
        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 only populated when the status is either Running or NotStarted
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;

            await Task.Delay(retryAfterInSec * secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return exportStatus;
}

Schritt 3 – Abrufen der Datei

Nachdem die Abfrage eine URL zurückgegeben hat, verwenden Sie dieses Beispiel, um die empfangene Datei abzurufen.

private async Task<ExportedFile> GetExportedFile(
    Guid reportId,
    Guid groupId,
    Export export /* Get from the GetExportStatusAsync response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        var httpMessage = 
            await Client.Reports.GetFileOfExportToFileInGroupWithHttpMessagesAsync(groupId, reportId, export.Id);

        return new ExportedFile
        {
            FileStream = httpMessage.Body,
            ReportName = export.ReportName,
            FileExtension = export.ResourceFileExtension,
        };
    }

    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string ReportName;
    public string FileExtension;
}

Vollständiges Beispiel

Dies ist ein End-to-End-Beispiel zum Exportieren eines Berichts. Dieses Beispiel enthält die folgenden Phasen:

Senden der Exportanforderung.
Abrufvorgang
Abrufen der Datei.

private async Task<ExportedFile> ExportPaginatedReport(
    Guid reportId,
    Guid groupId,
    int pollingtimeOutInMinutes,
    CancellationToken token)
{
    try
    {
        var exportId = await PostExportRequest(reportId, groupId);

        var export = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
        if (export == null || export.Status != ExportState.Succeeded)
        {
           // Error, failure in exporting the report
            return null;
        }

        return await GetExportedFile(reportId, groupId, export);
    }
    catch
    {
        // Error handling
        throw;
    }
}

Überlegungen und Einschränkungen

Das Exportieren eines paginierten Berichts mit einem Power BI-Semantikmodell als Datenquelle wird in den folgenden Fällen nicht unterstützt:
- Der Aufrufer ist ein Dienstprinzipalprofil.
- Eine der Datenquellen des Semantikmodells ist mit aktivierter SSO (Single Sign-On) konfiguriert und eine effektive Identität wurde bereitgestellt.
- Das Power BI-Semantikmodell verfügt über DirectQuery zu Azure Analysis Services oder zu einem anderen Power BI-Semantikmodell, und es wurde eine effektive Identität bereitgestellt.
Das Exportieren eines paginierten Berichts mit aktivierter Azure Analysis Services-Datenquelle mit aktiviertem Einmaliges Anmelden (Single Sign-On, SSO) wird in den folgenden Fällen nicht unterstützt:
- Der Aufrufer ist ein Dienstprinzipalprofil.
- Der Anrufer ist ein Hauptbenutzer, und es wurde eine effektive Identität bereitgestellt.
Um einen paginierten Bericht mit einer effektiven Identität zu exportieren, muss der Benutzername ein vorhandener Benutzer aus der Microsoft Entra-ID Ihres Mandanten sein.
Der Export eines Berichts ist auf 60 Minuten begrenzt, was der Lebensdauer des Benutzerzugriffstokens entspricht. Wenn beim Exportieren großer Datenmengen ein Timeoutfehler über die 60-Minuten-Marke liegt, sollten Sie die Datenmenge mithilfe geeigneter Filter reduzieren.
Der URL-Link für die Dateifreigabe (Dateifreigabe/UNC-Pfad) funktioniert nicht beim Exportieren eines veröffentlichten paginierten Berichts online im Power BI-Dienst.

Überprüfen Sie, wie Sie Inhalte für Ihre Kunden und Ihre Organisation einbetten:

Freigeben über

Paginierte Berichte in Datei exportieren

Verwendungsbeispiele

Verwenden der API

Lizenzanforderungen

Ereignisse rendern

Abfrage

Unterstützte Features

Formateinstellungen

Exportieren der ersten vier Seiten in eine PPTX-Datei

Exportieren der dritten Seite in eine .jpeg

Berichtsparameter

Authentifizierung

Sicherheit auf Zeilenebene (Row Level Security, RLS)

Einmaliges Anmelden (Single Sign-On, SSO) für SQL und Dataverse

Gleichzeitige Anforderungen

Codebeispiele

Schritt 1 – Senden einer Exportanforderung

Schritt 2 – Abfragen

Schritt 3 – Abrufen der Datei

Vollständiges Beispiel

Überlegungen und Einschränkungen

Feedback

Zusätzliche Ressourcen

Freigeben über

Paginierte Berichte in Datei exportieren

Verwendungsbeispiele

Verwenden der API

Lizenzanforderungen

Ereignisse rendern

Abfrage

Unterstützte Features

Formateinstellungen

Exportieren der ersten vier Seiten in eine PPTX-Datei

Exportieren der dritten Seite in eine .jpeg

Berichtsparameter

Authentifizierung

Sicherheit auf Zeilenebene (Row Level Security, RLS)

Einmaliges Anmelden (Single Sign-On, SSO) für SQL und Dataverse

Gleichzeitige Anforderungen

Codebeispiele

Schritt 1 – Senden einer Exportanforderung

Schritt 2 – Abfragen

Schritt 3 – Abrufen der Datei

Vollständiges Beispiel

Überlegungen und Einschränkungen

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen