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

Содержание

Описание методов
Предусловия и ограничения
Формат запроса (Request Body)
Формат ответа (Responses Code)

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

В настоящий момент корректное взаимодействие с методами 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
$filter	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			Обращение по заведомо отсутствующему ключу. Такой же ответ приходит, если запись существует, но недоступна учётной записи по её правам: различить эти случаи на стороне клиента нельзя.

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

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