Eksportér Power BI-rapport til fil

exportToFile API'en gør det muligt at eksportere en Power BI-rapport ved hjælp af et REST-kald. Følgende filformater understøttes:

• .pptx (PowerPoint)
• .pdf
• .png
  • Når du eksporterer til en .png, komprimeres en rapport med flere sider til en .zip fil
  • Hver fil i .zip repræsenterer en rapportside
  • Sidenavnene er de samme som returværdierne for API'erne Hent sider eller Hent sider i gruppe

Bemærk

Eksport af en Power BI-rapport til en fil ved hjælp af exportToFile-API'en understøttes ikke for Premium pr. bruger.

Eksempler på anvendelse

Du kan bruge eksportfunktionen på flere måder. Her er et par eksempler:

• Knappen Send til udskrivning – Opret en knap i programmet, der udløser et eksportjob, når der klikkes på den. Jobbet kan eksportere den viste rapport som en .pdf eller en .pptx. Når den er fuldført, kan brugeren modtage filen som en download. Ved hjælp af bogmærker kan du eksportere rapporten i en bestemt tilstand, herunder konfigurerede filtre, udsnitsværktøjer og andre indstillinger. Da API'en er asynkron, kan det tage et stykke tid, før filen er tilgængelig.

• Vedhæftet fil i mail – Send en automatisk mail med faste intervaller med en vedhæftet .pdf rapport. Dette scenarie kan være nyttigt, hvis du vil automatisere afsendelse af en ugentlig rapport til ledere. Du kan finde flere oplysninger under Eksportér og send en Power BI-rapport via mail med Power Automate

Brug af API'en

Licenskrav

• Den rapport, du eksporterer, skal være placeret i et arbejdsområde, der understøttes af en Premium-, Embedded- eller Fabric-kapacitet.
• API'en exportToFile understøttes ikke for Premium pr. bruger.

Administratorindstillinger

Før du bruger API'en, skal du kontrollere, at følgende administratorlejerindstillinger er aktiveret:

• Eksportér rapporter som PowerPoint-præsentationer eller PDF-dokumenter – aktiveret som standard.
• Eksportér rapporter som billedfiler – kræves kun for .png og deaktiveret som standard.

"Gengivelseshændelser"

Hvis du vil sikre dig, at eksporten ikke starter, før visualiseringen er færdig med at gengive, skal du bruge API'en til "Gengivelse" og kun starte eksporten, når gengivelsen er fuldført.

Polling

API'en er asynkron. Når exportToFile-API'en kaldes, udløser den et eksportjob. Når du har udløst et eksportjob, skal du bruge polling til at spore jobbet, indtil det er fuldført.

Under polling returnerer API'en et tal, der repræsenterer den mængde arbejde, der er fuldført. Arbejdet i hvert eksportjob beregnes på baggrund af det samlede antal eksporter i jobbet. En eksport omfatter eksport af en enkelt visualisering eller en side med eller uden bogmærker. Alle eksporter har samme vægt. Hvis dit eksportjob f.eks. omfatter eksport af en rapport med 10 sider, og polling returnerer 70, betyder det, at API'en behandlede syv ud af de 10 sider i eksportjobbet.

Når eksporten er fuldført, returnerer forespørgsels-API-kaldet en URL-adresse til Power BI for at hente filen. URL-adressen er tilgængelig i 24 timer.

Understøttede funktioner

I dette afsnit beskrives det, hvordan du bruger følgende understøttede funktioner:

• Valg af de sider, der skal udskrives
• Eksport af en side eller en enkelt visualisering
• Bogmærker
• Filtre
• Godkendelse
• Sikkerhed på rækkeniveau (RLS)
• Databeskyttelse
• Lokalisering
• Dynamisk binding

Valg af de sider, der skal udskrives

Angiv de sider, du vil udskrive, i henhold til returværdien Hent sider eller Hent sider i gruppe . Du kan også angive rækkefølgen af de sider, du eksporterer.

Eksport af en side eller en enkelt visualisering

Du kan angive en side eller en enkelt visualisering, der skal eksporteres. Sider kan eksporteres med eller uden bogmærker.

Afhængigt af typen af eksport skal du overføre forskellige attributter til Objektet ExportReportPage . I følgende tabel angives, hvilke attributter der kræves for hvert eksportjob.

Bemærk

