Condividi tramite

Esportare il report impaginato in un file

  • Articolo

L'API exportToFile consente di esportare un report impaginato di Power BI tramite una chiamata REST. Sono supportati i seguenti formati di file:

  • PPTX (PowerPoint)

  • .pdf (e PDF accessibile o PDF/UA)

  • XLSX (Excel)

  • .docx (Word)

  • CSV

  • XML

  • MHTML

  • Image
    Quando si esegue l'esportazione in un'immagine, impostare il formato dell'immagine tramite l'impostazione del formato OutputFormat. I valori OutputFormat supportati sono:

    • .tiff (impostazione predefinita)
    • .bmp
    • .emf
    • .gif
    • .jpeg
    • .png

Esempi di utilizzo

La funzionalità di esportazione può essere usata in diversi modi. Ecco alcuni esempi:

  • Pulsante di invio alla stampa: creare un pulsante nell'applicazione che, se selezionato, attiva un processo di esportazione. Il processo può esportare il report visualizzato come .pdf o un .pptx. Al termine, l'utente può ricevere il file come download. Usando i parametri del report e le impostazioni del formato è possibile esportare il report in uno stato specifico, inclusi i dati filtrati, le dimensioni di pagina personalizzate e altre impostazioni specifiche del formato. Poiché l'API è asincrona, potrebbe essere necessario attendere qualche minuto prima che il file sia disponibile.

  • Allegato di posta elettronica: inviare un messaggio di posta elettronica automatizzato a intervalli prestabiliti con un report PDF allegato. Questo scenario può essere utile se si vuole automatizzare l'invio di un report settimanale ai dirigenti.

Uso dell'API

Requisiti di licenza

Rendering di eventi

Per assicurarsi che l'esportazione non inizi prima che il rendering dell'oggetto abbia terminato il rendering, usare l'API degli eventi "Rendering" e iniziare l'esportazione solo al termine del rendering.

Polling

L'API è asincrona. Quando viene chiamata l'API exportToFile, viene attivato un processo di esportazione. Dopo l'attivazione di un processo di esportazione, usare il polling per tenere traccia del processo fino al suo completamento.

Al termine dell'esportazione, la chiamata API di polling restituisce un URL di Power BI per recuperare il file. L'URL è disponibile per 24 ore.

Funzionalità supportate

Impostazioni del formato

Specificare varie impostazioni per ogni formato di file. Le proprietà e i valori supportati sono equivalenti ai parametri delle informazioni sul dispositivo per i parametri URL del report impaginato.

Ecco due esempi. Il primo consiste nell'esportare le prime quattro pagine di un report usando le dimensioni della pagina del report in un file .pptx. Il secondo esempio consiste nell'esportare la terza pagina di un report in un file con estensione jpeg.

Esportazione delle prime quattro pagine in un file con estensione pptx

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

Esportazione della terza pagina in un file con estensione jpeg

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

Parametri di report

È possibile usare l'API exportToFile per esportare un report a livello di codice con un set di parametri del report. Questa operazione viene eseguita usando le funzionalità dei parametri del report.

Di seguito è riportato un esempio per l'impostazione dei valori dei parametri del report.

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

Autenticazione

È possibile eseguire l'autenticazione con un utente (o utente master) o un'entità servizio.

Sicurezza a livello di riga

Quando si usa un modello semantico di Power BI con la sicurezza a livello di riga definita come origine dati, è possibile esportare un report che mostra i dati visibili solo a determinati utenti. Se ad esempio si esporta un report sulle vendite definito con ruoli regionali, è possibile filtrare il report a livello di codice in modo che venga visualizzata solo una determinata area.

Per eseguire l'esportazione usando la sicurezza a livello di riga, è necessaria l'autorizzazione di lettura per il modello semantico di Power BI usato dal report come origine dati.

Di seguito è riportato un esempio che specifica un nome utente efficace per la sicurezza a livello di riga.

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

