Exportar o relatório paginado para um arquivo

  • Artigo

A API exportToFile permite exportar um relatório paginado do Power BI usando uma chamada REST. Os seguintes formatos de arquivo têm suporte:

  • .pptx (PowerPoint)

  • .pdf (e PDF acessível ou PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .csv

  • .xml

  • .mhtml

  • Imagem
    Ao exportar para uma imagem, defina o formato da imagem por meio da configuração de formato de OutputFormat. Os valores OutputFormat com suporte são:

    • .tiff (padrão)
    • .bmp
    • .emf
    • .gif
    • .jpeg
    • .png

Exemplos de uso

Você pode usar o recurso de exportação de várias maneiras. Aqui estão alguns exemplos:

  • Botão Enviar para impressão – No seu aplicativo, crie um botão que, quando clicado, dispara um trabalho de exportação. O trabalho pode exportar o relatório exibido como um .pdf ou um .pptx. Quando estiver concluído, o usuário poderá receber o arquivo como um download. Usando parâmetros de relatório e configurações de formato, você pode exportar o relatório em um estado específico, incluindo dados filtrados, tamanhos de página personalizados e outras configurações de formato específico. Como a API é assíncrona, pode levar algum tempo até que o arquivo esteja disponível.

  • Anexo de email: envie um email automatizado em intervalos definidos, com um relatório anexado em .pdf. Esse cenário poderá ser útil se você quiser automatizar o envio de relatórios semanais para executivos.

Usando a API

Requisitos de licença

Renderização de eventos

Para garantir que a exportação não comece antes que o visual conclua a renderização, use a API de eventos "Rendering" e só comece a exportação quando a renderização for concluída.

Sondagem

A API é assíncrona. Quando a API exportToFile é chamada, dispara um trabalho de exportação. Depois de disparar o trabalho de exportação, use a sondagem para rastrear o trabalho até a conclusão.

Quando a exportação for concluída, a chamada à API de sondagem retornará uma URL do Power BI para a obtenção do arquivo. A URL fica disponível por 24 horas.

Recursos compatíveis

Configurações de formato

Especifique várias configurações de formato para cada formato de arquivo. Os valores e as propriedades com suporte são equivalentes a Parâmetros de informações de dispositivo para parâmetros de URL de relatórios paginados.

A seguir, são apresentados dois exemplos. O primeiro é para exportar as quatro primeiras páginas de um relatório usando o tamanho da página do relatório para um arquivo .pptx. O segundo exemplo é para exportar a terceira página de um relatório para um arquivo .jpeg.

Como exportar as primeiras quatro páginas para um .pptx

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

Como exportar a terceira página para um .jpeg

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

Parâmetros de relatório

Você pode usar a API exportToFile para exportar programaticamente um relatório com um conjunto de parâmetros de relatório. Isso é feito usando funcionalidades de parâmetro de relatório.

Aqui está um exemplo para definir valores de parâmetro de relatório.

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

Autenticação

É possível autenticar usando um usuário (ou usuário mestre) ou uma entidade de serviço.

RLS (Segurança em Nível de Linha)

Ao usar um modelo semântico do Power BI que tem RLS (Segurança em Nível de Linha) definida como uma fonte de dados, você pode exportar um relatório mostrando os dados que são visíveis apenas para determinados usuários. Por exemplo, se você estiver exportando um relatório de vendas definido com funções regionais, poderá filtrar o relatório programaticamente para exibir apenas determinada região.

Para exportar usando RLS, você deve ter permissão de leitura para o modelo semântico do Power BI que o relatório está usando como uma fonte de dados.

Aqui está um exemplo para fornecer um nome de usuário efetivo para RLS.

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "identities": [
                  {"username": "john@contoso.com"}
            ]
      }
}

Dataverse e SQL de logon único (SSO)

No Power BI, você tem a opção de definir o OAuth com o SSO. Quando você fizer isso, as credenciais do usuário que está vendo o relatório serão usadas para recuperar dados. O token de acesso no cabeçalho de solicitação não é usado para acessar os dados. O token deve ser transmitido com a identidade efetiva no corpo da postagem.

Obter o token de acesso correto para o recurso que você deseja acessar pode ser complicado às vezes.

  • Para o SQL do Azure, o recurso é https://database.windows.net.
  • Para o Dataverse, o recurso é o endereço https:// do seu ambiente. Por exemplo, https://contoso.crm.dynamics.com.

Acesse a API de token usando o método AuthenticationContext.AcquireTokenAsync.

Veja um exemplo para fornecer uma identidade efetiva (nome de usuário) com um token de acesso.

{
       "format":"PDF",
       "paginatedReportConfiguration":{
          "formatSettings":{
             "AccessiblePDF":"true",
             "PageHeight":"11in",
             "PageWidth":"8.5in",
             "MarginBottom":"2in"
          },
          "identities":[
             {
                "username":"john@contoso.com",
                "identityBlob": {
                "value": "eyJ0eX....full access token"
         }
        }
     ]
   }
}

Solicitações simultâneas

O exportToFile dá suporte a um número limitado de solicitações simultâneas. O número máximo de solicitações simultâneas de renderização de relatório paginado é 500. Para evitar exceder o limite e receber um erro Too Many Requests (429), tente distribuir a carga ao longo do tempo ou entre capacidades.

Com o PPU (Premium por Usuário), a API exportToFile permite apenas uma solicitação em uma janela de cinco minutos. Várias solicitações dentro de um período de cinco minutos resultam no erro Solicitações em excesso (429).

Exemplos de código

O SDK da API do Power BI usado nos exemplos de código pode ser baixado aqui.

Ao criar um trabalho de exportação, é necessário seguir três etapas:

  1. Enviar uma solicitação de exportação.
  2. Executar a sondagem.
  3. Obter o arquivo.

Esta seção fornece exemplos para cada etapa.

Etapa 1 – enviar uma solicitação de exportação

A primeira etapa envolve enviar uma solicitação de exportação. Neste exemplo, uma solicitação de exportação é enviada para um intervalo de página, tamanho e valores de parâmetro de relatório 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;
}

Etapa 2 – executar a sondagem

Depois de enviar a solicitação de exportação, use a sondagem para identificar quando o arquivo de exportação que você está esperando ficou 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;
}

Etapa 3 – obter o arquivo

Quando a sondagem retornar uma URL, use este exemplo para receber o arquivo.

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

Exemplo de ponta a ponta

Este é um exemplo de ponta a ponta da exportação de um relatório. O exemplo inclui os seguintes estágios:

  1. Enviar a solicitação de exportação.
  2. Executar a sondagem.
  3. Obter o arquivo.
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;
    }
}

Considerações e limitações

  • A exportação de um relatório paginado que tem um modelo semântico do Power BI como fonte de dados não é compatível nos seguintes casos:

    • O chamador é um perfil de entidade de serviço.
    • Uma das fontes de dados do modelo semântico é configurada com o SSO (logon único) habilitado e uma identidade efetiva foi fornecida.
    • O modelo semântico do Power BI tem o DirectQuery para Azure Analysis Services ou para outro modelo semântico do Power BI e uma identidade eficaz foi fornecida.

  • Não há suporte nos seguintes casos para exportar um relatório paginado que tenha a fonte de dados do Azure Analysis Services configurada com SSO (logon único) habilitado:

  • Para exportar um relatório paginado com uma identidade efetiva, o nome de usuário deve ser um usuário existente do Microsoft Entra ID do locatário.

  • A exportação de um relatório é limitada a 60 minutos, o que corresponde à vida útil do token de acesso do usuário. Se você receber um erro de tempo limite após a marca de 60 minutos ao exportar grandes quantidades de dados, considere reduzir a quantidade de dados usando filtros apropriados.

  • O hiperlink de URL do compartilhamento de arquivo (caminho UNC/compartilhamento de arquivos) não funciona ao exportar um relatório paginado publicado no serviço do Power BI online.

Conteúdo relacionado

Confira novamente como incorporar conteúdo para seus clientes e para sua empresa: