Share via

Exportar relatório do Power BI para arquivo

  • Artigo

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

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

Nota

A exportação de um relatório do Power BI para um arquivo usando a API exportToFile não é suportada para PPU (Premium Por Usuário).

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 marcadores, você pode exportar o relatório em um estado específico, incluindo filtros configurados, segmentações de dados e outras configurações. 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 executivos. Para obter mais informações, consulte Exportar e enviar por email um relatório do Power BI com o Power Automate

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 não é suportada para Premium Per User (PPU).

Definições de administração

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

  • Exportar relatórios como apresentações do PowerPoint ou documentos PDF - Ativado por padrão.
  • Exportar relatórios como arquivos de imagem - Necessário apenas para .png e desativado por padrão.

Eventos de "renderização"

Para garantir que a exportação não comece antes que a renderização visual termine, 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.

Durante a sondagem, a API retorna um número que representa a quantidade de trabalho concluído. O trabalho em cada trabalho de exportação é calculado com base no total de exportações no trabalho. Uma exportação inclui a exportação de um único visual ou de uma página com ou sem marcadores. 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 no trabalho de exportação.

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

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

Selecionar as páginas a imprimir

Especifique as páginas que deseja imprimir de acordo com o valor de retorno Obter Páginas ou Obter Páginas em Grupo. Você também pode especificar a ordem das páginas que está exportando.

Exportar uma página ou um único visual

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

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.

Nota

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

Atributo Página 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 do GetPages ou a API dogetPagescliente.
visualName Does not apply to. Applies to. Há duas maneiras de obter o nome do visual:
  • Use a API do getVisuals cliente.
  • Ouça e registre o evento visualClicked , que é acionado quando um visual é selecionado. Para obter mais informações, consulte Como manipular eventos
    • .

    Marcadores

    Os marcadores 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 marcador de um relatório, de duas maneiras:

    • Exportar um marcador existente

      Para exportar um marcador de relatório existente, use a propriedade, um identificador exclusivo (diferencia maiúsculas de minúsculas), que você pode obter usando a name API JavaScript de favoritos.

    • Exportar o estado do relatório

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

    Nota

    Não há suporte para marcadores 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 da cadeia de caracteres de consulta de URL que você deseja usar como filtro em ExportFilter. Ao inserir a cadeia de caracteres, você deve remover a ?filter= parte do parâmetro de consulta de URL.

    A tabela inclui alguns exemplos de sintaxe de cadeias de caracteres que você pode passar para ExportFilter.

    Filtro Sintaxe Exemplo
    Um valor em um campo Tabela/Campo eq 'valor' Loja/Território eq 'NC'
    Vários valores em um campo Tabela/Campo em ('value1', 'value2') Loja/Território em ('NC', 'TN')
    Um valor distinto em um campo e um valor distinto diferente em outro campo Tabela/Campo1 eq 'valor1' e Tabela/Campo2 eq 'valor2' Loja/Território eq 'NC' e Loja/Cadeia eq 'Modas Directas'

    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)

    Com a Segurança em Nível de Linha (RLS), 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 as seguintes permissões:

    • Permissões de gravação e compartilhamento novo para o modelo semântico ao qual o relatório está conectado
    • Membro ou administrador do espaço de trabalho onde o relatório reside

    Proteção de dados

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

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

    Localização

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

    Vinculação dinâmica

    Para exportar um relatório enquanto ele estiver conectado a um modelo semântico diferente do modelo semântico padrão, especifique o datasetToBind ID do conjunto de dados necessário no parâmetro ao chamar a API. Leia mais sobre vinculação dinâmica.

    Pedidos simultâneos

    A exportToFile API suporta um número limitado de solicitações simultâneas. O número máximo de solicitações simultâneas suportadas é de 500 por capacidade. Para evitar exceder o limite e obter um erro de solicitações demais (429), distribua a carga ao longo do tempo ou entre capacidades. Apenas cinco páginas de um relatório são processadas simultaneamente. Por exemplo, se você 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

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

    1. Envio de um pedido de exportação.
    2. Votação.
    3. Obter o ficheiro.
    4. Usando o fluxo de arquivos.

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

    Passo 2 - sondagem

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

    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 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 - Usando o fluxo de arquivos

    Quando você tem o fluxo de arquivos, você pode manipulá-lo da maneira que melhor se adapta às suas necessidades. Por exemplo, você pode enviá-lo por e-mail ou usá-lo para baixar os relatórios exportados.

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

    • Uma carga de operação de API de exportação é avaliada como uma operação em segundo plano de execução lenta, conforme descrito em Avaliação de carga de capacidade Premium.
    • Todos os modelos semânticos relacionados no relatório que você está exportando devem residir em uma capacidade Premium ou Incorporada, incluindo modelos semânticos com uma conexão Direct Query.
    • Os relatórios exportados não podem exceder um tamanho de arquivo de 250 MB.
    • Ao exportar para o .png, os rótulos de sensibilidade não são suportados.
    • O número de exportações (visuais únicos ou páginas de relatório) que podem ser incluídas em um único relatório exportado é 50 (não incluindo 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.
    • Não há suporte para marcadores pessoais e filtros persistentes para exportação de relatório do Power BI para arquivo.
    • A exportToFile API exporta o relatório com o valor padrão se usado sem marcadores ou reportLevelFilters.
    • Os visuais do Power BI listados aqui não são suportados. Quando você exporta um relatório que contém esses elementos visuais, as partes do relatório que contêm esses elementos visuais não são renderizadas e exibem um símbolo de erro.
      • Visuais personalizados não certificados do Power BI
      • Visuais R
      • PowerApps
      • Visuais Python
      • Power Automate
      • Relatório visual paginado
      • Visio
      • Visuais do ArcGIS

    Conteúdos relacionados

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

    Mais perguntas? Experimente a Comunidade do Power BI