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

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

  • Мақала

exportToFile API позволяет экспортировать отчет с разбивкой на страницы 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"}
            ]
      }
}

Единый вход SQL и Dataverse (единый вход)

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

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

  • Для 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) exportToFileAPI разрешает только один запрос в пятиминутном окне. Несколько запросов в течение пяти минут приводит к ошибке слишком много запросов (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 клиента.

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

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

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

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