Power BI-rapport exporteren naar bestand

Artikel
12/19/2023

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

.pptx (PowerPoint)
.Pdf
.png
- Wanneer u exporteert naar een PNG-bestand, wordt een rapport met meerdere pagina's gecomprimeerd in een ZIP-bestand
- Elk bestand in de .zip vertegenwoordigt een rapportpagina
- De paginanamen zijn hetzelfde als de retourwaarden van de Get Pages of Get Pages in Groeps-API's

Notitie

Het exporteren van een Power BI-rapport naar een bestand met behulp van de exportToFile-API wordt niet ondersteund voor PPU (Premium Per User).

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 bladwijzers kunt u het rapport in een specifieke status exporteren, waaronder geconfigureerde filters, slicers en andere 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. Zie Een Power BI-rapport exporteren en e-mailen met Power Automate voor meer informatie

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 wordt niet ondersteund voor PPU (Premium Per User).

Beheerdersinstellingen

Controleer voordat u de API gebruikt of de volgende tenantinstellingen voor beheerders zijn ingeschakeld:

Rapporten exporteren als PowerPoint-presentaties of PDF-documenten - standaard ingeschakeld.
Rapporten exporteren als afbeeldingsbestanden - alleen vereist voor PNG en standaard uitgeschakeld.

'Rendering'-gebeurtenissen

Als u ervoor wilt zorgen dat de export niet begint voordat de weergave van de visual is voltooid, gebruikt u de API voor rendering-gebeurtenissen en start u alleen 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.

Tijdens het peilen retourneert de API een getal dat de hoeveelheid voltooid werk aangeeft. Het werk in elke exporttaak wordt berekend op basis van het totale aantal exports in de taak. Een export omvat het exporteren van één visual of een pagina met of zonder bladwijzers. Alle exports hebben hetzelfde gewicht. Als uw exporttaak bijvoorbeeld een rapport met tien pagina's exporteert en de polling 70 retourneert, betekent dit dat de API zeven van de tien pagina's in de exporttaak heeft verwerkt.

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

In deze sectie wordt beschreven hoe u de volgende ondersteunde functies gebruikt:

Selecteren welke pagina's u wilt afdrukken
Een pagina of één visual exporteren
Bladwijzers
Filters
Verificatie
Beveiliging op rijniveau (RLS)
Gegevensbeveiliging
Localisatie
Dynamische binding

Selecteren welke pagina's u wilt afdrukken

Geef de pagina's op die u wilt afdrukken op basis van de retourwaarde Pagina's ophalen of Pagina's ophalen in groep . U kunt ook de volgorde opgeven van de pagina's die u exporteert.

Een pagina of één visual exporteren

U kunt een pagina of één visual opgeven die u wilt exporteren. Pagina's kunnen worden geëxporteerd met of zonder bladwijzers.

Afhankelijk van het type export moet u verschillende kenmerken doorgeven aan het object ExportReportPage . De volgende tabel geeft aan welke kenmerken vereist zijn voor elke exporttaak.

Notitie

Het exporteren van één visual heeft hetzelfde gewicht als het exporteren van een pagina (met of zonder bladwijzers). Dit betekent dat in termen van systeemberekeningen beide bewerkingen dezelfde waarde hebben.

Kenmerk	Pagina	Opmerkingen
`bookmark`	Optioneel	Gebruiken om een pagina met een specifieke status te exporteren
`pageName`		Gebruik de GetPages REST API of de `getPages` client-API.
`visualName`		Er zijn twee manieren om de naam van de visual op te halen: Gebruik de `getVisuals` client-API. Luister en registreer de visualClicked-gebeurtenis , die wordt geactiveerd wanneer een visual wordt geselecteerd. Zie Gebeurtenissen afhandelen voor meer informatie .

Bladwijzers

Bladwijzers kunnen worden gebruikt om een rapport op te slaan in een specifieke configuratie, inclusief toegepaste filters en de status van de visuals van het rapport. U kunt de exportToFile-API gebruiken om de bladwijzer van een rapport programmatisch te exporteren, op twee manieren:

Een bestaande bladwijzer exporteren

Als u een bestaande rapportbladwijzer wilt exporteren, gebruikt u de name eigenschap, een unieke (hoofdlettergevoelige) id, die u kunt ophalen met behulp van de JavaScript-API voor bladwijzers.
De status van het rapport exporteren

Als u de huidige status van het rapport wilt exporteren, gebruikt u de state eigenschap. U kunt bijvoorbeeld de methode van bookmarksManager.capture de bladwijzer gebruiken om de wijzigingen vast te leggen die een specifieke gebruiker in een rapport heeft aangebracht en deze vervolgens in de huidige status te exporteren met behulp van capturedBookmark.state.

Notitie

Persoonlijke bladwijzers en permanente filters worden niet ondersteund.

Filters

Met powerBIReportExportConfiguration reportLevelFilterskunt u een rapport exporteren in een gefilterde voorwaarde.

Als u een gefilterd rapport wilt exporteren, voegt u de URL-querytekenreeksparameters in die u als filter wilt gebruiken om ExportFilter te exporteren. Wanneer u de tekenreeks invoert, moet u het ?filter= deel van de URL-queryparameter verwijderen.

De tabel bevat enkele syntaxisvoorbeelden van tekenreeksen die u kunt doorgeven ExportFilter.

Filteren	Syntaxis	Opmerking
Een waarde in een veld	Table/Field eq 'value'	Store/Territory eq 'NC'
Meerdere waarden in een veld	Tabel/veld in ('value1', 'value2')	Opslaan/gebied in ('NC', 'TN')
Een afzonderlijke waarde in het ene veld en een andere afzonderlijke waarde in een ander veld	Table/Field1 eq 'value1' en Table/Field2 eq 'value2'	Store/Territory eq 'NC' en Store/Chain eq 'Fashions Direct'

Verificatie

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

Beveiliging op rijniveau (RLS)

Met beveiliging op rijniveau (RLS) 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 RLS, moet u over de volgende machtigingen beschikken:

Schrijf- en deelmachtigingen voor het semantische model waaraan het rapport is gekoppeld
Lid of beheerder van de werkruimte waarin het rapport zich bevindt

Gegevensbescherming

De .pdf- en .pptx-indelingen ondersteunen vertrouwelijkheidslabels. Als u een rapport met een vertrouwelijkheidslabel exporteert naar een .pdf of een .pptx, wordt in het geëxporteerde bestand het rapport met het vertrouwelijkheidslabel weergegeven.

Een rapport met een vertrouwelijkheidslabel kan niet worden geëxporteerd naar een .pdf of een .pptx met behulp van een service-principal.

Lokalisatie

Wanneer u de exportToFile API gebruikt, kunt u de gewenste landinstelling doorgeven. De lokalisatie-instellingen zijn van invloed op de manier waarop het rapport wordt weergegeven, bijvoorbeeld door de opmaak te wijzigen op basis van de geselecteerde lokale.

Dynamische binding

Als u een rapport wilt exporteren terwijl het is verbonden met een semantisch model, anders dan het standaard semantische model, geeft u de vereiste gegevensset-id op in de datasetToBind parameter bij het aanroepen van de API. Meer informatie over dynamische binding.

Gelijktijdige aanvragen

De exportToFile API ondersteunt een beperkt aantal gelijktijdige aanvragen. Het maximum aantal ondersteunde gelijktijdige aanvragen is 500 per capaciteit. 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. Er worden slechts vijf pagina's van een rapport gelijktijdig verwerkt. Als u bijvoorbeeld een rapport met 50 pagina's exporteert, wordt de exporttaak in 10 opeenvolgende intervallen verwerkt. Bij het optimaliseren van uw exporttaak kunt u overwegen om een paar taken parallel uit te voeren.

Codevoorbeelden

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

Een exportaanvraag verzenden.
Polling.
Het bestand wordt opgeslagen.
Gebruik de bestandsstroom.

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 specifieke pagina.

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

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

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

Stap 4: de bestandsstroom gebruiken

Wanneer u de bestandsstroom hebt, kunt u deze afhandelen op de manier die het beste past bij uw behoeften. U kunt deze bijvoorbeeld e-mailen of gebruiken om de geëxporteerde rapporten te downloaden.

End-to-end-voorbeeld

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

De exportaanvraag verzenden.
Polling.
Het bestand wordt opgeslagen.

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

Overwegingen en beperkingen

De belasting van een export-API-bewerking wordt geëvalueerd als een traaglopende achtergrondbewerking, zoals beschreven in de belastingsevaluatie van Premium-capaciteit.
Alle gerelateerde semantische modellen in het rapport dat u exporteert, moeten zich bevinden op een Premium- of Embedded-capaciteit, inclusief semantische modellen met een Direct Query-verbinding.
Geëxporteerde rapporten mogen niet groter zijn dan 250 MB.
Wanneer u exporteert naar .png, worden vertrouwelijkheidslabels niet ondersteund.
Het aantal exports (enkelvoudige visuals of rapportpagina's) dat kan worden opgenomen in één geëxporteerd rapport is 50 (niet inclusief het exporteren van gepagineerde rapporten). Als de aanvraag meer exports bevat, retourneert de API een fout en wordt de exporttaak geannuleerd.
Persoonlijke bladwijzers en permanente filters worden niet ondersteund voor het exporteren van Power BI-rapporten naar bestand.
De exportToFile API exporteert het rapport met de standaardwaarde als het wordt gebruikt zonder bladwijzers of reportLevelFilters.
De power BI-visuals die hier worden vermeld, worden niet ondersteund. Wanneer u een rapport met deze visuals exporteert, worden de delen van het rapport die deze visuals bevatten niet weergegeven en wordt er een foutsymbool weergegeven.
- Niet-gecertificeerde aangepaste Power BI-visuals
- R-visuals
- PowerApps
- Python-visuals
- Power Automate
- Visual gepagineerd rapport
- Visio
- ArcGIS-visuals

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

Meer vragen? Probeer de Power BI-community

Power BI-rapport exporteren naar bestand

Voorbeelden van gebruik

De API gebruiken

Licentievereisten

Beheerdersinstellingen

'Rendering'-gebeurtenissen

Navragen

Ondersteunde functies

Selecteren welke pagina's u wilt afdrukken

Een pagina of één visual exporteren

Bladwijzers

Filters

Verificatie

Beveiliging op rijniveau (RLS)

Gegevensbescherming

Lokalisatie

Dynamische binding

Gelijktijdige aanvragen

Codevoorbeelden

Stap 1: een exportaanvraag verzenden

Stap 2: polling

Stap 3: het bestand downloaden

Stap 4: de bestandsstroom gebruiken

End-to-end-voorbeeld

Overwegingen en beperkingen

Feedback

Feedback

Aanvullende resources

Power BI-rapport exporteren naar bestand

Voorbeelden van gebruik

De API gebruiken

Licentievereisten

Beheerdersinstellingen

'Rendering'-gebeurtenissen

Navragen

Ondersteunde functies

Selecteren welke pagina's u wilt afdrukken

Een pagina of één visual exporteren

Bladwijzers

Filters

Verificatie

Beveiliging op rijniveau (RLS)

Gegevensbescherming

Lokalisatie

Dynamische binding

Gelijktijdige aanvragen

Codevoorbeelden

Stap 1: een exportaanvraag verzenden

Stap 2: polling

Stap 3: het bestand downloaden

Stap 4: de bestandsstroom gebruiken

End-to-end-voorbeeld

Overwegingen en beperkingen

Gerelateerde inhoud

Feedback

Feedback

Aanvullende resources