Бөлісу құралы:

Экспорт отчета с разбивкой на страницы в файл

  • Мақала

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

  • .pptx (PowerPoint)

  • .pdf (и доступный PDF-файл или PDF/UA)

  • .xlsx (Excel)

  • .docx (Word)

  • .csv

  • .xml

  • .mhtml

  • Изображение
    При экспорте в изображение задайте формат изображения, используя параметр формата OutputFormat. Поддерживаемые значения OutputFormat:

    • .tiff (по умолчанию)
    • .bmp
    • .emf
    • .gif
    • .jpeg
    • .png

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

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

  • Кнопка «Отправить на печать». В вашем приложении создайте кнопку, которая при нажатии запускает задание на экспорт. Задание может экспортировать просматриваемый отчет как .pdf или .pptx. По завершении пользователь может получить файл как скачанный. С помощью параметров отчета и параметров формата можно экспортировать отчет в определенном состоянии, включая отфильтрованные данные, настраиваемые размеры страниц и другие параметры формата. Так как API является асинхронным, может потребоваться некоторое время, чтобы файл был доступен.

  • Приложение к электронной почте — Отправляйте автоматически сообщения электронной почты с отчетом .pdf через заданные интервалы времени. Этот сценарий может оказаться полезным, если вы хотите автоматизировать отправку еженедельного отчета руководителям.

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

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

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

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

Голосование

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

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

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

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

Укажите различные параметры формата для каждого формата файла. Поддерживаемые свойства и значения эквивалентны параметрам сведений об устройстве для параметров URL-адреса отчета с разбивкой на страницы.

Ниже приведены два примера. Первым является экспорт первых четырех страниц отчета с помощью размера страницы отчета в файл .pptx. Второй пример — экспорт третьей страницы отчета в файл .jpeg.

Экспорт первых четырех страниц в .pptx

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

Экспорт третьей страницы в .jpeg

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

Параметры отчета

API exportToFile можно использовать для программного экспорта отчета с набором параметров отчета. Это делается с использованием возможностей отчета при помощи параметра.

Ниже приведен пример задания значений параметров отчета.

{
      "format": "PDF",
      "paginatedReportConfiguration":{
            "parameterValues":[
                  {"name": "State", "value": "WA"},
                  {"name": "City", "value": "Seattle"},
                  {"name": "City", "value": "Bellevue"},
                  {"name": "City", "value": "Redmond"}
            ]
      }
}

Аутентификация

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

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

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

Для экспорта с помощью RLS необходимо иметь разрешение на чтение на семантическую модель Power BI, используемую отчетом в качестве источника данных.

Ниже приведен пример предоставления эффективного имени пользователя для RLS.

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

Протокол единого входа (Single Sign-On, SSO) для SQL и Dataverse

В Power BI у вас есть возможность настроить OAuth с SSO. Когда вы это делаете, учетные данные пользователя, просматривающего отчет, используются для получения данных. Маркер доступа в заголовке запроса не используется для доступа к данным. Маркер должен передаваться с эффективным удостоверением в тексте публикации.

Получение правильного маркера доступа для ресурса, к которому требуется доступ, иногда может оказаться сложным.

  • Для SQL Azure ресурс https://database.windows.net.
  • Для Dataverse ресурс — это адрес https:// для вашей среды. Например, https://contoso.crm.dynamics.com.

Получите доступ к токен API с помощью метода AuthenticationContext.AcquireTokenAsync.

Вот пример предоставления эффективного удостоверения (имени пользователя) вместе с токеном доступа.

{
       "format":"PDF",
       "paginatedReportConfiguration":{
          "formatSettings":{
             "AccessiblePDF":"true",
             "PageHeight":"11in",
             "PageWidth":"8.5in",
             "MarginBottom":"2in"
          },
          "identities":[
             {
                "username":"john@contoso.com",
                "identityBlob": {
                "value": "eyJ0eX....full access token"
         }
        }
     ]
   }
}

Одновременные запросы

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

С Premium на пользователя (PPU)API exportToFile позволяет только один запрос в пятиминутном окне. Несколько запросов в течение пяти минут приводят к ошибке слишком много запросов (429).

Примеры кода

Пакет SDK API Power BI, используемый в примерах кода, можно скачать здесь.

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

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

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

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

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

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

Шаг 2. Опрос

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

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

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

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

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

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

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

  1. Отправка запроса на экспорт.
  2. голосование.
  3. Получаем файл.
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;
    }
}

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

  • Экспорт отчета с разбивкой на страницы с семантической моделью Power BI в качестве источника данных не поддерживается в следующих случаях:

    • Вызывающий объект — это профиль субъекта-службы.
    • Один из источников данных семантической модели настроен с поддержкой единого входа, и ему присвоено эффективное удостоверение.
    • Семантическая модель Power BI использует DirectQuery к Azure Analysis Services или другой семантической модели Power BI, и предоставлено эффективное удостоверение.

  • Экспорт отчета с разбивкой на страницы с включенным источником данных Azure Analysis Services с поддержкой единого входа не поддерживается в следующих случаях:

    • Вызывающий объект — это профиль служебного принципала .
    • Звонивший является главным пользователем, и было предоставлено эффективное удостоверение.

  • Чтобы экспортировать отчёт с постраничной разбивкой с эффективной идентификацией, имя пользователя должно быть среди существующих пользователей в Microsoft Entra ID вашего клиента.

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

  • Гиперссылка URL-адреса общей папки (UNC-путь к общей папке) не работает при экспорте опубликованного отчета с разбивкой на страницы в Службе Power BI в Интернете.

Связанное содержимое

Узнайте, как внедрить содержимое для клиентов и вашей организации: