Esportare un report impaginato in un file
L'API exportToFile consente di esportare un report impaginato di Power BI usando 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 esporta in un'immagine, impostare il formato dell'immagine tramite l'impostazione delOutputFormatformato. I valori supportatiOutputFormatsono:- .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 alla 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 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, 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 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
- Il report esportato deve trovarsi in un'area di lavoro supportata da una capacità Premium, Incorporata o Infrastruttura.
- L'API
exportToFileha un supporto limitato in Premium per utente (PPU).
Eventi di rendering
Per assicurarsi che l'esportazione non inizi prima che l'oggetto visivo finisca il rendering, usare l'API eventi "Rendering" e iniziare l'esportazione solo al termine del rendering.
Polling
L'API è asincrona. Quando viene chiamata l'API exportToFile , attiva un processo di esportazione. Dopo aver attivato un processo di esportazione, usare il polling per tenere traccia del processo fino al 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 ai parametri Device Info per i parametri URL del report impaginati.
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 con estensione 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 pptx
{
"format": "PPTX",
"paginatedReportConfiguration":{
"formatSettings":{
"UseReportPageSize": "true",
"StartPage": "1",
"EndPage": "4"
}
}
}
Esportazione della terza pagina in un file 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.
Ecco 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 usando un utente (o un utente master) o un'entità 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 usando la sicurezza a livello di riga, è necessario disporre dell'autorizzazione di lettura per il modello semantico di Power BI usato dal report come origine dati.
Di seguito è riportato un esempio di specificare 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 per l'ambiente
https://. 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 del report impaginato simultanee è 500. Per evitare di superare il limite e ottenere un errore troppi richieste (429), distribuire il carico nel tempo o tra le capacità.
Con Premium per utente (PPU), l'API exportToFile consente una sola richiesta in una finestra di cinque minuti. Più richieste all'interno della finestra di cinque minuti generano un errore Troppi richieste (429).
Esempi di codice
Il API Power BI SDK usato negli esempi di codice può essere scaricato qui.
Quando si crea un processo di esportazione, è necessario eseguire tre passaggi:
- Invio di una richiesta di esportazione.
- Polling.
- 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.
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 identificare quando il file di esportazione in attesa è 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 ottenere 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
Questo è un esempio end-to-end per l'esportazione di un report. Questo esempio include le fasi seguenti:
- Invio della richiesta di esportazione.
- Polling.
- 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 e è 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à effettiva, il nome utente deve essere un utente esistente dall'ID Microsoft Entra del 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 /UNC) non funziona quando si esporta un report impaginato pubblicato in servizio Power BI online.
Contenuto correlato
Esaminare come incorporare contenuti per i clienti e l'organizzazione:
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per