Публичный API [3.0]. Видеоаналитика. Метаданные фотоматериалов событий
Содержание
Описание методов
В настоящий момент корректное взаимодействие с методами API гарантируется только при использовании клиента Postman (файлы коллекции и окружения).
Внешний контур событий видеоаналитики предоставляет доступ к метаданным фотоснимков, полученных по событиям по протоколу OData v4.
| Метод | Описание |
| GET /odata/VaAlarmPhoto | Возвращает коллекцию метаданных фотоснимков, полученных по событиям видеоаналитики. Удалённые файлы в выборку не попадают. Связь с событием устанавливается по полю TelemetryId. |
| GET /odata/VaAlarmPhoto({key}) | Возвращает метаданные одного фотоснимка по идентификатору. Каноническая форма записи ключа в OData. Эквивалентна форме с сегментом пути. Значение подставляется из переменной mediaFileId, которую заполняет скрипт запроса коллекции. |
| GET /odata/VaAlarmPhoto/{key} | Поддерживается для клиентов, не работающих со скобками в адресе. Результат идентичен канонической форме. |
| GET /odata/VaAlarmPhoto/$count | Возвращает количество записей, доступных учётной записи, с учётом применённого $filter. Тело ответа - целое число без обёртки. |
Предусловия и ограничения
- Требуется аутентификация
- При работе с методом УЗ должна быть присвоена роль со следующими скоупами для работы:
| Метод | Назначение метода | Scope | Чек-боксы в справочнике ролей для scope |
| GET /odata/VaAlarmPhoto | Выборка метаданных фотофайлов событий | externalVaAlarmVideo:read |
«Таблица Событий. Скачивание видео» |
| GET /odata/VaAlarmPhoto({id}) | Метаданные одного фотофайла по идентификатору | externalVaAlarmVideo:read |
«Таблица Событий. Скачивание видео» |
Ограничения:
- Все методы только на чтение;
- Размер страницы $top - не более 1000; большие объёмы - постраничный обход с $skip и сортировкой;
- Скачивание содержимого видеофайлов и фотоснимков - в разработке: сейчас API отдаёт метаданные, файлы доступны через интерфейсы SKAI;
- Пакетные запросы OData не поддерживаются.
Поиск TelemetryId по шагам:
1) выбрать события с VideoCount gt 0;
2) взять из события TelemetryId;
3) выбрать файлы фильтром по нему.
Валидация события не требуется - файлы доступны при любом статусе.
Формат запроса (Request Body)
| Атрибут | Поле | Тип | Обязательность | Описание |
|
$filter
|
beginFrom |
String
|
Нет
|
Дата и время начала периода фильтрации. ISO 8601. Пример: 2026-08-01T00:00:00Z
|
|
beginTo
|
String
|
Нет
|
Дата и время конца периода фильтрации. ISO 8601. Пример: 2026-08-02T00:00:00Z
|
|
|
$select
|
AlarmId,
TelemetryId, Begin, End, Type, AlarmStatus, RegulationStatus, UnitStateNumber, DriverFullName, VideoCount |
String
|
Нет
|
Массив полей, включаемых в ответ. Пример: ["AlarmId","Begin","UnitStateNumber"]
|
|
$orderBy
|
|
String
|
Нет
|
Поле и направление сортировки (asc / desc). Пример: Begin asc
|
|
$top
|
|
Integer
|
Нет
|
Максимальное количество возвращаемых записей. Пример: 100
|
|
$skip
|
|
Integer
|
Нет
|
Количество пропускаемых записей от начала выборки. Применяется вместе с $top.
|
|
$count
|
|
Boolean
|
Нет
|
Признак включения общего количества записей в ответ в поле @odata.count. Не учитывает $top и $skip.
|
Пример запроса:
GET /odata/VaAlarmPhoto?$filter=TelemetryId eq '17223456789012345'&$orderby=Channel asc
Формат ответа (Responses Code)
В случае успеха метод возвращает ответ с кодом 200 и телом ответа в формате OData JSON:
|
Поле
|
Атрибут
|
Тип
|
Описание
|
| @odata.context |
- | String | URL-ссылка на контекст метаданных OData |
| value | - | Array | Массив объектов с данными |
| Id | UUID | Идентификатор медиафайла, ключ сущности | |
| Channel | Integer | Номер канала (камеры), с которого записан файл. Задаётся конфигурацией терминала (например, 1 - фронтальная, 3 - салонная). |
|
| TelemetryId | String или null | Идентификатор события, сгенерированный оборудованием | |
| AlarmId | UUID или null | Идентификатор события | |
| CreatedAt | DateTime | Дата и время появления файла в хранилище |
Пример ответа:
{
"value": [
{ "Id": "8c1f2a3b-4d5e-4f60-9a7b-1c2d3e4f5a6b", "Channel": 1,
"TelemetryId": "17223456789012345",
"AlarmId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"CreatedAt": "2026-08-01T07:15:40+03:00" },
{ "Id": "9d2e3b4c-5e6f-4071-8b8c-2d3e4f5a6b7c", "Channel": 3,
"TelemetryId": "17223456789012345",
"AlarmId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"CreatedAt": "2026-08-01T07:15:52+03:00" }
]
}
В случае ошибок авторизации или валидации запроса метод возвращает код, соответствующий ошибке, и тело в формате OData:
| Тело ответа | Тип | Обязательность | Описание | |
| error | Object[] | Да | Корневой объект, содержащий информацию об ошибке | |
| code | String | Да | Машиночитаемый код ошибки | |
| message | String | Да | Человекочитаемое сообщение об ошибке | |
| target | String | Нет | Цель ошибки (например, имя поля) | |
| details | Object[] | Да | Массив детализированных ошибок | |
| 200 (пусто) | - |
Учётной записи не открыт доступ к данным: не назначены транспортные средства, либо не выдан доступ на просмотр | ||
| 400 | Bad Request | Значение $top свыше предела 1000. Ошибка синтаксиса, неизвестное поле, $top > 1000 |
||
| 401 | Unautorized | Токен невалидный или истек срок действия. Запрос без авторизации. Ожидаемый код 401 подтверждает, что маршрут опубликован и защищён. Если вместо 401 приходит 404, неверен базовый адрес или контур. |
||
| 403 | Forbidden | Учётной записи не выдано нужное право | ||
| 404 | Not Found | Обращение по заведомо отсутствующему ключу. Такой же ответ приходит, если запись существует, но недоступна учётной записи по её правам: различить эти случаи на стороне клиента нельзя. |
||