Eksport af en enkelt visualisering har samme vægt som eksport af en side (med eller uden bogmærker). Det betyder, at med hensyn til systemberegninger har begge handlinger samme værdi.

Attribut	Side	Enkelt visualisering	Kommentarer
bookmark	Valgfrit		Bruges til at eksportere en side i en bestemt tilstand
pageName			Brug GetPages REST API'en eller klient-API'engetPages.
visualName			Der er to måder at hente navnet på visualiseringen på: Brug klient-API'engetVisuals. Lyt og logfør hændelsen visualClicked , som udløses, når en visualisering vælges. Du kan få flere oplysninger under Sådan håndterer du hændelser .

Bogmærker

Bogmærker kan bruges til at gemme en rapport i en bestemt konfiguration, herunder anvendte filtre og tilstanden for rapportens visualiseringer. Du kan bruge API'en exportToFile til programmeringsmæssigt at eksportere en rapports bogmærke på to måder:

• Eksportér et eksisterende bogmærke

  Hvis du vil eksportere et eksisterende rapportbogmærke, skal du bruge egenskabenname, som er et entydigt id (forskel på store og små bogstaver), som du kan bruge JavaScript-API'en til bogmærker.

• Eksportér rapportens tilstand

  Hvis du vil eksportere rapportens aktuelle tilstand, skal du bruge egenskaben state . Du kan f.eks. bruge bogmærkets bookmarksManager.capture metode til at registrere de ændringer, en bestemt bruger har foretaget i en rapport, og derefter eksportere den i dens aktuelle tilstand ved hjælp af capturedBookmark.state.

Bemærk

Personlige bogmærker og faste filtre understøttes ikke.

Filtre

Ved hjælp af reportLevelFilters i PowerBIReportExportConfiguration kan du eksportere en rapport i en filtreret betingelse.

Hvis du vil eksportere en filtreret rapport, skal du indsætte de parametre for URL-forespørgselsstrengen, du vil bruge som filter, til ExportFilter. Når du angiver strengen, skal du fjerne den ?filter= del af URL-forespørgselsparameteren.

Tabellen indeholder nogle få syntakseksempler på strenge, du kan overføre til ExportFilter.

Filtrer	Syntaks	Eksempel
En værdi i et felt	Table/Field eq 'value'	Store/Territory eq 'NC'
Flere værdier i et felt	Tabel/felt i ('value1', 'value2')	Store/Territory in ('NC', 'TN')
En entydig værdi i ét felt og en anden distinkt værdi i et andet felt	Table/Field1 eq 'value1' og Table/Field2 eq 'value2'	Store/Territory eq 'NC' and Store/Chain eq 'Fashions Direct'

Godkendelse

Du kan godkende ved hjælp af en bruger (eller masterbruger) eller en tjenesteprincipal.

Sikkerhed på rækkeniveau (RLS)

Med sikkerhed på rækkeniveau kan du eksportere en rapport, der viser data, der kun er synlige for bestemte brugere. Hvis du f.eks. eksporterer en salgsrapport, der er defineret med regionale roller, kan du filtrere rapporten programmatisk, så der kun vises et bestemt område.

Hvis du vil eksportere ved hjælp af sikkerhed på rækkeniveau, skal du have følgende tilladelser:

• Skrivetilladelser til den semantiske model, som rapporten er forbundet med
• Bidragyder eller administrator af det arbejdsområde, hvor rapporten er placeret

Databeskyttelse

Formaterne .pdf og .pptx understøtter følsomhedsmærkater. Hvis du eksporterer en rapport med en følsomhedsmærkat til en .pdf eller en .pptx, viser den eksporterede fil rapporten med dens følsomhedsmærkat.

En rapport med en følsomhedsmærkat kan ikke eksporteres til en .pdf eller en .pptx ved hjælp af en tjenesteprincipal.

Lokalisering

Når du bruger API'en exportToFile , kan du overføre den ønskede landestandard. Indstillingerne for lokalisering påvirker den måde, rapporten vises på, f.eks. ved at ændre formateringen i henhold til den valgte lokale.

Dynamisk binding

Hvis du vil eksportere en rapport, mens den har forbindelse til en semantisk model, der er en anden end den semantiske standardmodel, skal du angive det påkrævede datasæt-id i datasetToBind parameteren, når API'en kaldes. Læs mere om dynamisk binding.

Samtidige anmodninger

API'en exportToFile understøtter et begrænset antal samtidige anmodninger. Det maksimale antal understøttede samtidige anmodninger er 500 pr. kapacitet. Hvis du vil undgå at overskride grænsen og få fejlen For mange anmodninger (429), skal du enten distribuere belastningen over tid eller på tværs af kapaciteter. Det er kun fem sider i en rapport, der behandles samtidigt. Hvis du f.eks. eksporterer en rapport med 50 sider, behandles eksportjobbet i 10 sekventielle intervaller. Når du optimerer dit eksportjob, kan du overveje at udføre nogle få job parallelt.

Kodeeksempler

Når du opretter et eksportjob, er der fire trin, du skal følge:

1. Sender en eksportanmodning.
2. Polling.
3. Henter filen.
4. Brug af filstreamen.

Dette afsnit indeholder eksempler på hvert trin.

Trin 1 – afsendelse af en eksportanmodning

Det første trin er at sende en eksportanmodning. I dette eksempel sendes der en eksportanmodning for en bestemt side.

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

Trin 2 – polling

Når du har sendt en eksportanmodning, kan du bruge polling til at identificere, hvornår den eksportfil, du venter på, er klar.

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

Trin 3 – hentning af filen

Når polling returnerer en URL-adresse, skal du bruge dette eksempel til at hente den modtagne fil.

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

Trin 4 – Brug af filstrømmen

Når du har filstreamen, kan du håndtere den på den måde, der passer bedst til dine behov. Du kan f.eks. sende en mail til den eller bruge den til at downloade de eksporterede rapporter.

Eksempel fra ende til anden

Dette er et eksempel fra ende til anden for eksport af en rapport. Dette eksempel indeholder følgende faser:

1. Sender eksportanmodningen.
2. Polling.
3. Henter filen.

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

Overvejelser og begrænsninger

• En eksport-API-handlingsbelastning evalueres som en langsom kørsel af baggrundshandlingen, som beskrevet i Evaluering af belastning af Premium-kapacitet.
• Alle relaterede semantiske modeller i den rapport, du eksporterer, skal være placeret på en Premium- eller Embedded-kapacitet, herunder semantiske modeller med en Direct Query-forbindelse.
• Eksporterede rapporter må ikke overstige en filstørrelse på 250 MB.
• Når du eksporterer til .png, understøttes følsomhedsmærkater ikke.
• Antallet af eksporter (enkelte visualiseringer eller rapportsider), der kan medtages i en enkelt eksporteret rapport, er 50 (ikke inklusive eksport af sideinddelte rapporter). Hvis anmodningen indeholder flere eksporter, returnerer API'en en fejl, og eksportjobbet annulleres.
• Personlige bogmærker og faste filtre understøttes ikke for eksport til fil i Power BI-rapporter.
• exportToFile API'en eksporterer rapporten med standardværdien, hvis den bruges uden bogmærker eller reportLevelFilters.
• Eksport af en Power BI-rapport, der er forbundet til en eller flere sammensatte semantiske modeller, som har mindst én ekstern datakilde med enkeltlogon (SSO) aktiveret, understøttes ikke. Når du eksporterer, gengives visualiseringer muligvis ikke korrekt.
• Når du eksporterer en rapport med dynamisk binding ved hjælp af exportToFile REST-API'en, kan den dynamisk bundne semantiske model ikke være en sammensat model med en direkte forespørgsel til SQL Server Analysis Services (SSAS).
• De Power BI-visualiseringer, der er angivet her, understøttes ikke. Når du eksporterer en rapport, der indeholder disse visualiseringer, gengives de dele af rapporten, der indeholder disse visualiseringer, ikke, og der vises et fejlsymbol.
  • Brugerdefinerede Power BI-visualiseringer, der ikke er certificerede
  • R-visualiseringer
  • PowerApps
  • Python-visualiseringer
  • Power Automate
  • Visualisering af sideinddelt rapport
  • Visio
  • ArcGIS-visualiseringer

Relateret indhold

Gennemse, hvordan du integrerer indhold for dine kunder og din organisation:

• Eksportér sideinddelt rapport til fil
• Integrer for dine kunder
• Integrer for din organisation
• Eksportér og send en Power BI-rapport via mail med Power Automate

Flere spørgsmål? Prøv Power BI-community'et