Leggere in inglese

Condividi tramite

Esportare un report impaginato in un file

  • Articolo

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

  • .pptx (PowerPoint)

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

  • .xlsx (Excel)

  • .docx (Word)

  • .csv

  • .xml

  • .mhtml

  • immagine
    Quando si esporta in un'immagine, impostare il formato dell'immagine tramite l'impostazione di formato OutputFormat. I valori OutputFormat supportati sono:

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

Esempi di utilizzo

È possibile usare la funzionalità di esportazione in vari modi. Ecco alcuni esempi:

  • pulsante Invia a stampa: nell'applicazione creare un pulsante che quando si fa clic su 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 di formato, è possibile esportare il report in uno stato specifico, inclusi dati filtrati, dimensioni di pagina personalizzate e altre impostazioni specifiche del formato. Poiché l'API è asincrona, la disponibilità del file potrebbe richiedere del tempo.

  • allegato di posta elettronica: inviare un messaggio di posta elettronica automatizzato a intervalli impostati, 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

Eventi di rendering

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

Sondaggio

L'API è asincrona. Quando viene chiamata l'API exportToFile, attiva un processo di esportazione. Dopo aver attivato un processo di esportazione, utilizzare per l'interrogazione e tenere traccia del processo fino al suo completamento.

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

Funzionalità supportate

Impostazioni di formato

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

Ecco due esempi. La prima 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 di .jpeg.

Esportazione delle prime quattro pagine in un .pptx

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

Esportazione della terza pagina in un .jpeg

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

Parametri del 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 utilizzando le capacità del parametro del report .

Ecco un esempio per l'impostazione dei valori dei parametri del report.

JSON 
{
      "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 usando un utente (o un utente master) o un principale del servizio .

Sicurezza a livello di riga

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

Per esportare utilizzando RLS, devi avere l'autorizzazione di lettura per il modello semantico di Power BI usato dal report come origine dati.

Ecco un esempio di fornire un nome utente efficace per RLS.

JSON 
{
      "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:// del tuo 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.

JSON 
{
       "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

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

Con premium per utente (PPU), l'API exportToFile consente solo una richiesta di in una finestra di cinque minuti. Più richieste all'interno della finestra di cinque minuti generano un errore di troppe richieste (429).

Esempi di codice

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

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

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

In questa sezione vengono forniti esempi per ogni passaggio.

Passaggio 1: invio di una richiesta di esportazione

Il primo passaggio consiste nell'inviare 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.

C# 
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, utilizzare il polling per identificare quando il file di esportazione che stai aspettando è pronto.

C# 
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 ottenere il file ricevuto.

C# 
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 completo

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

  1. Invio della richiesta di esportazione.
  2. sondaggio.
  3. Ottenimento del file.
C# 
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 Single Sign-On (SSO) abilitato ed è stata fornita un'identità effettiva.
    • Il modello semantico di Power BI include DirectQuery ad Azure Analysis Services o a 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:

    • Il chiamante è un profilo dell'entità servizio.
    • Il chiamante è un utente master e è stata fornita un'identità efficace.

  • Per esportare un report impaginato con un'identità verificata, il nome utente deve essere un utente esistente all'interno dell'ID Microsoft Entra del tuo tenant.

  • L'esportazione di un report è limitata a 60 minuti, che corrisponde alla durata del token di accesso utente. Se si verifica un errore di timeout oltre il contrassegno di 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 di condivisione file/UNC) non funziona correttamente quando si esporta un report impaginato pubblicato sul servizio Power BI online.

Contenuto correlato

Esaminare come incorporare contenuti per i clienti e l'organizzazione: