Condividi tramite

Esportare report di Power BI in un file

  • Articolo

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

  • PPTX (PowerPoint)
  • PDF
  • .png
    • Quando si esporta in un file PNG, un report con più pagine viene compresso in un file ZIP
    • Ogni file all'interno del file ZIP rappresenta una pagina del report
    • I nomi di pagina corrispondono ai valori restituiti delle API Get Pages o Get Pages in Group

Nota

L'esportazione di un report di Power BI in un file tramite l'API exportToFile non è supportata per Premium per utente (PPU).

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. Con i segnalibri è possibile esportare il report in uno stato specifico, inclusi i filtri configurati, i filtri dei dati e altre impostazioni. 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. Per altre informazioni, vedere Esportare un report di Power BI e inviarlo via posta elettronica con Power Automate

Uso dell'API

Requisiti di licenza

  • Il report esportato deve trovarsi in un'area di lavoro supportata da una capacità Premium, Incorporata o Infrastruttura.
  • L'API exportToFile è non supportata per Premium per utente (PPU).

Impostazioni dell'amministratore

Prima di usare l'API, verificare che siano abilitate le impostazioni del tenant amministratore seguenti:

  • Esporta report come presentazioni di PowerPoint o documenti PDF: abilitata per impostazione predefinita.
  • Esporta report come file di immagine: impostazione obbligatoria solo per i file PNG e disabilitata per impostazione predefinita.

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.

Durante il polling, l'API restituisce un numero che rappresenta la quantità di lavoro completata. Il lavoro in ogni processo di esportazione viene calcolato in base al totale delle esportazioni nel processo. Un'esportazione include l'esportazione di un singolo oggetto visivo o una pagina con o senza segnalibri. Tutte le esportazioni hanno lo stesso peso. Se ad esempio il processo di esportazione include l’esportazione di un report di 10 pagine e il polling restituisce 70, significa che l'API ha elaborato 7 delle 10 pagine del processo di esportazione.

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

In questa sezione viene descritto come usare le funzionalità supportate seguenti:

Selezione delle pagine da stampare

Specificare le pagine da stampare in base al valore restituito dalle API Get Pages o Get Pages in Group. È anche possibile specificare l'ordine delle pagine esportate.

Esportazione di una pagina o di un singolo oggetto visivo

È possibile specificare una pagina o un singolo oggetto visivo da esportare. Le pagine possono essere esportate con o senza segnalibri.

A seconda del tipo di esportazione, è necessario passare attributi diversi all'oggetto ExportReportPage. Nella tabella seguente vengono specificati gli attributi necessari per ogni processo di esportazione.

Nota

L'esportazione di un singolo oggetto visivo ha lo stesso peso dell'esportazione di una pagina (con o senza segnalibri). Ciò significa che in termini di calcoli di sistema, entrambe le operazioni portano lo stesso valore.