Single Sign-On SQL e Dataverse (SSO)

In Power BI è possibile impostare OAuth con SSO. Quando si esegue questa operazione, le credenziali per l'utente che visualizza il report vengono usate per recuperare i dati. Il token di accesso nell'intestazione della richiesta non viene usato per accedere ai dati. Il token deve essere passato con l'identità effettiva nel corpo del post.

Il recupero del token di accesso corretto per la risorsa a cui si vuole accedere può talvolta risultare complicato.

  • Per Azure SQL, la risorsa è https://database.windows.net.
  • Per Dataverse, la risorsa è l'indirizzo https:// per l'ambiente. Ad esempio: https://contoso.crm.dynamics.com.

Accedere all'API del token usando il metodo AuthenticationContext.AcquireTokenAsync.

Ecco un esempio per fornire un'identità effettiva (nome utente) con un token di accesso.

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

Richieste simultanee

exportToFile supporta un numero limitato di richieste simultanee. Il numero massimo di richieste di rendering di report impaginati simultanee è 500. Per evitare di superare il limite e ottenere un errore per troppe richieste (429), distribuire il carico nel tempo o tra le capacità.

Con Premium per utente (PPU), l'API exportToFile consente solo una richiesta in una finestra di cinque minuti. Più richieste nella finestra di cinque minuti causeranno l'errore Troppe richieste (429).

Esempi di codice

Il Power BI API SDK usato negli esempi di codice può essere scaricato qui.

Quando si crea un processo di esportazione, è necessario seguire tre passaggi:

  1. Invio di una richiesta di esportazione.
  2. Polling.
  3. Recupero del file.

Questa sezione presenta esempi per ogni passaggio.

Passaggio 1: invio di una richiesta di esportazione

Il primo passaggio consiste nell'invio di una richiesta di esportazione. In questo esempio viene inviata una richiesta di esportazione per un intervallo di pagine, dimensioni e valori dei parametri del report specifici.

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

Passaggio 2: polling

Dopo aver inviato una richiesta di esportazione, usare il polling per definire quando il file di esportazione che si sta aspettando è pronto.

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

Passaggio 3: recupero del file

Quando il polling restituisce un URL, usare questo esempio per recuperare il file ricevuto.

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

Esempio end-to-end

Ecco un esempio end-to-end per l'esportazione di un report. Questo esempio include le fasi seguenti:

  1. Invio della richiesta di esportazione.
  2. Polling.
  3. Recupero del file.
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;
    }
}

Considerazioni e limitazioni

  • L'esportazione di un report impaginato con un modello semantico di Power BI come origine dati non è supportato nei casi seguenti:

    • Il chiamante è un profilo dell'entità servizio.
    • Una delle origini dati del modello semantico è configurata con l'accesso Single Sign-On (SSO) abilitato e viene fornita un'identità efficace.
    • Il modello semantico di Power BI include DirectQuery in Azure Analysis Services o in un altro modello semantico di Power BI ed è stata fornita un'identità efficace.

  • L'esportazione di un report impaginato con origine dati di Azure Analysis Services configurata con l'accesso Single Sign-On (SSO) abilitato non è supportata nei casi seguenti:

  • Per esportare un report impaginato con un'identità effettiva, il nome utente deve essere un utente esistente da Microsoft Entra ID del tenant.

  • L'esportazione di un report è limitata a 60 minuti, che corrispondono alla durata del token di accesso utente. Se si verifica un errore di timeout oltre i 60 minuti durante l'esportazione di grandi quantità di dati, è consigliabile ridurre la quantità di dati usando filtri appropriati.

  • Il collegamento ipertestuale dell'URL di condivisione file (percorso /UNC di condivisione file) non funziona quando si esporta un report impaginato pubblicato nel servizio Power BI online.

Contenuto correlato

Vedere come incorporare contenuto per i clienti e l'organizzazione: