Exportación de un informe de Power BI a un archivo

Artículo
12/19/2023

La API exportToFile permite exportar un informe de Power BI mediante una llamada REST. Se admiten los siguientes formatos de archivo:

.pptx (PowerPoint)
.pdf
.png
- Al exportar a un archivo .png, un informe de varias páginas se comprime en un archivo ZIP.
- Cada archivo del archivo ZIP representa una página del informe
- Los nombres de página son los mismos que los valores devueltos de las API Obtener páginas u Obtener páginas en grupo

Nota:

No se admite la exportación de un informe de Power BI a un archivo mediante la API exportToFile para Premium por usuario (PPU).

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. Mediante marcadores, puede exportar el informe en un estado específico, incluidos filtros configurados, segmentaciones y otras configuraciones. 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. Para más información, consulte Exportación y envío por correo electrónico de un informe de Power BI con Power Automate.

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 exportToFileno es compatible con Premium por usuario (PPU).

Configuración de administrador

Antes de usar la API, compruebe que las siguientes configuraciones de inquilinos del administrador estén habilitadas:

Exportación de informes como presentaciones de PowerPoint o documentos PDF: habilitada de forma predeterminada.
Exportación de informes como archivos de imagen: se requiere solo para .png y está deshabilitada de forma predeterminada.

"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 eventos "Rendering" 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.

Durante el sondeo, la API devuelve un número que representa la cantidad de trabajo completado. El progreso de cada trabajo de exportación se calcula en función del número total de exportaciones que tenga ese trabajo. Un trabajo de exportación incluye la exportación de un solo objeto visual, o una página con o sin marcadores. Todas las exportaciones tienen el mismo peso. Si, por ejemplo, el trabajo de exportación incluye la exportación de un informe con 10 páginas, y el sondeo devuelve 70, significa que la API ha procesado 7 de las 10 páginas en el trabajo de exportación.

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

En esta sección se describe cómo usar las siguientes características admitidas:

Selección de páginas para imprimir
Exportación de una página o un solo objeto visual
Marcadores
Filtros
Autenticación
Seguridad de nivel de fila (RLS)
Protección de datos
Localización
Enlace dinámico

Selección de páginas para imprimir

Especifique las páginas que desea imprimir conforme al valor devuelto de Obtener páginas u Obtener páginas en grupo. También puede especificar el orden de las páginas que está exportando.

Exportación de una página o un solo objeto visual

Puede especificar una página o un solo objeto visual para que se exporte. Las páginas se pueden exportar con o sin marcadores.

Dependiendo del tipo de exportación, deberá pasar atributos diferentes al objeto ExportReportPage. En la tabla siguiente se especifican los atributos necesarios para cada trabajo de exportación.

Nota:

Exportar un solo objeto visual tiene el mismo peso que exportar una página (con o sin marcadores). Esto significa que, en cuanto a los cálculos del sistema, ambas operaciones tienen el mismo valor.

Atributo	Página	Comentarios
`bookmark`	Opcional	Úselo para exportar una página con un estado específico.
`pageName`		Use la API REST GetPages o la `getPages`API de cliente.
`visualName`		Hay dos maneras de obtener el nombre del objeto visual: Use la `getVisuals`API de cliente. Escuchar y registrar el evento visualClicked, que se desencadena cuando se selecciona un objeto visual. Para obtener más información, consulte Procedimiento para controlar eventos. .

Marcadores

Los marcadores pueden usarse para guardar un informe en una configuración específica, incluidos los filtros aplicados y el estado de los objetos visuales del informe. Puede usar la API exportToFile para exportar mediante programación el marcador de un informe de dos maneras:

Exportar un marcador existente

Para exportar un marcador de informe existente, use la propiedad name, un identificador único (con distinción entre mayúsculas y minúsculas) que puede obtener mediante la API de JavaScript de los marcadores.
Exportar el estado del informe

Para exportar el estado actual del informe, use la propiedad state. Por ejemplo, puede usar el método bookmarksManager.capture del marcador para capturar los cambios que un usuario específico realizó en un informe y luego exportarlo en su estado actual mediante capturedBookmark.state.

Nota

Los marcadores personales y los filtros persistentes no se admiten.

Filtros

Con reportLevelFilters en PowerBIReportExportConfiguration, puede exportar un informe con un condición filtrada.

Para exportar un informe filtrado, inserte los parámetros de cadena de consulta de URL que quiere usar como filtro en ExportFilter. Cuando escriba la cadena, debe quitar la parte ?filter= del parámetro de consulta de URL.

