Exportera sidnumrerad rapport till fil

  • Artikel

API:et exportToFile gör det möjligt att exportera en sidnumrerad Power BI-rapport med hjälp av ett REST-anrop. Följande filformat stöds:

  • .pptx (PowerPoint)

  • .pdf (och tillgänglig PDF eller PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .Csv

  • .Xml

  • .Mhtml

  • Bild
    När du exporterar till en bild anger du bildformatet via formatinställningen OutputFormat . De värden som stöds OutputFormat är:

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

Exempel på användning

Du kan använda exportfunktionen på olika sätt. Här är några exempel:

  • Knappen Skicka till utskrift – I ditt program skapar du en knapp som när du klickar på utlöser ett exportjobb. Jobbet kan exportera den visade rapporten som en .pdf eller en .pptx. När den är klar kan användaren ta emot filen som en nedladdning. Med hjälp av rapportparametrar och formatinställningar kan du exportera rapporten i ett visst tillstånd, inklusive filtrerade data, anpassade sidstorlekar och andra formatspecifika inställningar. Eftersom API:et är asynkront kan det ta lite tid innan filen är tillgänglig.

  • E-postbilaga – Skicka ett automatiserat e-postmeddelande med angivna intervall med en bifogad .pdf-rapport. Det här scenariot kan vara användbart om du vill automatisera sändningen av en veckorapport till chefer.

Använda API:et

Licenskrav

Återgivningshändelser

Om du vill kontrollera att exporten inte börjar innan det visuella objektet har slutfört återgivningen använder du API:et "Rendering"-händelser och påbörjar bara exporten när renderingen är klar.

avsökning

API:et är asynkront. När exportToFile-API:et anropas utlöser det ett exportjobb. När du har utlöst ett exportjobb använder du avsökning för att spåra jobbet tills det är klart.

När exporten är klar returnerar API-avsökningsanropet en Power BI-URL för att hämta filen. URL:en är tillgänglig i 24 timmar.

Funktioner som stöds

Formatinställningar

Ange olika formatinställningar för varje filformat. De egenskaper och värden som stöds motsvarar parametrarna för enhetsinformation för sidnumrerade rapport-URL-parametrar.

Här följer två exempel. Den första är för att exportera de första fyra sidorna i en rapport med hjälp av rapportsidans storlek till en .pptx-fil. Det andra exemplet är för att exportera den tredje sidan i en rapport till en .jpeg-fil.

Exportera de första fyra sidorna till en .pptx

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

Exportera den tredje sidan till en .jpeg

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

Rapportparametrar

Du kan använda API:et exportToFile för att programmatiskt exportera en rapport med en uppsättning rapportparametrar. Detta görs med hjälp av rapportparameterfunktioner .

Här är ett exempel för att ange rapportparametervärden.

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

Autentisering

Du kan autentisera med hjälp av en användare (eller huvudanvändare) eller ett huvudnamn för tjänsten.

Säkerhet på radnivå (RLS)

När du använder en Power BI-semantisk modell med säkerhet på radnivå (RLS) som definierats som en datakälla, kan du exportera en rapport som visar data som bara är synliga för vissa användare. Om du till exempel exporterar en försäljningsrapport som har definierats med regionala roller kan du programmatiskt filtrera rapporten så att endast en viss region visas.

Om du vill exportera med RLS måste du ha läsbehörighet för power BI-semantikmodellen som rapporten använder som datakälla.

Här är ett exempel på hur du anger ett effektivt användarnamn för RLS.

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

Enkel inloggning i SQL och Dataverse (SSO)

I Power BI har du möjlighet att ange OAuth med enkel inloggning. När du gör det används autentiseringsuppgifterna för användaren som visar rapporten för att hämta data. Åtkomsttoken i begärandehuvudet används inte för att komma åt data. Token måste skickas med den effektiva identiteten i posttexten.

Det kan ibland vara svårt att få rätt åtkomsttoken för den resurs som du vill komma åt.

  • För Azure SQL är https://database.windows.netresursen .
  • För Dataverse är resursen https:// adressen för din miljö. Exempel: https://contoso.crm.dynamics.com

Få åtkomst till token-API:et med metoden AuthenticationContext.AcquireTokenAsync .

Här är ett exempel för att tillhandahålla en effektiv identitet (användarnamn) med en åtkomsttoken.

{
       "format":"PDF",
       "paginatedReportConfiguration":{
          "formatSettings":{
             "AccessiblePDF":"true",
             "PageHeight":"11in",
             "PageWidth":"8.5in",
             "MarginBottom":"2in"
          },
          "identities":[
             {
                "username":"john@contoso.com",
                "identityBlob": {
                "value": "eyJ0eX....full access token"
         }
        }
     ]
   }
}

Samtidiga förfrågningar

Har exportToFile stöd för ett begränsat antal samtidiga begäranden. Det maximala antalet samtidiga sidnumrerade rapportåtergivningsbegäranden är 500. Om du vill undvika att överskrida gränsen och få ett fel med för många begäranden (429) distribuerar du belastningen över tid eller mellan kapaciteter.

Med Premium per användare (PPU) tillåter API:et exportToFile bara en begäran i ett femminutersfönster. Flera begäranden inom femminutersfönstret resulterar i ett fel med för många begäranden (429).

Kodexempel

Det Power BI-API SDK som används i kodexemplen kan laddas ned här.

När du skapar ett exportjobb finns det tre steg att följa:

  1. Skickar en exportbegäran.
  2. Polling.
  3. Hämtar filen.

Det här avsnittet innehåller exempel för varje steg.

Steg 1 – skicka en exportbegäran

Det första steget är att skicka en exportbegäran. I det här exemplet skickas en exportbegäran för ett specifikt sidintervall, storlek och rapportparametervärden.

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

Steg 2 – avsökning

När du har skickat en exportbegäran använder du avsökning för att identifiera när exportfilen som du väntar på är 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;
}

Steg 3 – hämta filen

När avsökningen returnerar en URL använder du det här exemplet för att hämta den mottagna 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;
}

Exempel från slutpunkt till slutpunkt

Det här är ett exempel från slutpunkt till slutpunkt för att exportera en rapport. Det här exemplet innehåller följande steg:

  1. Skickar exportbegäran.
  2. Avsökning.
  3. Hämtar 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;
    }
}

Beaktanden och begränsningar

  • Export av en sidnumrerad rapport som har en Power BI-semantisk modell som datakälla stöds inte i följande fall:

    • Anroparen är en profil för tjänstens huvudnamn.
    • En av semantikmodellens datakällor har konfigurerats med enkel inloggning (SSO) aktiverat och en effektiv identitet har angetts.
    • Power BI-semantikmodellen har DirectQuery till Azure Analysis Services eller till en annan Power BI-semantisk modell och en effektiv identitet tillhandahölls.

  • Export av en sidnumrerad rapport som har Azure Analysis Services-datakällan konfigurerad med enkel inloggning (SSO) aktiverad stöds inte i följande fall:

  • Om du vill exportera en sidnumrerad rapport med en effektiv identitet måste användarnamnet vara en befintlig användare från klientorganisationens Microsoft Entra-ID.

  • Exporten av en rapport är begränsad till 60 minuter, vilket matchar livslängden för användarens åtkomsttoken. Om du får ett timeout-fel efter 60-minutersmarkeringen när du exporterar stora mängder data bör du överväga att minska mängden data med lämpliga filter.

  • Hyperlänken för filresursens URL (filresurs/UNC-sökväg) fungerar inte när du exporterar en publicerad sidnumrerad rapport på Power BI-tjänst online.

Relaterat innehåll

Läs om hur du bäddar in innehåll för dina kunder och din organisation: