Exportación de un informe paginado al archivo

La API de 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 el valor de formato OutputFormat. Los valores de OutputFormat admitidos son:

  • .tiff (valor predeterminado)
  • .bmp
  • .emf
  • .gif
  • .jpeg
  • .png

Ejemplos de uso

Puede usar la característica de exportación de varias maneras. Estos son un par de ejemplos:

• botón Enviar para imprimir: en la aplicación, cree un botón que al hacer clic en desencadena un trabajo de exportación. El trabajo puede exportar el informe visto como archivo .pdf o .pptx. Cuando haya finalizado, 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 otras configuraciones específicas del formato. Dado que la API es asincrónica, el archivo puede tardar algún tiempo en estar disponible.

• Adjunto de correo electrónico - Envíe un correo electrónico automatizado a intervalos establecidos, con un informe adjunto .pdf. 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 exportToFile tiene compatibilidad limitada en Premium por usuario (PPU).

Representación de eventos

Para asegurarse de que la exportación no comienza antes de que el objeto visual termine de representarse, use la API de eventos de "Rendering" y solo inicie la exportación cuando finalice la representación.

Encuesta

La API es asincrónica. Cuando se llama a la API exportToFile, inicia 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 a la 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 compatibles

Configuración de formato

Especifique varias opciones de configuración 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. La primera consiste en exportar las cuatro primeras páginas de un informe mediante el tamaño de página del informe a un archivo .pptx. El segundo ejemplo es para exportar la tercera página de un informe a un archivo .jpeg.

Exportar las cuatro primeras páginas a un .pptx

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

Exportación de la tercera página a un .jpeg

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

Parámetros de informe

Puede usar la API de 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 valores de parámetros de informe.

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "parameterValues":[
                  {"name": "State", "value": "WA"},
                  {"name": "City", "value": "Seattle"},
                  {"name": "City", "value": "Bellevue"},
                  {"name": "City", "value": "Redmond"}
            ]
      }
}

Autenticación

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 que tenga seguridad de nivel de fila (RLS) definido como origen de datos, puede exportar un informe que muestre los datos que solo son visibles para determinados usuarios. Por ejemplo, si va a exportar un informe de ventas definido con roles regionales, puede filtrar mediante programación el informe 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 usa como origen de datos.

Este es un ejemplo de 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 ve el informe se usan para recuperar 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.

• Para Azure SQL, el recurso es https://database.windows.net.
• Para Dataverse, el recurso es la dirección https:// del entorno. Por ejemplo, https://contoso.crm.dynamics.com.

Acceda a la API del token mediante el método AuthenticationContext.AcquireTokenAsync.

Este es un ejemplo para 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 diferentes capacidades.

Con Premium por usuario (PPU), la API exportToFile solo permite una solicitud en un período de cinco minutos. Varias solicitudes dentro del período de cinco minutos producen un error de "Demasiadas Solicitudes" (429).

Ejemplos de código

El SDK de la API de Power BI que se usa en los ejemplos de código se puede descargar aquí.

Al crear un trabajo de exportación, hay tres pasos que debe seguir:

1. Enviar una solicitud de exportación.
2. Encuestas
3. 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, un tamaño y valores de parámetro de informe específicos.

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: obtener el 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 completo

Se trata de un ejemplo completo para exportar un informe. En este ejemplo se incluyen las siguientes fases:

1. Enviar la solicitud de exportación.
2. Sondeo.
3. Obtener el archivo.

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 la exportación de un informe paginado que tenga un modelo semántico de Power BI como origen de datos en los casos siguientes:

  • 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 utiliza DirectQuery para Azure Analysis Services u otro modelo semántico de Power BI, y se ha proporcionado una identidad eficaz.

• 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 del identificador de Microsoft Entra del inquilino.

• La exportación de un informe está limitada a 60 minutos, que coincide con la vida del token de acceso de usuario. Si recibe un error de tiempo de espera pasado la marca de 60 minutos al exportar grandes cantidades de datos, considere la posibilidad de reducir la cantidad de datos mediante 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 los clientes y su organización:

• Exportar informe a archivo
• Insertar para los clientes
• Insertar para la organización