Публичный 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 по шагам:
- Получить событие из набора VaAlarms и взять значение поля TelemetryId. Заранее отобрать события с видео условием VideoCount gt 0;
- Отобрать записи набора VaAlarmVideo или VaAlarmPhoto условием TelemetryId eq значение и взять поле Id нужной записи;
- Подставить это значение в адрес метода.
Идентификатор медиафайла не хранится в записи события напрямую, связь строится через телеметрию. Связь строится по полю 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 | Файл с указанным идентификатором не найден или удалён из хранилища. | ||