Exportera sidnumrerad rapport till fil

Med api:et exportToFile kan du 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 inställningen OutputFormat format. De OutputFormat värden som stöds är:

  • .tiff (standard)
  • .bmp
  • .emf
  • .gif
  • .jpeg
  • .png

Användningsexempel

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 automatiskt 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

• Rapporten som du exporterar måste finnas på en arbetsyta som backas upp av en Premium-, Embedded- eller Fabric-kapacitet.
• exportToFile-API:et har begränsat stöd i Premium per användare (PPU).

Återgivningshändelser

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

Opinionsundersökning

API:et är asynkront. När exportToFile API anropas utlöser det ett exportjobb. När du har utlöst ett exportjobb använder du 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 Enhetsinformation för url-parametrar för sidnumrerade rapporter.

Här är 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 exportToFile-API:et för att programmatiskt exportera en rapport med en uppsättning rapportparametrar. Detta görs med hjälp av rapportparameter funktioner.

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 genom att använda en användare (eller huvudanvändare) eller ett tjänstekonto.

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 SSO. 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. Tokenet måste skickas med den effektiva identiteten i innehållet i postningen.

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 resursen https://database.windows.net.
• För Dataverse är resursen adressen https:// för din miljö. Till exempel https://contoso.crm.dynamics.com.

Få åtkomst till token-API:et med hjälp av 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 begäranden

exportToFile stöder 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 exportToFile-API:et bara en begäran i ett femminutersfönster. Flera begäranden inom femminutersfönstret resulterar i ett för många begäranden (429) fel.

Kodexempel

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. Omröstning
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änd "polling" för att veta när exportfilen 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;
}

Helomfattande exempel

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. Skicka exportbegäran.
2. avsökning.
3. Hämta 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;
    }
}

Överväganden 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 tjänsthuvudnamnsprofil.
  • 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:

  • Anroparen är en profil för tjänstehuvudansvarig .
  • Anroparen är en huvudanvändare och en effektiv identitet har angetts.

• 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 i Power BI-tjänsten online.

Relaterat innehåll

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

• Exportera rapport till fil
• Bädda in för dina kunder
• Bädda in för din organisation