Attributo Pagina Oggetto visivo singolo Commenti
bookmark Facoltativo Non si applica a. Usare per esportare una pagina in uno stato specifico
pageName Si applica a. Si applica a. Usare l'API REST GetPages o l'getPages API client.
visualName Non si applica a. Si applica a. Esistono due modi per ottenere il nome dell'oggetto visivo:
  • Usare l'getVisuals API client.
  • Ascoltare e registrare l'evento visualClicked, che si attiva quando viene selezionato un oggetto visivo. Per altre informazioni, vedere Come gestire gli eventi
    • .

    Bookmarks

    I segnalibri possono essere usati per salvare un report in una configurazione specifica, inclusi i filtri applicati e lo stato degli oggetti visivi del report. È possibile usare l'API exportToFile per esportare a livello di codice il segnalibro di un report, in due modi:

    • Esportare un segnalibro esistente

      Per esportare un segnalibro di report esistente, usare la proprietà name, un identificatore univoco (con distinzione tra maiuscole/minuscole) che è possibile ottenere usando l'API JavaScript dei segnalibri.

    • Esportare lo stato del report

      Per esportare lo stato corrente del report, usare la proprietà state. Ad esempio, è possibile usare il metodo bookmarksManager.capture del segnalibro per acquisire le modifiche apportate da un utente specifico a un report e quindi esportarlo nello stato corrente usando capturedBookmark.state.

    Nota

    I segnalibri personali e i filtri permanenti non sono supportati.

    Filtri

    Se si usa reportLevelFilters in PowerBIReportExportConfiguration, è possibile esportare un report in una condizione filtrata.

    Per esportare un report filtrato, inserire i parametri della stringa di query dell'URL che si vuole usare come filtro in ExportFilter. Quando si immette la stringa, è necessario rimuovere la parte ?filter= del parametro di query dell'URL.

    La tabella include alcuni esempi di sintassi delle stringhe che è possibile passare a ExportFilter.

    Filtro Sintassi Esempio
    Un valore in un campo Table/Field eq 'value' Store/Territory eq 'NC'
    Più valori in un campo Table/Field in ('value1', 'value2') Store/Territory in ('NC', 'TN')
    Un valore distinct in un campo e un valore distinct diverso in un altro campo Table/Field1 eq 'value1' and Table/Field2 eq 'value2' Store/Territory eq 'NC' and Store/Chain eq 'Fashions Direct'

    Autenticazione

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

    Sicurezza a livello di riga

    Con la sicurezza a livello di riga è possibile esportare un report in cui sono visualizzati 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 esportare con la sicurezza a livello di riga, è necessario avere le autorizzazioni seguenti:

    • Autorizzazioni di scrittura e ricondivisione per il modello semantico a cui è connesso il report
    • Membro o amministratore dell'area di lavoro in cui risiede il report

    Protezione dei dati

    I formati PDF e PPTX supportano le etichette di riservatezza. Se si esporta un report con un'etichetta di riservatezza in un file PDF o PPTX, il file esportato visualizza il report con la relativa etichetta di riservatezza.

    Un report con un'etichetta di riservatezza non può essere esportato in un file PDF o PPTX usando un'entità servizio.

    Localizzazione

    Quando si usa l'API exportToFile, è possibile passare le impostazioni internazionali desiderate. Le impostazioni di localizzazione influiscono sul modo in cui viene visualizzato il report, ad esempio modificando la formattazione in base alle impostazioni internazionali selezionate.

    Associazione dinamica

    Per esportare un report quando è collegato a un modello semantico diverso da quello predefinito, specificare l'ID del set di dati richiesto nel parametro datasetToBind quando si chiama l'API. Altre informazioni sull'associazione dinamica.

    Richieste simultanee

    L'API exportToFile supporta un numero limitato di richieste simultanee. Il numero massimo di richieste simultanee supportate è di 500 per capacità. Per evitare di superare il limite e ottenere un errore per troppe richieste (429), distribuire il carico nel tempo o tra le capacità. Vengono elaborate simultaneamente solo cinque pagine di un report. Ad esempio, se si esporta un report con 50 pagine, il processo di esportazione viene elaborato in 10 intervalli sequenziali. Quando si ottimizza il processo di esportazione, è consigliabile prendere in considerazione l'esecuzione di alcuni processi in parallelo.

    Esempi di codice

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

    1. Invio di una richiesta di esportazione.
    2. Polling.
    3. Recupero del file.
    4. Uso del flusso di 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 una pagina specifica.

    private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId,
    FileFormat format,
    IList<string> pageNames = null, /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
    var powerBIReportExportConfiguration = new PowerBIReportExportConfiguration
    {
        Settings = new ExportReportSettings
        {
            Locale = "en-us",
        },
        // Note that page names differ from the page display names
        // To get the page names use the GetPages REST API
        Pages = pageNames?.Select(pn => new ExportReportPage(Name = pn)).ToList(),
        // ReportLevelFilters collection needs to be instantiated explicitly
        ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

    };

    var exportRequest = new ExportReportRequest
    {
        Format = format,
        PowerBIReportConfiguration = powerBIReportExportConfiguration,
    };

    // The 'Client' object is an instance of the Power BI .NET SDK
    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<HttpOperationResponse<Export>> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the PostExportRequest response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    HttpOperationResponse<Export> httpMessage = null;
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int c_secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations 
            return null;
        }

        // The 'Client' object is an instance of the Power BI .NET SDK
        httpMessage = await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
        exportStatus = httpMessage.Body;

        // You can track the export progress using the PercentComplete that's part of the response
        SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(), exportStatus.PercentComplete);
        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 not always populated
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;
            await Task.Delay(retryAfterInSec * c_secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return httpMessage;
}

    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 PollExportRequest response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        // The 'Client' object is an instance of the Power BI .NET SDK
        var fileStream = await Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
        return new ExportedFile
        {
            FileStream = fileStream,
            FileSuffix = export.ResourceFileExtension,
        };
    }
    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string FileSuffix;
}

    Passaggio 4: Uso del flusso di file

    Quando si ha il flusso di file, è possibile gestirlo nel modo più adatto alle proprie esigenze. Ad esempio è possibile inviarlo in un messaggio di posta elettronica o usarlo per scaricare i report esportati.

    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> ExportPowerBIReport(
	Guid reportId,
	Guid groupId,
	FileFormat format,
	int pollingtimeOutInMinutes,
	CancellationToken token,
	IList<string> pageNames = null,  /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
	const int c_maxNumberOfRetries = 3; /* Can be set to any desired number */
	const int c_secToMillisec = 1000;
	try
	{
		Export export = null;
		int retryAttempt = 1;
		do
		{
			var exportId = await PostExportRequest(reportId, groupId, format, pageNames, urlFilter);
			var httpMessage = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
			export = httpMessage.Body;
			if (export == null)
			{
				// Error, failure in exporting the report
				return null;
			}
			if (export.Status == ExportState.Failed)
			{
				// Some failure cases indicate that the system is currently busy. The entire export operation can be retried after a certain delay
				// In such cases the recommended waiting time before retrying the entire export operation can be found in the RetryAfter header
				var retryAfter = httpMessage.Response.Headers.RetryAfter;
				if(retryAfter == null)
				{
				    // Failed state with no RetryAfter header indicates that the export failed permanently
				    return null;
                }

                var retryAfterInSec = retryAfter.Delta.Value.Seconds;
                await Task.Delay(retryAfterInSec * c_secToMillisec);
            }
        }
        while (export.Status != ExportState.Succeeded && retryAttempt++ < c_maxNumberOfRetries);

        if (export.Status != ExportState.Succeeded)
        {
            // Error, failure in exporting the report
            return null;
        }

        var exportedFile = await GetExportedFile(reportId, groupId, export);

        // Now you have the exported file stream ready to be used according to your specific needs
        // For example, saving the file can be done as follows:
        /*
            var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;

            using (var fileStream = File.Create(pathOnDisk))
            {
                exportedFile.FileStream.CopyTo(fileStream);
            }
        */

        return exportedFile;
    }
    catch
    {
        // Error handling
        throw;
    }
}

    Considerazioni e limitazioni

    • Il carico dell'operazione API di esportazione viene valutato come un’operazione in background a esecuzione lenta, come descritto nella valutazione del carico della capacità Premium.
    • Tutti i modelli semantici correlati nel report da esportare devono risiedere in una capacità Premium o Incorporata, inclusi i modelli semantici con una connessione Direct Query.
    • I report esportati non possono avere una dimensione file superiore a 250 MB.
    • Quando si esegue l'esportazione in formato PNG, le etichette di riservatezza non sono supportate.
    • Il numero di esportazioni (singoli oggetti visivi o pagine di report) che possono essere inclusi in un singolo report esportato è 50 (esclusa l'esportazione di report impaginati). Se la richiesta include più esportazioni, l'API restituisce un errore e il processo di esportazione viene annullato.
    • Isegnalibri personali e i filtri permanenti non sono supportati per l'esportazione di report di Power BI nel file.
    • L'API exportToFile esporta il report con il valore predefinito se usato senza segnalibri o reportLevelFilters.
    • L'esportazione di un report di Power BI connesso a uno o più modelli semantici compositi, che dispone di almeno un'origine dati esterna con l'accesso Single Sign-On (SSO) abilitato, non è supportata. Durante l'esportazione, gli oggetti visivi potrebbero non essere visualizzati correttamente.
    • Gli oggetti visivi di Power BI elencati qui non sono supportati. Quando viene esportato un report contenente questi oggetti visivi, il rendering delle parti del report che contengono tali oggetti visivi non viene eseguito correttamente e viene visualizzato un simbolo di errore.
      • Visualizzazioni personalizzate di Power BI non certificate
      • Oggetti visivi R
      • PowerApps
      • Oggetti visivi Python
      • Power Automate
      • Oggetto visivo del report impaginato
      • Visio
      • Oggetti visivi ArcGIS

    Contenuto correlato

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

    Altre domande? Provare la Community di Power BI