En la tabla se incluyen algunos ejemplos de sintaxis de cadenas que puede pasar a ExportFilter.

Filter	Sintaxis	Ejemplo
Un valor en un campo	Table/Field eq 'value'	Store/Territory eq 'NC'
Varios valores en un campo	Table/Field in ('value1', 'value2')	Store/Territory in ('NC', 'TN')
Un valor distinto en un campo y un valor distinto diferente en otro campo	Table/Field1 eq 'value1' y Table/Field2 eq 'value2'	Store/Territory eq 'NC' y Store/Chain eq 'Fashions Direct'

Authentication

Se puede autenticar mediante un usuario (o usuario maestro), o bien una entidad de servicio.

Seguridad de nivel de fila (RLS)

Con la seguridad de nivel de fila (RLS), puede exportar un informe que muestra datos que solo son visibles para ciertos usuarios. 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 realizar la exportación mediante la seguridad de nivel de fila, debe tener los siguientes permisos:

Permisos para escribir y volver a compartir para el modelo semántico al que está conectado el informe.
Miembro del área de trabajo o administrador del área de trabajo donde reside el informe

Protección de datos

Los formatos .pdf y .pptx admiten etiquetas de confidencialidad. Si exporta un informe con una etiqueta de confidencialidad a un archivo .pdf o .pptx, el archivo exportado mostrará el informe con su etiqueta de confidencialidad.

Un informe con una etiqueta de confidencialidad no se puede exportar a un archivo .pdf o .pptx mediante una entidad de servicio.

Localización

Al usar la API exportToFile, puede pasar su configuración regional deseada. La configuración de localización afecta a la forma en que se muestra el informe, por ejemplo, cambiando el formato conforme a la localización seleccionada.

Enlace dinámico

Para exportar un informe mientras está conectado a un modelo semántico que no es el predeterminado, especifique el identificador de conjunto de datos necesario en el parámetro datasetToBind al llamar a la API. Más información sobre el enlace dinámico.

Solicitudes simultáneas

La API exportToFile admite un número limitado de solicitudes simultáneas. El número máximo de solicitudes simultáneas admitidas es 500 por capacidad. 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. Solo cinco páginas de un informe se procesan simultáneamente. Por ejemplo, si va a exportar un informe con 50 páginas, el trabajo de exportación se procesará en 10 intervalos secuenciales. Al optimizar el trabajo de exportación, puede considerar la posibilidad de ejecutar algunos trabajos en paralelo.

Ejemplos de código

Cuando crea un trabajo de exportación, hay cuatro pasos que se deben seguir:

Envío de una solicitud de exportación.
Sondeo.
Obtención del archivo.
Uso de la secuencia de 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 una página específica.

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

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

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

Paso 4: uso de la secuencia de archivo

Cuando tenga la secuencia de archivo, puede administrarla de la manera que mejor se adapte a sus necesidades. Por ejemplo, puede enviarla por correo electrónico o usarla para descargar los informes exportados.

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:

Envío de la solicitud de exportación.
Sondeo.
Obtención del archivo.

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

Consideraciones y limitaciones

Una carga de operación de la API de exportación se evaluará como una operación en segundo plano de ejecución lenta, como se describe en Evaluación de la carga de capacidad Premium.
Todos los modelos semánticos relacionados del informe que va a exportar deben residir en una capacidad Premium o Embedded, incluidos los modelos semánticos con una conexión de Direct Query.
Los informes exportados no pueden tener un tamaño superior a 250 MB.
Al exportar a .png, no se admiten las etiquetas de confidencialidad.
El número de exportaciones (objetos visuales o páginas de informe individuales) que se pueden incluir en un informe exportado es de 50 (sin incluir la exportación de informes paginados). Si la solicitud incluye más exportaciones, la API devuelve un error y el trabajo de exportación se cancela.
Los marcadores personales y los filtros persistentes no se admiten para la exportación de informes de Power BI al archivo.
La API exportToFile exportará el informe con el valor predeterminado si se utiliza sin marcadores ni reportLevelFilters.
Los objetos visuales de Power BI que se enumeran a continuación no se admiten. Cuando se exporta un informe que contiene estos objetos visuales, las partes del informe que los contienen no se representarán y mostrarán un símbolo de error.
- Objetos visuales personalizados de Power BI sin certificar
- Objetos visuales de R
- PowerApps
- Objetos visuales de Python
- Power Automate
- Elemento visual de informe paginado
- Visio
- Objetos visuales de ArcGIS

Revise cómo insertar contenido para sus clientes y su organización:

¿Tiene más preguntas? Consulte a la Comunidad de Power BI.