Gepagineerd rapport exporteren naar bestand

  • Artikel

Met de exportToFile API kunt u een gepagineerd Power BI-rapport exporteren met behulp van een REST-aanroep. De volgende bestandsindelingen worden ondersteund:

  • .pptx (PowerPoint)

  • .pdf (en toegankelijke PDF of PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .Csv

  • .Xml

  • .Mhtml

  • Installatiekopie
    Wanneer u naar een afbeelding exporteert, stelt u de afbeeldingsindeling in via de OutputFormat indelingsinstelling. De ondersteunde OutputFormat waarden zijn:

    • .tiff (standaard)
    • .Bmp
    • .Emf
    • .gif
    • .jpeg
    • .png

Voorbeelden van gebruik

U kunt de exportfunctie op verschillende manieren gebruiken. Hier volgen enkele voorbeelden:

  • Knop Verzenden naar afdrukken - Maak in uw toepassing een knop waarop een exporttaak wordt geactiveerd wanneer erop wordt geklikt. De taak kan het weergegeven rapport exporteren als een PDF- of .pptx. Wanneer het is voltooid, kan de gebruiker het bestand ontvangen als een download. Met behulp van rapportparameters en opmaakinstellingen kunt u het rapport in een specifieke status exporteren, waaronder gefilterde gegevens, aangepaste paginaformaten en andere indelingsspecifieke instellingen. Omdat de API niet synchroon werkt, kan het enige tijd duren voordat het bestand beschikbaar is.

  • E-mailbijlage - Verzend een geautomatiseerd e-mailbericht met ingestelde intervallen, met een bijgevoegd PDF-rapport. Dit scenario kan handig zijn als u het verzenden van een wekelijks rapport naar leidinggevenden wilt automatiseren.

De API gebruiken

Licentievereisten

Rendering-gebeurtenissen

Als u ervoor wilt zorgen dat de export niet begint voordat de weergave van de visual is voltooid, gebruikt u de GEBEURTENIS-API 'Rendering' en begint u alleen met de export wanneer de rendering is voltooid.

Navragen

De API is asynchroon. Wanneer de exportToFile-API wordt aangeroepen, wordt er een exporttaak geactiveerd. Nadat u een exporttaak hebt geactiveerd, gebruikt u polling om de taak bij te houden totdat deze is voltooid.

Wanneer het exporteren is voltooid, retourneert de polling-API-aanroep een Power BI-URL voor het ophalen van het bestand. De URL is 24 uur beschikbaar.

Ondersteunde functies

Opmaakinstellingen

Geef verschillende indelingsinstellingen op voor elke bestandsindeling. De ondersteunde eigenschappen en waarden zijn gelijk aan parameters voor apparaatgegevens voor gepagineerde rapport-URL-parameters.

Hier volgen twee voorbeelden. De eerste is voor het exporteren van de eerste vier pagina's van een rapport met behulp van het rapportpaginaformaat naar een PPTX-bestand. Het tweede voorbeeld is voor het exporteren van de derde pagina van een rapport naar een JPEG-bestand.

De eerste vier pagina's exporteren naar een .pptx

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

De derde pagina exporteren naar een .jpeg

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

Rapportparameters

U kunt de exportToFile API gebruiken om programmatisch een rapport te exporteren met een set rapportparameters. Dit wordt gedaan met behulp van rapportparametermogelijkheden .

Hier volgt een voorbeeld voor het instellen van rapportparameterwaarden.

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

Verificatie

U kunt zich verifiëren met behulp van een gebruiker (of hoofdgebruiker) of een service-principal.

Beveiliging op rijniveau (RLS)

Wanneer u een semantisch Power BI-model gebruikt waarvoor beveiliging op rijniveau (RLS) is gedefinieerd als gegevensbron, kunt u een rapport exporteren met gegevens die alleen zichtbaar zijn voor bepaalde gebruikers. Als u bijvoorbeeld een verkooprapport exporteert dat is gedefinieerd met regionale rollen, kunt u het rapport programmatisch filteren zodat alleen een bepaalde regio wordt weergegeven.

Als u wilt exporteren met behulp van RLS, moet u beschikken over leesmachtigingen voor het semantische Power BI-model dat het rapport gebruikt als gegevensbron.

Hier volgt een voorbeeld van het opgeven van een effectieve gebruikersnaam voor beveiliging op rijniveau.

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

Eenmalige aanmelding voor SQL en Dataverse (SSO)

In Power BI hebt u de mogelijkheid om OAuth in te stellen met eenmalige aanmelding. Wanneer u dit doet, worden de referenties voor de gebruiker die het rapport bekijkt, gebruikt om gegevens op te halen. Het toegangstoken in de aanvraagheader wordt niet gebruikt voor toegang tot de gegevens. Het token moet worden doorgegeven met de effectieve identiteit in de hoofdtekst van het bericht.

Het ophalen van het juiste toegangstoken voor de resource waartoe u toegang wilt, kan soms lastig zijn.

  • Voor Azure SQL is https://database.windows.netde resource .
  • Voor Dataverse is de resource het https:// adres voor uw omgeving. Bijvoorbeeld: https://contoso.crm.dynamics.com.

Open de token-API met behulp van de methode AuthenticationContext.AcquireTokenAsync .

Hier volgt een voorbeeld voor het opgeven van een effectieve identiteit (gebruikersnaam) met een toegangstoken.

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

Gelijktijdige aanvragen

Het exportToFile ondersteunt een beperkt aantal gelijktijdige aanvragen. Het maximum aantal gelijktijdige gepagineerde rapportweergaveaanvragen is 500. Om te voorkomen dat de limiet wordt overschreden en een fout te veel aanvragen (429) krijgt, distribueert u de belasting over een bepaalde periode of over capaciteiten.

Met PPU (Premium Per User) staat de exportToFile API slechts één aanvraag toe in een venster van vijf minuten. Meerdere aanvragen binnen het venster van vijf minuten resulteren in een fout te veel aanvragen (429).

Codevoorbeelden

De API van Power BI SDK die in de codevoorbeelden wordt gebruikt, kan hier worden gedownload.

Wanneer u een exporttaak maakt, moet u drie stappen uitvoeren:

  1. Een exportaanvraag verzenden.
  2. Polling.
  3. Het bestand wordt opgeslagen.

Deze sectie bevat voorbeelden voor elke stap.

Stap 1: een exportaanvraag verzenden

De eerste stap is het verzenden van een exportaanvraag. In dit voorbeeld wordt een exportaanvraag verzonden voor een specifiek paginabereik, grootte en rapportparameterwaarden.

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

Stap 2: polling

Nadat u een exportaanvraag hebt verzonden, gebruikt u polling om te bepalen wanneer het exportbestand dat u wacht, gereed is.

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

Stap 3: het bestand downloaden

Zodra polling een URL retourneert, gebruikt u dit voorbeeld om het ontvangen bestand op te halen.

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

End-to-end-voorbeeld

Dit is een end-to-end voorbeeld voor het exporteren van een rapport. Dit voorbeeld bevat de volgende fasen:

  1. De exportaanvraag verzenden.
  2. Polling.
  3. Het bestand wordt opgeslagen.
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;
    }
}

Overwegingen en beperkingen

  • Het exporteren van een gepagineerd rapport met een semantisch Power BI-model als gegevensbron wordt in de volgende gevallen niet ondersteund:

    • De aanroeper is een service-principalprofiel.
    • Een van de gegevensbronnen van het semantische model is geconfigureerd met eenmalige aanmelding (SSO) ingeschakeld en er is een effectieve identiteit opgegeven.
    • Het semantische Power BI-model heeft DirectQuery naar Azure Analysis Services of naar een ander semantisch Power BI-model en er is een effectieve identiteit opgegeven.

  • Het exporteren van een gepagineerd rapport waarvoor Azure Analysis Services-gegevensbron is geconfigureerd met eenmalige aanmelding (SSO) wordt niet ondersteund in de volgende gevallen:

    • De aanroeper is een service-principalprofiel.
    • De beller is een hoofdgebruiker en er is een effectieve identiteit opgegeven.

  • Als u een gepagineerd rapport met een effectieve identiteit wilt exporteren, moet de gebruikersnaam een bestaande gebruiker zijn uit de Microsoft Entra-id van uw tenant.

  • Het exporteren van een rapport is beperkt tot 60 minuten, wat overeenkomt met de levensduur van het toegangstoken van de gebruiker. Als u een time-outfout krijgt na de markering van 60 minuten bij het exporteren van grote hoeveelheden gegevens, kunt u overwegen om de hoeveelheid gegevens te verminderen met behulp van de juiste filters.

  • De URL-hyperlink van de bestandsshare (bestandsshare /UNC-pad) werkt niet wanneer u een gepubliceerd gepagineerd rapport exporteert op Power BI-service online.

Gerelateerde inhoud

Lees hoe u inhoud insluit voor uw klanten en uw organisatie: