Delen via

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-

  • afbeelding
    Wanneer u naar een afbeelding exporteert, stelt u het afbeeldingsformaat in via de OutputFormat-instelling. De ondersteunde OutputFormat waarden zijn:

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

Gebruiksvoorbeelden

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

  • Verzenden om te printen-knop - Maak in de toepassing een knop die een exporttaak start wanneer erop wordt geklikt. De taak kan het weergegeven rapport exporteren als een .pdf of een .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 asynchroon is, 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

  • Het rapport dat u exporteert, moet zich in een werkruimte bevinden die wordt ondersteund door een Premium-, Embedded- of Fabric-capaciteit.
  • De exportToFile-API heeft beperkte ondersteuning in PPU-(Premium Per User).

Rendering-gebeurtenissen

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

Polling

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 de export 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 equivalent aan de parameters voor apparaatgegevens () en 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 gebeurt met behulp van de mogelijkheden van de rapportparameter.

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"}
            ]
      }
}

Authenticatie

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 is een voorbeeld van het opgeven van een effectieve gebruikersnaam voor RLS.

{
      "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 Single Sign-On (SSO). 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 de resource https://database.windows.net.
  • 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

De exportToFile ondersteunt een beperkt aantal gelijktijdige aanvragen. Het maximum aantal gelijktijdige gepagineerde rapportaanvragen is 500. Om te voorkomen dat de limiet wordt overschreden en een foutmelding voor te veel verzoeken (429) krijgt, verdeelt u de belasting over een bepaalde periode of over capaciteiten.

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

Codevoorbeelden

De Power BI API 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.
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 serviceprincipal-profiel.
    • 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 biedt DirectQuery naar Azure Analysis Services of naar een ander semantisch Power BI-model, en er is een geldige 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-out fout krijgt wanneer u langer dan 60 minuten bezig bent met het exporteren van grote hoeveelheden gegevens, overweeg dan 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 online exporteert in de Power BI-service.

Verwante inhoud

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