Eksporter paginert rapport til fil

  • Artikkel

exportToFile API-en aktiverer eksport av en paginert Power BI-rapport ved hjelp av et REST-anrop. Følgende filformater støttes:

  • PPTX (PowerPoint)

  • PDF (og tilgjengelig PDF eller PDF/UA)

  • XLSX (Excel)

  • .docx (Word)

  • .Csv

  • .Xml

  • .Mhtml

  • Bilde
    Når du eksporterer til et bilde, angir du bildeformatet via OutputFormat formatinnstillingen. De støttede OutputFormat verdiene er:

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

Eksempler på bruk

Du kan bruke eksportfunksjonen på forskjellige måter. Her er et par eksempler:

  • Send for å skrive ut-knappen – Opprett en knapp i programmet når du klikker på utløser en eksportjobb. Jobben kan eksportere den viste rapporten som en PDF- eller PPTX-fil. Når den er fullført, kan brukeren motta filen som en nedlasting. Ved hjelp av rapportparametere og formatinnstillinger kan du eksportere rapporten i en bestemt tilstand, inkludert filtrerte data, egendefinerte sidestørrelser og andre formatspesifikke innstillinger. Da API-en er asynkron, kan det ta litt tid før filen blir tilgjengelig.

  • E-postvedlegg – Send en automatisert e-postmelding med angitte intervaller, med en vedlagt PDF-rapport. Dette scenarioet kan være nyttig hvis du vil automatisere sending av en ukentlig rapport til ledere.

Bruke API-en

Lisenskrav

Gjengivelseshendelser

Hvis du vil forsikre deg om at eksporten ikke begynner før gjengivelsen av visualobjektet er ferdig, bruker du API-en for gjengivelseshendelser og starter bare eksporten når gjengivelsen er fullført.

Polling

API-en er asynkron. Når exportToFile-API-en kalles, utløses en eksportjobb. Når du har utløst en eksportjobb, kan du bruke avspørring til å spore jobben til den er fullført.

Når eksporten er fullført, returnerer API-kallet for avspørring en Nettadresse for Power BI for å hente filen. URL-adressen er tilgjengelig i 24 timer.

Støttede funksjoner

Formateringsinnstillinger

Angi ulike formatinnstillinger for hvert filformat. De støttede egenskapene og verdiene tilsvarer parametere for enhetsinformasjon for url-parametere for paginerte rapporter.

Her er to eksempler. Den første er for å eksportere de fire første sidene i en rapport ved hjelp av rapportsidestørrelsen til en PPTX-fil. Det andre eksemplet er å eksportere den tredje siden i en rapport til en JPEG-fil.

Eksportere de fire første sidene til en PPTX

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

Eksporterer den tredje siden til en JPEG

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

Rapportparametere

Du kan bruke exportToFile API-en til å eksportere en rapport programmatisk med et sett med rapportparametere. Dette gjøres ved hjelp av rapportparameterfunksjoner .

Her er et eksempel på hvordan du angir rapportparameterverdier.

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

Autentisering

Du kan godkjenne ved hjelp av en bruker (eller hovedbruker) eller en tjenestekontohaver.

Sikkerhet på radnivå (RLS)

Når du bruker en semantisk Power BI-modell som har sikkerhet på radnivå (RLS) definert som en datakilde, kan du eksportere en rapport som viser data som bare er synlige for bestemte brukere. Hvis du for eksempel eksporterer en salgsrapport som er definert med regionale roller, kan du programmatisk filtrere rapporten slik at bare et bestemt område vises.

Hvis du vil eksportere ved hjelp av RLS, må du ha lesetillatelse for semantisk Power BI-modell som rapporten bruker som datakilde.

Her er et eksempel på å angi et effektivt brukernavn for RLS.

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

Enkel pålogging sql og datavers (SSO)

I Power BI har du muligheten til å angi OAuth med SSO. Når du gjør dette, brukes legitimasjonen for brukeren som viser rapporten til å hente data. Tilgangstokenet i forespørselshodet brukes ikke til å få tilgang til dataene. Tokenet må sendes inn med den effektive identiteten i postteksten.

Det kan noen ganger være vanskelig å få riktig tilgangstoken for ressursen du vil ha tilgang til.

  • For Azure SQL er https://database.windows.netressursen .
  • For Dataverse er ressursen https:// adressen for miljøet ditt. Eksempel: https://contoso.crm.dynamics.com.

Få tilgang til token-API-en ved hjelp av metoden AuthenticationContext.AcquireTokenAsync .

Her er et eksempel for å angi en effektiv identitet (brukernavn) med et tilgangstoken.

{
       "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 forespørsler

Støtter exportToFile et begrenset antall samtidige forespørsler. Maksimalt antall samtidige forespørsler om paginert rapportgjengivelse er 500. Hvis du vil unngå å overskride grensen og få en for mange forespørsler (429)-feil, kan du enten distribuere belastningen over tid eller på tvers av kapasiteter.

Med Premium per bruker (PPU)exportToFile tillater API-en bare én forespørsel i et vindu på fem minutter. Flere forespørsler i det fem minutter lange vinduet resulterer i en for mange forespørsler (429)-feil.

Kodeeksempler

Den Power BI-API SDK som brukes i kodeeksempler, kan lastes ned her.

Når du oppretter en eksportjobb, er det tre trinn å følge:

  1. Sender en eksportforespørsel.
  2. Polling.
  3. Henter filen.

Denne inndelingen inneholder eksempler for hvert trinn.

Trinn 1 – sende en eksportforespørsel

Det første trinnet er å sende en eksportforespørsel. I dette eksemplet sendes en eksportforespørsel for et bestemt sideområde, størrelse og rapportparameterverdier.

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

Trinn 2 – avstemning

Når du har sendt en eksportforespørsel, kan du bruke avspørring til å identifisere når eksportfilen 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;
}

Trinn 3 – hente filen

Når avspørring returnerer en URL-adresse, kan du bruke dette eksemplet til å hente den mottatte filen.

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 på ende-til-ende

Dette er et eksempel fra ende til ende for eksport av en rapport. Dette eksemplet inneholder følgende faser:

  1. Sender eksportforespørselen.
  2. Avstemning.
  3. Henter filen.
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;
    }
}

Hensyn og begrensninger

  • Eksport av en paginert rapport som har en semantisk Power BI-modell som datakilde, støttes ikke i følgende tilfeller:

    • Innringeren er en tjenestekontohaverprofil.
    • En av de semantiske modellens datakilder er konfigurert med enkel pålogging (SSO) aktivert, og en effektiv identitet ble angitt.
    • Den semantiske Power BI-modellen har DirectQuery til Azure Analysis Services eller til en annen semantisk Power BI-modell, og en effektiv identitet ble angitt.

  • Eksport av en paginert rapport som har Azure Analysis Services-datakilde konfigurert med enkel pålogging (SSO) aktivert, støttes ikke i følgende tilfeller:

  • Hvis du vil eksportere en paginert rapport med en effektiv identitet, må brukernavnet være en eksisterende bruker fra leierens Microsoft Entra-ID.

  • Eksport av en rapport er begrenset til 60 minutter, som samsvarer med levetiden til brukertilgangstokenet. Hvis du får en tidsavbruddsfeil forbi 60-minuttersmerket når du eksporterer store mengder data, kan du vurdere å redusere mengden data ved hjelp av riktige filtre.

  • Hyperkoblingen url-adresse for fildeling (fildeling /UNC-bane) fungerer ikke når du eksporterer en publisert paginert rapport på Power Bi-tjeneste tilkoblet.

Relatert innhold

Se gjennom hvordan du bygger inn innhold for kundene og organisasjonen: