Публичный API [3.0]. Видеоаналитика. Скачивание медиафайлов событий

Содержание

Описание методов

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

Внешний контур медиафайлов событий предоставляет доступ к скачиванию видеозаписей/фотоснимков, полученных по событиям видеоаналитики. Файл через OData не передаётся, поэтому для получения содержимого применяется отдельный метод. Адрес метода расположен в разделе контура /data и не входит в модель OData: query options к нему не применяются.

Метод Описание
GET /data/media-files/va-alarms/{mediaFileId} Скачивание выбранных медиафайлов.

Значение подставляется из переменной mediaFileId, которую заполняет скрипт запроса коллекции.

Предусловия и ограничения

Метод Назначение метода Scope Чек-боксы в справочнике ролей для scope
GET /data/media-files/va-alarms/{mediaFileId}
Скачивание видеофайлов событий
mediafiles:read


externalVaAlarmVideo:read

Права на метаданные для получения содержимого недостаточно.
«Просмотр таблицы событий»,  «Просмотр таблицы событий с ограничениями»

«Таблица Событий. Скачивание видео»

Ограничения:

Поиск TelemetryId по шагам:

  1. Получить событие из набора VaAlarms и взять значение поля TelemetryId. Заранее отобрать события с видео условием VideoCount gt 0;
  2. Отобрать записи набора VaAlarmVideo или VaAlarmPhoto условием TelemetryId eq значение и взять поле Id нужной записи;
  3. Подставить это значение в адрес метода.

Идентификатор медиафайла не хранится в записи события напрямую, связь строится через телеметрию. Связь строится по полю TelemetryId, а не по AlarmId: поле AlarmId в записях медиафайлов заполнено не для всех записей.
Валидация события не требуется - файлы доступны при любом статусе.

Формат запроса (Request Body)

Атрибут Тип Обязательность Описание
mediaFileId
UUID
Да
Значение поля Id записи набора VaAlarmVideo или VaAlarmPhoto.

Идентификаторы файлов других типов методом не обслуживаются.

Пример запроса:

curl -OJ "https://public.skai.online/data/media-files/va-alarms/<mediaFileId>" \
  -H "Authorization: Bearer <access_token>"

Формат ответа (Responses Code)

В случае успеха метод возвращает ответ с кодом 200 и телом ответа. Тело ответа содержит медиафайл в двоичном виде (не JSON). Характеристики файла передаются заголовками.

Поле
Тип
Описание
Content-Type String Тип содержимого

Пример: video/mp4 для видеозаписи, image/jpeg для фотоснимка
Content-Length Integer Размер содержимого в байтах

Пример: 1161295
Content-Disposition                      String Имя файла для сохранения

Пример: attachment; filename="<терминал>/<телеметрия>/1.mp4"

Имя файла содержит путь; при сохранении путь отбрасывается и остаётся короткое имя вида 1.mp4, одинаковое у файлов разных событий. При массовой выгрузке имя формируется на стороне клиента. Частичная загрузка по заголовку Range не поддерживается: сервер отвечает кодом 200 и передаёт файл целиком.

В случае ошибок авторизации или валидации запроса метод возвращает код, соответствующий ошибке, в формате JSON:

Тело ответа Тип Обязательность Описание
error Object[] Да Корневой объект, содержащий информацию об ошибке
code String Да Машиночитаемый код ошибки
message String Да Человекочитаемое сообщение об ошибке
target String Нет Цель ошибки (например, имя поля)
  details Object[] Да Массив детализированных ошибок
401  Unautorized  Токен отсутствует, просрочен, не прошёл проверку, либо в нём нет права mediafiles:read
403 Forbidden   Учётной записи не выдано нужное право

В токене есть mediafiles:read, но нет externalVaAlarmVideo:read, либо файл относится к недоступному владельцу токена терминалу
404 Not Found   Файл с указанным идентификатором не найден или удалён из хранилища.

Номер материала: 5870
Отправлено: Thu, Aug 13, 2026
Последнее обновление: Fri, Sep 18, 2026
Отправлено: Эфендиева Валерия Руслановна [v.efendieva@skai.online]

Online URL: https://kb.skai.online/article/Публичный-api-3-0-Видеоаналитика-Скачивание-медиафайлов-событий-5870.html