Exportar relatório paginado para arquivo

  • Artigo

A exportToFile API permite exportar um relatório paginado do Power BI usando uma chamada REST. Os seguintes formatos de ficheiro são suportados:

  • .pptx (PowerPoint)

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

  • .xlsx (Excel)

  • .docx (Word)

  • .csv

  • .xml

  • .mhtml

  • Image
    Ao exportar para uma imagem, defina o formato da imagem através da configuração de OutputFormat formato. Os valores suportados OutputFormat são:

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

Exemplos de utilização

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

  • Botão Enviar para impressão - Em seu aplicativo, crie um botão que, quando clicado, aciona um trabalho de exportação. O trabalho pode exportar o relatório visualizado 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 específicas de formato. Como a API é assíncrona, pode demorar algum tempo até o ficheiro estar disponível.

  • Anexo de e-mail - Envie um e-mail automático em intervalos definidos, com um relatório de .pdf anexado. Esse cenário pode ser útil se você quiser automatizar o envio de um relatório semanal para os executivos.

Usando a API

Requisitos de licença

  • O relatório que você está exportando deve residir em um espaço de trabalho apoiado por uma capacidade Premium, Incorporada ou de Malha.
  • A exportToFile API, tem suporte limitado em Premium Per User (PPU).

Renderização de eventos

Para garantir que a exportação não comece antes que o visual termine a renderização, use a API de eventos "Renderização" e só inicie a exportação quando a renderização estiver concluída.

Consultas

A API é assíncrona. Quando a API exportToFile é chamada, ela dispara um trabalho de exportação. Depois de acionar um trabalho de exportação, use sondagem para acompanhar o trabalho até que ele seja concluído.

Quando a exportação estiver concluída, a chamada da API de sondagem retorna uma URL do Power BI para obter o arquivo. O URL fica disponível durante 24 horas.

Funcionalidades suportadas

Configurações de formato

Especifique várias configurações de formato para cada formato de arquivo. As propriedades e valores suportados são equivalentes aos parâmetros de Informações do Dispositivo para parâmetros de URL de relatório paginado.

Veja a seguir dois exemplos. A primeira é para exportar as primeiras quatro 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 de .jpeg.

Exportando as quatro primeiras páginas para um .pptx

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

Exportando a terceira página para um .jpeg

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

Parâmetros do relatório

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

Veja um exemplo para definir valores de parâmetros 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

Você pode autenticar usando um usuário (ou usuário mestre) ou uma entidade de serviço.

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

Ao usar um modelo semântico do Power BI que tenha RLS (Segurança em Nível de Linha) definida como uma fonte de dados, você pode exportar um relatório mostrando dados 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 programaticamente o relatório para que apenas uma determinada região seja exibida.

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 fonte de dados.

Aqui está um exemplo de fornecimento de um nome de usuário eficaz para RLS.

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

SQL de logon único e Dataverse (SSO)

No Power BI, você tem a opção de definir OAuth com SSO. Quando o fizer, as credenciais do utilizador que visualiza o relatório são utilizadas para recuperar dados. O token de acesso no cabeçalho da solicitação não é usado para acessar os dados. O token deve ser passado com a identidade efetiva no corpo postal.

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

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

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

Aqui está 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"
         }
        }
     ]
   }
}

Pedidos simultâneos

O exportToFile suporta um número limitado de solicitações simultâneas. O número máximo de solicitações de renderização de relatório paginado simultâneas é 500. Para evitar exceder o limite e obter um erro de solicitações demais (429), distribua a carga ao longo do tempo ou entre capacidades.

Com o Premium Per User (PPU), a exportToFile API permite apenas uma solicitação em uma janela de cinco minutos. Várias solicitações dentro da janela de cinco minutos resultam em um erro de solicitações demais (429).

Exemplos de código

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

Quando você cria um trabalho de exportação, há três etapas a serem seguidas:

  1. Envio de um pedido de exportação.
  2. Votação.
  3. Obter o ficheiro.

Esta seção fornece exemplos para cada etapa.

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

O primeiro passo é enviar um pedido de exportação. Neste exemplo, uma solicitação de exportação é enviada para um intervalo de páginas, 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;
}

Passo 2 - sondagem

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

Passo 3 - obter o ficheiro

Depois que a sondagem retornar uma URL, use este exemplo para obter o arquivo recebido.

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 completo para exportar um relatório. Este exemplo inclui as seguintes etapas:

  1. Envio do pedido de exportação.
  2. Votação.
  3. Obter o ficheiro.
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

  • Não há suporte para a exportação de um relatório paginado que tenha um modelo semântico do Power BI como fonte de dados nos seguintes casos:

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

  • A exportação de um relatório paginado que tenha a fonte de dados do Azure Analysis Services configurada com o logon único (SSO) habilitado não é suportada nos seguintes casos:

    • O chamador é um perfil de entidade de serviço.
    • O chamador é um usuário mestre e uma identidade efetiva foi fornecida.

  • Para exportar um relatório paginado com uma identidade efetiva, o nome de usuário deve ser um usuário existente da ID do Microsoft Entra do seu 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 além da marca de 60 minutos ao exportar grandes quantidades de dados, considere reduzir a quantidade de dados usando filtros apropriados.

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

Conteúdos relacionados

Reveja como incorporar conteúdo para os seus clientes e a sua organização: