Exportar relatório do Power BI para um arquivo

  • Artigo

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

  • .pptx (PowerPoint)
  • .pdf
  • .png
    • Ao exportar para um .png, um relatório com várias páginas é compactado em um arquivo .zip
    • Cada arquivo no .zip representa uma página do relatório
    • Os nomes das páginas são os mesmos que os valores de retorno das APIs Obter Páginas ou Obter Páginas em Grupo

Observação

Não há suporte para a exportação de um relatório do Power BI para um arquivo usando a API exportToFile para usuários Premium por Usuário (PPU).

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 indicadores, é possível exportar o relatório em um estado específico, incluindo filtros configurados, segmentações e outras configurações. 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. Para obter mais informações, confira Exportar um relatório do Power BI e enviá-lo por email com o Power Automate

Usando a API

Requisitos de licença

  • O relatório que você está exportando deve residir em um workspace com suporte de uma capacidade Premium, Embedded ou Fabric.
  • A API exportToFilenão tem suporte para PPU (Premium por Usuário).

Configurações de administração

Antes de usar a API, verifique se as seguintes configurações de locatário administrador estão definidas:

  • Exportar relatórios como apresentações do PowerPoint ou documentos PDF – Habilitado por padrão.
  • Exportar relatórios como arquivos de imagem: necessário somente para .png e desabilitado por padrão.

"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.

Durante a sondagem, a API retorna um número que representa a quantidade de trabalho concluída. Cada trabalho de exportação é calculado com base no número total de exportações no trabalho. Uma exportação inclui exportar somente um visual ou uma página com ou sem indicadores. Todas as exportações têm o mesmo peso. Se, por exemplo, seu trabalho de exportação incluir a exportação de um relatório com 10 páginas e a sondagem retornar 70, isso significa que a API processou sete das 10 páginas do trabalho de exportaçã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

Esta seção descreve como usar os seguintes recursos com suporte:

Selecionar as páginas para impressão

Especifique as páginas para impressão de acordo com o valor de retorno de Obter Páginas ou Obter Páginas em Grupo. Também é possível especificar a ordem das páginas que você está exportando.

Exportar uma página ou somente um visual

Você pode especificar uma página ou somente um visual para exportar. As páginas podem ser exportadas com ou sem indicadores.

Dependendo do tipo de exportação, você precisa passar atributos diferentes para o objeto ExportReportPage. A tabela a seguir especifica quais atributos são necessários para cada trabalho de exportação.

Observação

Exportar somente um visual tem o mesmo peso que exportar uma página (com ou sem indicadores). Isso significa que, em termos de cálculos do sistema, ambas as operações têm o mesmo valor.

Atributo ? Visual único Comentários
bookmark Opcional Does not apply to. Usar para exportar uma página em um estado específico
pageName Applies to. Applies to. Use a API REST GetPages ou a API do cliente getPages.
visualName Does not apply to. Applies to. Há duas maneiras de obter o nome do visual:
  • Use a API de cliente getVisuals.
  • Escute e registre o evento visualClicked, que é disparado quando um visual é selecionado. Para obter mais informações, confira Como manipular eventos
    • .

    Indicadores

    Os Indicadores podem ser usados para salvar um relatório em uma configuração específica, incluindo filtros aplicados e o estado dos visuais do relatório. Você pode usar a API exportToFile para exportar programaticamente o indicador de relatório de duas maneiras:

    • Exportar um indicador existente

      Para exportar um indicador de relatório existente, use a propriedade name, um identificador exclusivo (com diferenciação de maiúsculas e minúsculas) que você pode obter usando a API JavaScript de indicadores.

    • Exportar o estado do relatório

      Para exportar o estado atual do relatório, use a propriedade state. Por exemplo, você pode usar o método bookmarksManager.capture do indicador para capturar as alterações que um usuário específico executou no relatório, depois pode exportá-lo no seu estado atual usando capturedBookmark.state.

    Observação

    Não há suporte para indicadores pessoais e filtros persistentes.

    Filtros

    Usando reportLevelFilters no PowerBIReportExportConfiguration, você pode exportar um relatório em uma condição filtrada.

    Para exportar um relatório filtrado, insira os parâmetros de cadeia de caracteres de consulta de URL que deseja usar como filtro em ExportFilter. Ao inserir a cadeia de caracteres, você deve remover a parte ?filter= do parâmetro de consulta de URL.

    A tabela inclui alguns exemplos de sintaxe de cadeias de caracteres que podem ser passadas para ExportFilter.

    Filter Sintaxe Exemplo
    Um valor em um campo Table/Field eq 'value' Store/Territory eq 'NC'
    Vários valores em um campo Table/Field in ('value1', 'value2') Store/Territory in ('NC', 'TN')
    Um valor distinto em um campo e um valor distinto diferente em outro campo Table/Field1 eq 'value1' e Table/Field2 eq 'value2' Store/Territory eq 'NC' e Store/Chain eq 'Fashions Direct'

    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)

    Com a RLS (Segurança em Nível de Linha), é possível exportar um relatório mostrando dados que só ficam visíveis para determinados usuários. Por exemplo, se estiver exportando um relatório de vendas definido com funções regionais, é possível filtrar programaticamente o relatório para que apenas uma determinada região seja exibida.

    Para exportar usando RLS, você deve ter as seguintes permissões:

    • Permissões de gravação e recompartilhamento do modelo semântico ao qual o relatório está conectado
    • Membro do workspace ou administrador do workspace em que o relatório reside

    Proteção de dados

    Os formatos .pdf e .pptx dão suporte a rótulos de confidencialidade. Se você exportar um relatório com um rótulo de confidencialidade para um arquivo .pdf ou .pptx, o arquivo exportado exibirá o relatório com seu rótulo de confidencialidade.

    Um relatório com um rótulo de confidencialidade não pode ser exportado para um .pdf ou um .pptx com uma entidade de serviço.

    Localização

    Ao usar a API exportToFile, você pode passar a localidade desejada. As configurações de localização afetam a maneira como o relatório é exibido, por exemplo, ao alterar a formatação de acordo com o local selecionado.

    Associação dinâmica

    Para exportar um relatório enquanto ela estiver conectada a outro conjunto de dados além do modelo semântico padrão, especifique a ID do modelo semântico necessária no parâmetro datasetToBind ao chamar a API. Leia mais sobre associação dinâmica.

    Solicitações simultâneas

    A exportToFile API dá suporte a um número limitado de solicitações simultâneas. O número máximo de solicitações simultâneas com suporte é 500 por capacidade. Para evitar exceder o limite e receber um erro Too Many Requests (429), tente distribuir a carga ao longo do tempo ou entre capacidades. Somente cinco páginas de um relatório são processadas simultaneamente. Por exemplo, se estiver exportando um relatório com 50 páginas, o trabalho de exportação será processado em 10 intervalos sequenciais. Ao otimizar seu trabalho de exportação, convém considerar a execução de alguns trabalhos em paralelo.

    Exemplos de código

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

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

    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, solicitação de exportação é enviada para uma página específica.

    private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId,
    FileFormat format,
    IList<string> pageNames = null, /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
    var powerBIReportExportConfiguration = new PowerBIReportExportConfiguration
    {
        Settings = new ExportReportSettings
        {
            Locale = "en-us",
        },
        // Note that page names differ from the page display names
        // To get the page names use the GetPages REST API
        Pages = pageNames?.Select(pn => new ExportReportPage(Name = pn)).ToList(),
        // ReportLevelFilters collection needs to be instantiated explicitly
        ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

    };

    var exportRequest = new ExportReportRequest
    {
        Format = format,
        PowerBIReportConfiguration = powerBIReportExportConfiguration,
    };

    // The 'Client' object is an instance of the Power BI .NET SDK
    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

    Após enviar uma solicitação de exportação, use a sondagem para identificar quando o arquivo de exportação que você está esperando estiver Pronto.

    private async Task<HttpOperationResponse<Export>> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the PostExportRequest response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    HttpOperationResponse<Export> httpMessage = null;
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int c_secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations 
            return null;
        }

        // The 'Client' object is an instance of the Power BI .NET SDK
        httpMessage = await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
        exportStatus = httpMessage.Body;

        // You can track the export progress using the PercentComplete that's part of the response
        SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(), exportStatus.PercentComplete);
        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 not always populated
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;
            await Task.Delay(retryAfterInSec * c_secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return httpMessage;
}

    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 PollExportRequest response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        // The 'Client' object is an instance of the Power BI .NET SDK
        var fileStream = await Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
        return new ExportedFile
        {
            FileStream = fileStream,
            FileSuffix = export.ResourceFileExtension,
        };
    }
    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string FileSuffix;
}

    Etapa 4 – Usar o fluxo de arquivos

    Quando você tiver um fluxo de arquivos, poderá lidar com ele da forma mais adequada às suas necessidades. Por exemplo, você pode enviar por email ou usar para baixar os relatórios exportados.

    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> ExportPowerBIReport(
	Guid reportId,
	Guid groupId,
	FileFormat format,
	int pollingtimeOutInMinutes,
	CancellationToken token,
	IList<string> pageNames = null,  /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
	const int c_maxNumberOfRetries = 3; /* Can be set to any desired number */
	const int c_secToMillisec = 1000;
	try
	{
		Export export = null;
		int retryAttempt = 1;
		do
		{
			var exportId = await PostExportRequest(reportId, groupId, format, pageNames, urlFilter);
			var httpMessage = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
			export = httpMessage.Body;
			if (export == null)
			{
				// Error, failure in exporting the report
				return null;
			}
			if (export.Status == ExportState.Failed)
			{
				// Some failure cases indicate that the system is currently busy. The entire export operation can be retried after a certain delay
				// In such cases the recommended waiting time before retrying the entire export operation can be found in the RetryAfter header
				var retryAfter = httpMessage.Response.Headers.RetryAfter;
				if(retryAfter == null)
				{
				    // Failed state with no RetryAfter header indicates that the export failed permanently
				    return null;
                }

                var retryAfterInSec = retryAfter.Delta.Value.Seconds;
                await Task.Delay(retryAfterInSec * c_secToMillisec);
            }
        }
        while (export.Status != ExportState.Succeeded && retryAttempt++ < c_maxNumberOfRetries);

        if (export.Status != ExportState.Succeeded)
        {
            // Error, failure in exporting the report
            return null;
        }

        var exportedFile = await GetExportedFile(reportId, groupId, export);

        // Now you have the exported file stream ready to be used according to your specific needs
        // For example, saving the file can be done as follows:
        /*
            var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;

            using (var fileStream = File.Create(pathOnDisk))
            {
                exportedFile.FileStream.CopyTo(fileStream);
            }
        */

        return exportedFile;
    }
    catch
    {
        // Error handling
        throw;
    }
}

    Considerações e limitações

    • A carga de uma operação de API de exportação é avaliada como uma operação em segundo plano de execução lenta, conforme descrito em Avaliação da Carga de capacidade Premium.
    • Todos os modelos semânticos relacionados no relatório que você está exportando devem residir em uma capacidade Premium ou Embedded, incluindo modelos semânticos com uma conexão de Consulta Direta.
    • Os relatórios exportados não podem exceder um tamanho de arquivo de 250 MB.
    • Não há suporte para rótulos de confidencialidade ao exportar para .png.
    • O número de exportações (páginas únicas de visuais ou relatórios) que podem ser incluídas em um único relatório exportado é 50 (não incluída a exportação de relatórios paginados). Se a solicitação incluir mais exportações, a API retornará um erro e o trabalho de exportação será cancelado.
    • Indicadores pessoais e filtros persistentes não têm suporte para exportação de relatório do Power BI para arquivo.
    • A API exportToFile exporta o relatório com valor padrão se usado sem indicadores ou reportLevelFilters.
    • Não há suporte para os recursos visuais do Power BI listados aqui. Quando você exporta um relatório que contém esses visuais, as partes do relatório que contêm esses visuais não são renderizadas e exibem um símbolo de erro.
      • Visuais personalizados do Power BI não certificados
      • Visuais do R
      • PowerApps
      • Visuais de Python
      • Power Automate
      • Visual de relatório paginado
      • Visio
      • Visuais do ArcGIS

    Conteúdo relacionado

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

    Mais perguntas? Experimente a Comunidade do Power BI