null

Показать оглавление

API-метод automated позволяет автоматически генерировать и экспортировать отчеты в форматах PDF, PNG, SVG или PPTX. Для работы используется headless-браузер, который загружает отчет и возвращает результат в виде файла в кодировке Base64.

Установка автоэкспорта

Для функционала автоэкспорт отчетов требуется:

установка браузера chromium в пути доступном для портала;
в modusbi.json требуется доп настройка:

{
  "browser": {
    "exec_path": "",
    "disable_gpu": true,
    "no_sandbox": false
  }
}

Параметры:

exec_path — путь к браузеру . Возможно устанавливать явно путь к установленному chromium:
- "" (пусто) — автопоиск Chrome/Chromium в системе;
- "C: path to chrome.exe" (Windows) — явный путь;
- "/usr/bin/chromium" (Linux) — явный путь.
disable_gpu — отключение GPU ускорения:
- true — рекомендуется для серверов без видеокарты;
- false — использовать GPU (по умолчанию Chrome).
no_sandbox — отключение sandbox режима (безопасность)
- false — sandbox включен (рекомендуется, безопаснее);
- true — sandbox отключен (только если возникают проблемы в Docker).

Общая информация

Права доступа:

Для вызова метода необходима авторизация в системе.
Все авторизованные пользователи могут запускать экспорт от своего имени.
Для запуска экспорта от имени другого пользователя (с указанием user_id) необходимо право ImpersonateUser. Им обладают только роли DEVELOPER и ADMINISTRATOR.
Для использования отладочного режима (параметр debug: true) необходимо право Debugging. Им обладает только роль DEVELOPER (см. раздел «Debug режим и диагностика»). Подробнее про отладку в статье «Диагностика и отладка автоматического экспорта через API (метод automated)».

Адрес и тип запроса:

URL: https://dev.modusbi.ru/v1/api/exports;
Метод: POST;
Тип данных: JSON.

Параметры самого запроса представлены в таблице ниже.

Параметр	Тип	Обязательный	Описание и допустимые значения
`$.command.name`	Строка	Да	Имя команды: "automated"
`$.object.name`	Строка	Да	Имя объекта: "exports"
`$.data[0].url`	Строка	Да	URL отчета для генерации (должен содержать report_id в формате /report/123)
`$.data[0].user_id`	Число	Нет	ID пользователя (опционально, по умолчанию используется ID текущего авторизованного пользователя)
`$.data[0].output_type`	Строка	Нет	Итоговый формат: "pdf", "png", "svg" или "pptx" (по умолчанию "pdf")
`$.data[0].page_size`	Строка	Нет	Размер страницы PDF: "A4" или "A3" (по умолчанию "A4", только для output_type="pdf")
`$.data[0].page_orientation`	Строка	Нет	Ориентация страницы PDF: "portrait" или "landscape" (по умолчанию "portrait", только для output_type="pdf")
`$.data[0].debug`	Логический	Нет	Включение отладочного режима. Возвращает детальные логи. По умолчанию: false. Требует права `Debugging`
`$.data[0].monitoring_patterns`	Массив строк	Нет	URL паттерны для HTTP мониторинга (по умолчанию `["/v1/api/recordsets/", "/v1/api/exports/"]`). Работает только при `debug: true`. Можно указать пустой массив [] для отключения фильтрации или свои паттерны для отслеживания конкретных эндпоинтов
`$.data[0].timeout`	Число	Нет	Максимально допустимое время ожидания ответа от frontend в секундах (по умолчанию 120). Backend не знает реального времени генерации, поэтому использует timeout как верхнюю границу
`$.data[0].delay`	Число	Нет	Базовая задержка на элемент в миллисекундах (по умолчанию 1000). Frontend умножает на количество элементов (N*delay) и ждет это время перед отправкой результата
`$.data[0].shutdown_grace_ms`	Число	Нет	Пауза перед закрытием браузера в мс (по умолчанию 2000, можно указать 0 для отключения)
`$.data[0].headless`	Логический	Нет	Режим headless браузера (по умолчанию true)

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

После отправки запроса сервер возвращает ответ в формате JSON. Ниже описаны все возможные параметры в этом ответе. Обращайте особое внимание на success — оно определяет, был ли запрос выполнен успешно.

Параметр	Тип	Описание
`$.mode`	Строка	Текущий статус работы портала. Всегда имеет значение "online"
`$.status`	Число	HTTP-статус код ответа. В данном случае всегда 200
`$.message`	Строка	Общее системное сообщение. Обычно пустая строка
`$.data[0].success`	Число	Главный индикатор результата: 1 — операция успешна, файл создан; 0 — ошибка
`$.data[0].report_id`	Число	Уникальный идентификатор отчета, по которому выполнялась генерация
`$.data[0].message`	Строка	Детальное сообщение о результате операции (успех или причина ошибки)
`$.data[0].elapsed`	Число	Фактическое время выполнения операции (в секундах). Присутствует всегда
`$.data[0].file_data`	Строка	Данные файла в кодировке Base64. Возвращается только при success=1
`$.data[0].file_name`	Строка	Имя сгенерированного файла (например, report_123.pdf). Возвращается только при success=1
`$.data[0].mime_type`	Строка	MIME-тип файла. Возвращается только при success=1
`$.data[0].file_size`	Число	Размер файла в байтах. Возвращается только при success=1
`$.data[0].debug`	Объект	Отладочная информация. Доступна только для пользователей с ролью DEVELOPER при включении параметра `debug: true` в запросе (см. раздел «Debug режим и диагностика»). Подробная структура объекта и работа с отладкой описана в статье «Диагностика и отладка автоматического экспорта через API (метод automated)»

HTTP статус коды:

200 – Операция завершена. Проверяйте поле data[0].success в ответе;
400 – Ошибка валидации входных параметров;
500 – Внутренняя ошибка сервера;
502 – Ошибка связи с браузером или внешним сервисом;
504 – Превышено время выполнения операции.

Полное описание ошибок и методов их диагностики вынесено в отдельную статью «Диагностика и отладка автоматического экспорта через API (метод automated)».

Примеры запросов и ответов

Пример тела запроса минималистичный (без user_id)

```json
{
   "object": {"name": "exports"},
   "command": {"name": "automated"},
   "data": [{
      "url": "https://dev.modusbi.ru/report/123"
   }]
}
```

Пример тела запроса минималистичный (с явным user_id)

```json
{
   "object": {"name": "exports"},
   "command": {"name": "automated"},
   "data": [{
      "url": "https://dev.modusbi.ru/report/123",
      "user_id": 456
   }]
}

Пример тела запроса (PDF)

```json
{
   "object": {"name": "exports"},
   "command": {"name": "automated"},
   "data": [{
      "url": "https://dev.modusbi.ru/report/123",
      "user_id": 456,
      "output_type": "pdf",
      "page_size": "A4",
      "page_orientation": "portrait",
      "debug": false,
      "delay": 2000,
      "timeout": 120,
      "headless": true
   }]
}
```

Пример тела запроса (PNG)

```json
{
   "object": {"name": "exports"},
   "command": {"name": "automated"},
   "data": [{
      "url": "https://dev.modusbi.ru/report/123",
      "user_id": 456,
      "output_type": "png",
      "debug": false,
      "delay": 2000,
      "timeout": 120,
      "headless": true
   }]
}
```

Пример тела запроса (PPTX)

```json
{
   "object": {"name": "exports"},
   "command": {"name": "automated"},
   "data": [{
      "url": "https://dev.modusbi.ru/report/123?export=pptx",
      "user_id": 456,
      "output_type": "pptx",
      "debug": false,
      "delay": 2000,
      "timeout": 120,
      "headless": true
   }]
}
```

Пример успешного ответа PDF (HTTP 200)

```json
{
   "mode": "online",
   "status": 200,
   "message": "",
   "data": [{
      "success": 1,
      "report_id": 123,
      "message": "Отчет успешно сгенерирован",
      "elapsed": 12.45,
      "file_data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSAKPj4KPj4KL01lZGlhQm94IFswIDAgNjEyIDc5Ml0KL0NvbnRlbnRzIDQgMCBSCj4+CmVuZG9iago0IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNQowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1OCAwMDAwMCBuIAowMDAwMDAwMTE1IDAwMDAwIG4gCjAwMDAwMDAyNDUgMDAwMDAgbiAKdHJhaWxlcgo8PAovU2l6ZSA1Ci9Sb290IDEgMCBSCj4+CnN0YXJ0eHJlZgozMzkKJSVFT0Y=",
      "file_name": "report_123.pdf",
      "mime_type": "application/pdf",
      "file_size": 2048
   }]
}
```

Пример успешного ответа PNG (HTTP 200)

```json
{
   "mode": "online",
   "status": 200,
   "message": "",
   "data": [{
      "success": 1,
      "report_id": 123,
      "message": "PNG файл успешно сгенерирован",
      "elapsed": 8.32,
      "file_data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
      "file_name": "report_123.png",
      "mime_type": "image/png",
      "file_size": 54076
   }]
}
```

Пример успешного ответа PPTX (HTTP 200)

```json
{
   "mode": "online",
   "status": 200,
   "message": "",
   "data": [{
      "success": 1,
      "report_id": 123,
      "message": "PPTX файл успешно сгенерирован",
      "elapsed": 15.32,
      "file_data": "UEsDBBQABgAIAAAAIQBi7p1oXgEAAJAEAAATAAgCW0NvbnRlbnRfVHlwZXNdLnhtbCCiBAIooAAC...",
      "file_name": "report_123.pptx",
      "mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
      "file_size": 125048
   }]
}
```

Пример фронтенд проблемы - таймаут (HTTP 200)

```json
{
   "mode": "online",
   "status": 200,
   "message": "",
   "data": [{
      "success": 0,
      "report_id": 123,
      "message": "фронтенд не отправил данные в течение указанного времени",
      "elapsed": 8.12
   }]
}
```

Пример фронтенд проблемы - ошибка генерации (HTTP 200)

```json
{
   "mode": "online",
   "status": 200,
   "message": "",
   "data": [{
      "success": 0,
      "report_id": 123,
      "message": "ошибка генерации отчета на фронтенде: не удалось загрузить данные",
      "elapsed": 5.23
   }]
}
```

Пример ошибки валидации (HTTP 400)

```json
{
   "mode": "online",
   "status": 400,
   "message": "url обязателен\n[call:1761855093378813600]"
}
```

Настройка времени выполнения:

timeout — максимальное время (в секундах), которое система будет ждать генерации отчета. Это ваша «страховка» от вечного ожидания. Фактическое время может быть меньше (смотрите поле elapsed в ответе). Для сложных отчетов увеличивайте это значение;
delay — базовая задержка (в миллисекундах), которая учитывается при расчете времени ожидания внутри системы. Чем больше элементов в отчете, тем больше итоговое время ожидания.

Примечания

Стандартный формат ответа: все ответы используют обёртку {mode, status, message, data[]} независимо от HTTP статус кода.
Унифицированная структура данных: внутри data[] всегда одинаковый формат с флагом success.
Флаг success: всегда проверяйте data[0].success (1=успех, 0=ошибка) для определения результата операции.
Для диагностики доступен отладочный режим (debug: true), требующий права Debugging (роль DEVELOPER). Подробности в статье «Debug режим и диагностика».
Оптимальные значения: delay=1000ms, timeout=30s для большинства отчетов.
timeout определяет верхнюю границу: Backend не знает реального времени генерации на frontend, поэтому использует timeout как максимально допустимое время ожидания. Фактическое время может быть меньше (смотрите поле elapsed).
Увеличивайте timeout для сложных отчетов с долгой генерацией данных.
Мониторинг производительности: поле elapsed показывает реальное время выполнения.
Выходные форматы: pdf (по умолчанию), png, svg, pptx.

PDF параметры: page_size и page_orientation применяются только для output_type: "pdf".

Связи контента

Автоматический экспорт отчетов через API - База знаний Modus