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 formato OutputFormat. Los valores admitidos de OutputFormatson:

  • .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 exportToFile tiene 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:

1. Envío de una solicitud de exportación.
2. Sondeo.
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 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:

1. Envío de la solicitud de exportación.
2. Sondeo.
3. Obtención del 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 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:

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