Exportar relatório paginado para arquivo

A API exportToFile permite exportar um relatório paginado do Power BI usando uma chamada REST. Há suporte para os seguintes formatos de arquivo:

• .pptx (PowerPoint)

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

• .xlsx (Excel)

• .docx (Word)

• .csv

• .xml

• .mhtml

• Imagem
  Ao exportar para uma imagem, defina o formato de imagem por meio da configuração de formato OutputFormat. Os valores de 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 imprimir – no 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 ele for concluído, o usuário poderá receber o arquivo como 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 levar algum tempo para 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 pode ser útil se você quiser automatizar o envio de um relatório semanal aos executivos.

Usando a API

Requisitos de licença

• O relatório que você está exportando deve estar em um espaço de trabalho suportado por uma capacidade Premium, Embedded ou Fabric.
• A API exportToFile tem suporte limitado na licença PPU (Premium por Usuário).

Eventos de renderização

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

Votação

A API é assíncrona. Quando a API exportToFile é chamada, ela dispara um trabalho de exportação. Depois de disparar um 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 obter o arquivo. A URL está disponível por 24 horas.

Recursos com suporte

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 os parâmetros de URL de relatórios paginados.

Aqui estão dois exemplos. A primeira é 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 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 de relatório

Você pode usar a API exportToFile para exportar programaticamente um relatório com um conjunto de parâmetros de relatório. Faça isso usando as funcionalidades do 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-se 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 tenha RLS (Segurança em Nível de Linha) definido 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 o 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 efetivo para RLS.

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

Dataverse e SQL de SSO (logon único)

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

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

• Para o SQL do Azure, o recurso é https://database.windows.net.
• Para o Dataverse, o recurso é o endereço https:// para 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"
         }
        }
     ]
   }
}

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 de Too Many Requests (429), distribua a carga ao longo do tempo ou entre diferentes capacidades.

Com a licença PPU (Premium por Usuário), a API exportToFile só permite uma solicitação em uma janela de cinco minutos. Diversas solicitações em um período de cinco minutos resultam no erro Muitas solicitações (429).

Exemplos de código

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

Ao criar um trabalho de exportação, há três etapas a seguir:

1. Enviando uma solicitação de exportação.
2. Votação.
3. Obter o arquivo.

Esta seção fornece exemplos para cada etapa.

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

A primeira etapa é enviar uma solicitação de exportação. Neste exemplo, uma solicitação de exportação é enviada para um intervalo de páginas específico, tamanho e valores de parâmetro de relatório.

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 – sondagem

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

Etapa 3 – obtendo o arquivo

Quando a sondagem retornar uma URL, use este exemplo para acessar 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 de ponta a ponta para exportar um relatório. Este exemplo inclui os seguintes estágios:

1. Enviar a solicitação de exportação.
2. Sondagem.
3. Obtendo 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

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

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

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

  • O autor da chamada é 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 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 arquivo) não funciona ao exportar um relatório paginado publicado no serviço do Power BI online.

Conteúdo relacionado

Examine como inserir conteúdo para seus clientes e sua organização:

• Exportar relatório para arquivo
• Inserção para clientes
• Inserção para a organização