Экспорт отчета Power BI в файл

Статья
12/19/2023

exportToFile API позволяет экспортировать отчет Power BI с помощью вызова REST. Поддерживаются следующие форматы файлов.

PPTX (PowerPoint)
.Pdf
.png
- При экспорте в PNG отчет с несколькими страницами сжимается в ZIP-файл.
- Каждый файл в ZIP-файле представляет страницу отчета
- Имена страниц совпадают с возвращаемыми значениями get Pages или Get Pages в API группы

Примечание.

Экспорт отчета Power BI в файл с помощью API exportToFile не поддерживается для пользователя premium на пользователя (PPU).

Примеры использования

Функцию экспорта можно использовать несколькими способами. Вот несколько примеров.

Кнопка "Отправить на печать" — в приложении создайте кнопку , которая при нажатии на триггеры задания экспорта. Задание может экспортировать просматриваемый отчет в формате PDF или PPTX. По завершении пользователь может получить файл как скачанный. С помощью закладок можно экспортировать отчет в определенном состоянии, включая настроенные фильтры, срезы и другие параметры. Так как этот API является асинхронным, может пройти некоторое время, прежде чем файл станет доступным.
Вложение электронной почты. Отправка автоматического сообщения электронной почты с заданными интервалами с вложенным отчетом .pdf. Этот сценарий может оказаться полезным, если вы хотите автоматизировать отправку еженедельного отчета руководителям. Дополнительные сведения см. в статье "Экспорт и электронная почта отчета Power BI с помощью Power Automate"

Использование API

Требования к лицензиям

Экспортируемый отчет должен находиться в рабочей области, поддерживаемой емкостью Premium, Embedded или Fabric.
exportToFile API не поддерживается для класса Premium на пользователя (PPU).

Параметры администрирования

Прежде чем использовать API, убедитесь, что включены следующие параметры клиента администратора:

Экспортируйте отчеты в виде презентаций PowerPoint или PDF-документов . По умолчанию включена поддержка.
Экспорт отчетов в виде файлов изображений — требуется только для PNG и отключен по умолчанию.

События отрисовки

Чтобы убедиться, что экспорт не начинается до завершения отрисовки, используйте API событий "Отрисовка" и начинается только при завершении отрисовки.

Опросы

API является асинхронным. При вызове API exportToFile он активирует задание экспорта. После активации задания экспорта используйте опрос для отслеживания задания, пока он не завершится.

Во время опроса API возвращает число, представляющее объем завершенной работы. Работа в каждом задании экспорта вычисляется на основе общей суммы экспорта в задании. Экспорт включает экспорт одного визуального элемента или страницы с закладками или без нее. Все экспорты имеют одинаковый вес. Например, задание экспорта включает экспорт отчета с 10 страниц, а опрос возвращает 70, это означает, что API обрабатывает семь из 10 страниц в задании экспорта.

После завершения экспорта вызов API опроса возвращает URL-адрес Power BI для получения файла. URL-адрес доступен в течение 24 часов.

Поддерживаемые функции

В этом разделе описывается, как использовать следующие поддерживаемые функции:

Выбор страниц для печати
Экспорт страницы или одного визуального элемента
Закладки
Фильтры
Аутентификация
Безопасность на уровне строк (RLS)
Защита данных
Локализация
Динамическая привязка

Выбор страниц для печати

Укажите страницы, которые нужно распечатать в соответствии с возвращаемым значением Get Pages или Get Pages в группе. Вы также можете указать порядок экспортируемых страниц.

Экспорт страницы или одного визуального элемента

Вы можете указать страницу или один визуальный элемент для экспорта. Страницы можно экспортировать с закладками или без нее.

В зависимости от типа экспорта необходимо передать различные атрибуты в объект ExportReportPage . В следующей таблице указаны атрибуты, необходимые для каждого задания экспорта.

Примечание.

Экспорт одного визуального элемента имеет тот же вес, что и экспорт страницы (с закладками или без нее). Это означает, что с точки зрения системных вычислений обе операции несут одно и то же значение.

Атрибут	Страница	Комментарии
`bookmark`	Необязательно	Использование для экспорта страницы в определенном состоянии
`pageName`		Используйте REST API GetPages или клиентский `getPages` API.
`visualName`		Существует два способа получить имя визуального элемента: Используйте клиентский `getVisuals` API. Прослушивайте и регистрируйте событие visualClicked , которое активируется при выборе визуального элемента. Дополнительные сведения см. в разделе "Обработка событий" .

Закладки

Закладки можно использовать для сохранения отчета в определенной конфигурации, включая примененные фильтры и состояние визуальных элементов отчета. API exportToFile можно использовать для программного экспорта закладки отчета двумя способами:

Экспорт существующей закладки

Чтобы экспортировать существующую закладку отчета, используйте name свойство, уникальный (конфиденциальный регистр) идентификатор, который можно получить с помощью API JavaScript для закладок.
Экспорт состояния отчета

Чтобы экспортировать текущее состояние отчета, используйте state свойство. Например, можно использовать метод закладки bookmarksManager.capture для записи изменений, внесенных в отчет, а затем экспортировать его в текущее состояние с помощью capturedBookmark.state.

Примечание.

Личные закладки и постоянные фильтры не поддерживаются.

Фильтры

Используя reportLevelFilters PowerBIReportExportConfiguration, можно экспортировать отчет в отфильтрованном состоянии.

Чтобы экспортировать отфильтрованный отчет, вставьте параметры строки ЗАПРОСА URL-адреса, которые вы хотите использовать в качестве фильтра, в ExportFilter. При вводе строки необходимо удалить ?filter= часть параметра запроса URL-адреса.

Таблица содержит несколько примеров синтаксиса строк, в ExportFilterкоторые можно передать.

Фильтр	Синтаксис	Пример
Значение в поле	Таблица или поле eq "value"	Store/Territory eq 'NC'
Несколько значений в поле	Таблица или поле в ('value1', 'value2')	Магазин или территория в ('NC', 'TN')
Уникальное значение в одном поле и другое отдельное значение в другом поле	Table/Field1 eq 'value1' и Table/Field2 eq 'value2'	Store/Territory eq 'NC' и Store/Chain eq 'Fashions Direct'

Проверка подлинности

Вы можете пройти проверку подлинности с помощью пользователя (или главного пользователя) или субъекта-службы.

Безопасность на уровне строк (RLS)

С помощью системы безопасности на уровне строк (RLS) можно экспортировать отчет с данными, видимыми только для определенных пользователей. Например, если вы экспортируете отчет о продажах, определенный с региональными ролями, можно программно отфильтровать отчет таким образом, чтобы отображалось только определенное регион.

Для экспорта с помощью RLS необходимо иметь следующие разрешения:

Разрешения на запись и повторное предоставление общего доступа для семантической модели, к которому подключен отчет
Член рабочей области или администратор рабочей области, в которой находится отчет

Защита данных

Форматы .pdf и PPTX поддерживают метки конфиденциальности. При экспорте отчета с меткой конфиденциальности в PDF-файл или PPTX экспортируемый файл отображает отчет с меткой конфиденциальности.

Отчет с меткой конфиденциальности нельзя экспортировать в PDF-файл или PPTX с помощью субъекта-службы.

Локализация

При использовании API можно передать нужный exportToFile языковой стандарт. Параметры локализации влияют на способ отображения отчета, например путем изменения форматирования в соответствии с выбранным локальным.

динамическая привязка;

Чтобы экспортировать отчет во время подключения к семантической модели, а затем семантической модели по умолчанию, укажите необходимый идентификатор набора данных в datasetToBind параметре при вызове API. Дополнительные сведения о динамической привязке.

Число одновременных запросов

exportToFile API поддерживает ограниченное количество одновременных запросов. Максимальное число одновременных запросов, поддерживаемых, составляет 500 на емкость. Чтобы избежать превышения предела и получения ошибки слишком большого количества запросов (429), распределяйте нагрузку по времени или по емкостям. Одновременно обрабатываются только пять страниц отчета. Например, при экспорте отчета с 50 страниц задание экспорта обрабатывается в 10 последовательных интервалах. При оптимизации задания экспорта можно рассмотреть возможность параллельного выполнения нескольких заданий.

Примеры кода

При создании задания экспорта необходимо выполнить четыре действия.

Отправка запроса на экспорт.
Опрос.
Получение файла.
Использование потока файлов.

В этом разделе приведены примеры для каждого шага.

Шаг 1. Отправка запроса на экспорт

Первым шагом является отправка запроса на экспорт. В этом примере запрос на экспорт отправляется для определенной страницы.

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

Шаг 2. Опрос

После отправки запроса на экспорт используйте опрос, чтобы определить, когда файл экспорта будет готов.

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

Шаг 3. Получение файла

Когда опрос возвращает URL-адрес, используйте этот пример для получения полученного файла.

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

Шаг 4. Использование потока файлов

Если у вас есть поток файлов, его можно обрабатывать таким образом, чтобы он соответствовал вашим потребностям. Например, вы можете отправить сообщение электронной почты или использовать его для скачивания экспортированных отчетов.

Полный пример

Это комплексный пример экспорта отчета. В этом примере приведены следующие этапы.

Отправка запроса на экспорт.
Опрос.
Получение файла.

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

Экспорт отчета Power BI в файл

Примеры использования

Использование API

Требования к лицензиям

Параметры администрирования

События отрисовки

Опросы

Поддерживаемые функции

Выбор страниц для печати

Экспорт страницы или одного визуального элемента

Закладки

Фильтры

Проверка подлинности

Безопасность на уровне строк (RLS)

Защита данных

Локализация

динамическая привязка;

Число одновременных запросов

Примеры кода

Шаг 1. Отправка запроса на экспорт

Шаг 2. Опрос

Шаг 3. Получение файла

Шаг 4. Использование потока файлов

Полный пример

Рекомендации и ограничения

Обратная связь

Обратная связь

Дополнительные ресурсы

Экспорт отчета Power BI в файл

Примеры использования

Использование API

Требования к лицензиям

Параметры администрирования

События отрисовки

Опросы

Поддерживаемые функции

Выбор страниц для печати

Экспорт страницы или одного визуального элемента

Закладки

Фильтры

Проверка подлинности

Безопасность на уровне строк (RLS)

Защита данных

Локализация

динамическая привязка;

Число одновременных запросов

Примеры кода

Шаг 1. Отправка запроса на экспорт

Шаг 2. Опрос

Шаг 3. Получение файла

Шаг 4. Использование потока файлов

Полный пример

Рекомендации и ограничения

Связанный контент

Обратная связь

Обратная связь

Дополнительные ресурсы