Exportieren de paginierten Berichts in eine Datei

  • Artikel

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

  • .pptx (PowerPoint)

  • PDF (und PDF-Datei mit Barrierefreiheit oder PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .csv

  • .xml

  • .mhtml

  • Bild
    Legen Sie beim Exportieren eines Bilds das Bildformat über die OutputFormat-Formateinstellung fest. Die unterstützten Werte für OutputFormat sind:

    • .tiff (Standard)
    • .bmp
    • .emf
    • .gif
    • .jpeg
    • .png

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. Mit Berichtsparametern und Formateinstellungen können Sie den Bericht in einem bestimmten Zustand exportieren, einschließlich gefilterter Daten, benutzerdefinierter Seitengrößen und weiteren formatspezifischen 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.

Verwenden der API

Lizenzanforderungen

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.

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

Formateinstellungen

Geben Sie verschiedene Formateinstellungen für jedes Dateiformat an. Die unterstützten Eigenschaften und Werte entsprechen den Parametern für Geräteinformationen für Parameter für paginierte Berichts-URLs.

Hier sind zwei Beispiele angegeben. Das erste dient zum Exportieren der ersten vier Seiten eines Berichts mithilfe der Berichtsseitengröße in eine PPTX-Datei. Das zweite Beispiel zeigt das 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-Datei

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

Berichtsparameter

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

Hier sehen Sie ein Beispiel zum Festlegen der Berichtsparameterwerte.

{
      "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 einem Benutzer (oder einem Hauptbenutzer) oder einem Dienstprinzipal erfolgen.

Sicherheit auf Zeilenebene

Wenn Sie ein Power BI-semantisches Modell verwenden, für das als Datenquelle die Sicherheit auf Zeilenebene (Row Level Security, RLS) definiert ist, können Sie einen Bericht exportieren, der Daten darstellt, 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 müssen Sie über Leseberechtigungen für das Power BI-semantisches Modell verfügen, das der Bericht als Datenquelle verwendet.

Nachstehend sehen Sie 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 Option, OAuth mit SSO festzulegen. Wenn Sie diese Option festlegen, werden die Anmeldeinformationen des Benutzers, der einen 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 lautet die Ressource https://database.windows.net.
  • Für Dataverse ist die Ressource die https://-Adresse für Ihre Umgebung. Beispiel: https://contoso.crm.dynamics.com.

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

Nachstehend sehen Sie ein Beispiel für die Angabe einer effektiven Identität (Benutzername) bei 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

exportToFile unterstützt eine begrenzte Anzahl gleichzeitiger Anforderungen. Die maximale Anzahl gleichzeitiger Anforderungen zum Rendern paginierter Berichte beträgt 500. 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.

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 Zeitfensters führen zum Fehler Zu viele Anforderungen (429).

Codebeispiele

Das SDK der Power BI-API, das in den Codebeispielen verwendet wird, kann hier heruntergeladen werden.

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

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

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 einen bestimmten Seitenbereich, eine bestimmte Seitengröße sowie für Berichtsparameter 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: Abrufvorgang

Nachdem Sie die Exportanforderung gesendet haben, verwenden Sie einen Abrufvorgang, um zu ermitteln, wann die Datei bereit sein wird.

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: 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 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

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> 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-semantisches Modell als Datenquelle wird in den folgenden Fällen nicht unterstützt:

    • Der Aufrufer ist ein Dienstprinzipalprofil.
    • Eine der Datenquellen des semantischen Modells wird mit aktivierter SSO (Single Sign-On) konfiguriert, und eine effektive Identität wurde bereitgestellt.
    • Das Power BI-semantische Modell verfügt über eine DirectQuery-Verbindung mit Azure Analysis Services oder zu einem anderen Power BI-semantischen Modell, und eine effektive Identität wurde bereitgestellt.

  • Das Exportieren eines paginierten Berichts, in dem eine Azure Analysis Services-Datenquelle mit aktiviertem einmaligem Anmelden (Single Sign-On, SSO) konfiguriert ist, wird in den folgenden Fällen nicht unterstützt:

    • Der Aufrufer ist ein Dienstprinzipalprofil.
    • Der Aufrufer ist ein/eine Hauptbenutzer*in, und eine effektive Identität wurde bereitgestellt.

  • Um einen paginierten Bericht mit einer effektiven Identität zu exportieren, muss der Benutzername als Benutzer*in in Microsoft Entra ID Ihres Mandanten vorhanden sein.

  • Der Export eines Berichts ist auf 60 Minuten begrenzt, was der Lebensdauer des Benutzerzugriffstokens entspricht. Bei einem Timeoutfehler nach der 60. Minute beim Exportieren großer Datenmengen sollten Sie erwägen, die Daten mit geeigneten Filtern zu minimieren.

  • Der URL-Link für die Dateifreigabe (Dateifreigabe/UNC-Pfad) funktioniert nicht beim Exportieren eines veröffentlichten paginierten Berichts online im Power BI-Dienst.

Zugehöriger Inhalt

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