Eksportér sideinddelt rapport til fil
exportToFile API'en gør det muligt at eksportere en sideinddelt Power BI-rapport ved hjælp af et REST-kald. Følgende filformater understøttes:
.pptx (PowerPoint)
.pdf (og tilgængelig PDF eller PDF/UA)
.xlsx (Excel)
.docx (Word)
.Csv
.Xml
.Mhtml
Billede
Når du eksporterer til et billede, skal du angive billedformatet viaOutputFormatformatindstillingen. De understøttedeOutputFormatværdier er:- .tiff (standard)
- .Bmp
- .Emf
- .gif
- .jpeg
- .png
Eksempler på anvendelse
Du kan bruge eksportfunktionen på forskellige 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 .pptx-fil. Når den er fuldført, kan brugeren modtage filen som en download. Ved hjælp af rapportparametre og formatindstillinger kan du eksportere rapporten i en bestemt tilstand, herunder filtrerede data, brugerdefinerede sidestørrelser og andre formatspecifikke 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 automatiseret 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.
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
exportToFilehar begrænset support i Premium pr. bruger.
Gengivelseshændelser
Hvis du vil sikre dig, at eksporten ikke starter, før visualiseringen er færdig med at blive gengivet, 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.
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
Formatindstillinger
Angiv forskellige formatindstillinger for hvert filformat. De understøttede egenskaber og værdier svarer til parametre for Enhedsoplysninger for url-parametre for sideinddelte rapporter.
Her er to eksempler. Den første er til eksport af de første fire sider i en rapport ved hjælp af rapportsidens størrelse til en .pptx-fil. Det andet eksempel er eksport af den tredje side i en rapport til en .jpeg-fil.
Eksport af de første fire sider til en .pptx
{
"format": "PPTX",
"paginatedReportConfiguration":{
"formatSettings":{
"UseReportPageSize": "true",
"StartPage": "1",
"EndPage": "4"
}
}
}
Eksporterer den tredje side til en .jpeg-fil
{
"format": "IMAGE",
"paginatedReportConfiguration":{
"formatSettings":{
"OutputFormat": "JPEG",
"StartPage": "3",
"EndPage": "3"
}
}
}
Rapportparametre
Du kan bruge API'en exportToFile til programmeringsmæssigt at eksportere en rapport med et sæt rapportparametre. Dette gøres ved hjælp af rapportparameteregenskaber .
Her er et eksempel på angivelse af rapportparameterværdier.
{
"format": "PDF",
"paginatedReportConfiguration":{
"parameterValues":[
{"name": "State", "value": "WA"},
{"name": "City", "value": "Seattle"},
{"name": "City", "value": "Bellevue"},
{"name": "City", "value": "Redmond"}
]
}
}
Godkendelse
Du kan godkende ved hjælp af en bruger (eller masterbruger) eller en tjenesteprincipal.
Sikkerhed på rækkeniveau (RLS)
Når du bruger en semantisk Power BI-model, hvor sikkerhed på rækkeniveau er defineret som en datakilde, kan du eksportere en rapport, der viser data, der kun er synlige for visse brugere. Hvis du f.eks. eksporterer en salgsrapport, der er defineret med regionale roller, kan du filtrere rapporten programmeringsmæssigt, så kun et bestemt område vises.
Hvis du vil eksportere ved hjælp af sikkerhed på rækkeniveau, skal du have læsetilladelse til den semantiske Power BI-model, som rapporten bruger som datakilde.
Her er et eksempel på angivelse af et effektivt brugernavn til sikkerhed på rækkeniveau.
{
"format": "PDF",
"paginatedReportConfiguration":{
"identities": [
{"username": "john@contoso.com"}
]
}
}
Single Sign-on SQL og Dataverse (SSO)
I Power BI har du mulighed for at angive OAuth med SSO. Når du gør det, bruges legitimationsoplysningerne for den bruger, der får vist rapporten, til at hente data. Adgangstokenet i anmodningsheaderen bruges ikke til at få adgang til dataene. Tokenet skal overføres med den effektive identitet i postorganet.
Det kan nogle gange være svært at hente det korrekte adgangstoken for den ressource, du vil have adgang til.
- For Azure SQL er
https://database.windows.netressourcen . - For Dataverse er
https://ressourcen adressen for dit miljø. F.eks.,https://contoso.crm.dynamics.com.
Få adgang til token-API'en ved hjælp af metoden AuthenticationContext.AcquireTokenAsync .
Her er et eksempel på, hvordan du leverer en effektiv identitet (brugernavn) med et adgangstoken.
{
"format":"PDF",
"paginatedReportConfiguration":{
"formatSettings":{
"AccessiblePDF":"true",
"PageHeight":"11in",
"PageWidth":"8.5in",
"MarginBottom":"2in"
},
"identities":[
{
"username":"john@contoso.com",
"identityBlob": {
"value": "eyJ0eX....full access token"
}
}
]
}
}
Samtidige anmodninger
exportToFile understøtter et begrænset antal samtidige anmodninger. Det maksimale antal samtidige anmodninger om gengivelse af sideinddelte rapporter er 500. 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.
Med Premium pr. brugerexportToFile tillader API'en kun én anmodning i et fem-minutters vindue. Flere anmodninger i vinduet på fem minutter resulterer i en fejl på for mange anmodninger (429).
Kodeeksempler
Den Power BI-API SDK, der bruges i kodeeksemplerne, kan downloades her.
Når du opretter et eksportjob, er der tre trin, du skal følge:
- Sender en eksportanmodning.
- Polling.
- Henter filen.
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 en eksportanmodning for et bestemt sideområde, en bestemt størrelse og rapportparameterværdier.
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;
}
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<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;
}
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 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;
}
Eksempel fra ende til anden
Dette er et eksempel fra ende til anden for eksport af en rapport. Dette eksempel indeholder følgende faser:
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;
}
}
Overvejelser og begrænsninger
Eksport af en sideinddelt rapport, der har en semantisk Power BI-model som datakilde, understøttes ikke i følgende tilfælde:
- Den person, der ringer op, er en tjenesteprincipalprofil.
- En af den semantiske models datakilder er konfigureret med enkeltlogon (SSO) aktiveret, og der blev angivet en effektiv identitet.
- Den semantiske Power BI-model har DirectQuery til Azure Analysis Services eller til en anden semantisk Power BI-model, og der blev angivet en effektiv identitet.
Eksport af en sideinddelt rapport, hvor Azure Analysis Services-datakilden er konfigureret med enkeltlogon (SSO) aktiveret, understøttes ikke i følgende tilfælde:
- Den person, der ringer op, er en tjenesteprincipalprofil.
- Kalderen er masterbruger, og der blev angivet en effektiv identitet.
Hvis du vil eksportere en sideinddelt rapport med en effektiv identitet, skal brugernavnet være en eksisterende bruger fra din lejers Microsoft Entra-id.
Eksport af en rapport er begrænset til 60 minutter, hvilket svarer til brugerens adgangstokens levetid. Hvis du får vist en timeoutfejl efter 60-minutters mærket, når du eksporterer store mængder data, kan du overveje at reducere mængden af data ved hjælp af relevante filtre.
URL-linket til filsharet (filshare/UNC-sti) fungerer ikke, når du eksporterer en publiceret sideinddelt rapport på Power BI-tjeneste online.
Relateret indhold
Gennemse, hvordan du integrerer indhold for dine kunder og din organisation:
Feedback
Kommer snart: I hele 2024 udfaser vi GitHub-problemer som feedbackmekanisme for indhold og erstatter det med et nyt feedbacksystem. Du kan få flere oplysninger under: https://aka.ms/ContentUserFeedback.
Indsend og få vist feedback om