Exportación de un informe paginado a un archivo
La API exportToFile permite exportar un informe paginado de Power BI mediante una llamada REST. Se admiten los siguientes formatos de archivo:
.pptx (PowerPoint)
.pdf (y PDF accesible o PDF/UA)
.xlsx (Excel)
.docx (Word)
.csv
.xml
.mhtml
Imagen
Al exportar a una imagen, establezca el formato de la imagen mediante la configuración de formatoOutputFormat. Los valores admitidos deOutputFormatson:- .tiff (valor predeterminado)
- .bmp
- .emf
- .gif
- .jpeg
- .png
Ejemplos de uso
Puede usar la característica de exportación de varias maneras. Estos son algunos ejemplos:
Botón Enviar para imprimir: en la aplicación, cree un botón que, al hacer clic en él, desencadene un trabajo de exportación. El trabajo puede exportar el informe visto como archivo .pdf o .pptx. Una vez completado, el usuario puede recibir el archivo como descarga. Con los parámetros de informe y la configuración de formato, puede exportar el informe en un estado específico, incluidos los datos filtrados, los tamaños de página personalizados y otros valores de formato específicos. Como la API es asincrónica, el archivo puede tardar un tiempo en estar disponible.
Datos adjuntos de correo electrónico: envíe un correo electrónico automatizado a intervalos establecidos, con un informe .pdf adjunto. Este escenario puede ser útil si desea automatizar el envío de un informe semanal a los ejecutivos.
Uso de la API
Requisitos de licencia
- El informe que va a exportar debe residir en un área de trabajo respaldada por una capacidad Premium, Embedded o Fabric.
- La API de
exportToFiletiene compatibilidad limitada en Premium por usuario (PPU).
Representación de eventos
Para asegurarse de que la exportación no empieza antes de que termine la representación del objeto visual, use la API de “representación” de eventos e inicie la exportación solo cuando haya finalizado la representación.
Sondeo
La API es asincrónica. Cuando se llama a la API exportToFile, se desencadena un trabajo de exportación. Después de activar un trabajo de exportación, use el sondeo para realizar un seguimiento del trabajo, hasta que se complete.
Cuando se completa la exportación, la llamada API de sondeo devuelve una dirección URL de Power BI para obtener el archivo. La dirección URL está disponible durante 24 horas.
Características admitidas
Configuración de formato
Especificar distintas configuraciones de formato para cada formato de archivo. Las propiedades y los valores admitidos son equivalentes a los parámetros de información del dispositivo para los parámetros de dirección URL del informe paginado.
Estos son dos ejemplos. El primero consiste en exportar las cuatro primeras páginas de un informe con el tamaño de página de informe a un archivo .pptx. El segundo ejemplo es para exportar la tercera página de un informe a un archivo .jpeg.
Exportación de las cuatro primeras páginas a un archivo .pptx
{
"format": "PPTX",
"paginatedReportConfiguration":{
"formatSettings":{
"UseReportPageSize": "true",
"StartPage": "1",
"EndPage": "4"
}
}
}
Exportar de la tercera página a un archivo .jpeg
{
"format": "IMAGE",
"paginatedReportConfiguration":{
"formatSettings":{
"OutputFormat": "JPEG",
"StartPage": "3",
"EndPage": "3"
}
}
}
Parámetros de informe
Puede usar la API exportToFile para exportar mediante programación un informe con un conjunto de parámetros de informe. Esto se realiza mediante funciones de parámetro de informe.
Este es un ejemplo para establecer los valores de los parámetros de informe.
{
"format": "PDF",
"paginatedReportConfiguration":{
"parameterValues":[
{"name": "State", "value": "WA"},
{"name": "City", "value": "Seattle"},
{"name": "City", "value": "Bellevue"},
{"name": "City", "value": "Redmond"}
]
}
}
Authentication
Se puede autenticar mediante un usuario (o usuario maestro), o bien una entidad de servicio.
Seguridad de nivel de fila (RLS)
Al usar un modelo semántico de Power BI en el que se ha definido la Seguridad de nivel de fila (RLS) como origen de datos, puede exportar un informe que muestre los datos que solo son visibles para usuarios concretos. Por ejemplo, si exporta un informe de ventas que está definido con roles regionales, puede filtrar dicho informe mediante programación para que solo se muestre una determinada región.
Para exportar mediante RLS, debe tener permiso de lectura para el modelo semántico de Power BI que el informe use como origen de datos.
Este es un ejemplo de cómo proporcionar un nombre de usuario efectivo para RLS.
{
"format": "PDF",
"paginatedReportConfiguration":{
"identities": [
{"username": "john@contoso.com"}
]
}
}
Inicio de sesión único en SQL y Dataverse (SSO)
En Power BI, tiene la opción de establecer OAuth con SSO. Al hacerlo, las credenciales del usuario que consulta el informe se usan para recuperar los datos. El token de acceso del encabezado de solicitud no se usa para acceder a los datos. El token se debe pasar con la identidad efectiva en el cuerpo de la publicación.
Obtener el token de acceso correcto para el recurso al que desea acceder a veces puede resultar complicado.
- En Azure SQL, el recurso es
https://database.windows.net. - En Dataverse, el recurso es la dirección
https://de su entorno. Por ejemplo,https://contoso.crm.dynamics.com.
Acceda a la API de tokens con el método AuthenticationContext.AcquireTokenAsync.
Este es un ejemplo de cómo proporcionar una identidad efectiva (nombre de usuario) con un token de acceso.
{
"format":"PDF",
"paginatedReportConfiguration":{
"formatSettings":{
"AccessiblePDF":"true",
"PageHeight":"11in",
"PageWidth":"8.5in",
"MarginBottom":"2in"
},
"identities":[
{
"username":"john@contoso.com",
"identityBlob": {
"value": "eyJ0eX....full access token"
}
}
]
}
}
Solicitudes simultáneas
El exportToFile admite un número limitado de solicitudes simultáneas. El número máximo de solicitudes de representación de informes paginados simultáneas es 500. Para evitar superar el límite y obtener un error de demasiadas solicitudes (429), distribuya la carga a lo largo del tiempo o entre capacidades.
Con Premium por usuario (PPU), la API exportToFile solo permite una solicitud en un período de cinco minutos. Si hay varias solicitudes en un período de cinco minutos, se produce un error de tipo Demasiadas solicitudes (429).
Ejemplos de código
El SDK de API de Power BI que se usa en los ejemplos de código se puede descargar aquí.
Cuando crea un trabajo de exportación, hay tres pasos que se deben seguir:
- Envío de una solicitud de exportación.
- Sondeo.
- Obtención del archivo.
En esta sección se proporcionan ejemplos para cada paso.
Paso 1: Envío de una solicitud de exportación
El primer paso es enviar una solicitud de exportación. En este ejemplo, se envía una solicitud de exportación para un intervalo de páginas concreto, un tamaño y valores de parámetro de informe.
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;
}
Paso 2: Sondeo
Después de enviar una solicitud de exportación, use el sondeo para identificar cuándo está listo el archivo de exportación que está esperando.
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;
}
Paso 3: Obtención del archivo
Una vez que el sondeo devuelve una dirección URL, use este ejemplo para obtener el archivo recibido.
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;
}
Ejemplo de un extremo a otro
Este es un ejemplo de un extremo a extremo para exportar un informe. Este ejemplo incluye las siguientes etapas:
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;
}
}
Consideraciones y limitaciones
No se admite en los siguientes casos la exportación de un informe paginado que tenga un modelo semántico de Power BI como su origen de datos:
- El autor de la llamada es un perfil de entidad de servicio.
- Uno de los orígenes de datos del modelo semántico está configurado con el inicio de sesión único (SSO) habilitado y se proporcionó una identidad efectiva.
- El modelo semántico de Power BI tiene DirectQuery para Azure Analysis Services o para otro modelo semántico de Power BI y se proporcionó una identidad efectiva.
La exportación de un informe paginado que tiene el origen de datos de Azure Analysis Services configurado con el inicio de sesión único (SSO) habilitado, no se admite en los casos siguientes:
- El autor de la llamada es un perfil de entidad de servicio.
- El autor de la llamada es un usuario maestro y se proporcionó una identidad efectiva.
Para exportar un informe paginado con una identidad efectiva, el nombre de usuario debe ser un usuario existente de una instancia de Microsoft Entra ID del inquilino.
La exportación de un informe se limita a 60 minutos, lo que coincide con la vida del token de acceso del usuario. Si recibe un error de tiempo de espera después de la marca del minuto 60 al exportar grandes cantidades de datos, considere recudir la cantidad de datos mediante los filtros adecuados.
El hipervínculo URL del recurso compartido de archivos (ruta de acceso UNC /recurso compartido de archivos) no funciona al exportar un informe paginado publicado en el servicio Power BI en línea.
Contenido relacionado
Revise cómo insertar contenido para sus clientes y su organización: