← Назад к списку статей

Xeoma и JSON: управление модулями из системы автоматизации

Источники Фильтры Назначения

Давайте поговорим об автоматизации. Если вы читаете это предложение – вы всё ещё не закрыли страницу в ужасе, а значит, у вас есть шанс не только узнать о новом функционале Xeoma, но и применить его в деле. Итак, суть любой автоматизации в том, чтобы заставить разные устройства взаимодействовать, повышая таким образом общую эффективность. Наиболее важный фактор – отсутствие прямого человеческого контроля. Такая система напоминает много практиковавшийся хор: у каждого своя партия, но вместе они составляют единый музыкальный номер. Сейчас многим уже не понаслышке знакомо понятие домашней автоматизации, а тем из вас, кто ещё не окунался в этот вопрос, почти наверняка придётся это сделать в будущем.

На вопрос, как именно работает автоматизация, чёткого ответа нет и не предвидится, т.к. каждая такая система по-своему уникальна и требует отдельного рассмотрения. В этом деле особенно ценны различные способы интеграции, API и стандартные протоколы. Среди протоколов, наиболее часто используемых в веб-среде, в глаза быстро бросается JSON – JavaScript Object Notation – достаточно простой, но крепкий формат, ставший успешным наследником XML.
И теперь Xeoma научилась с ним работать.

Что же именно можно сделать с Xeoma посредством JSON? Так можно контролировать самую основу программы – её модули. Все модули. Продемонстрировать это проще всего будет на примерах.

Допустим у нас есть сервер с парой камер:

Цепочки модулей для них настроены так:

Самый наглядный способ проследить за работой данного API – это использовать плагин для Google Chrome, который называется «Tabbed Postman – REST Client». Избрали его мы по 2 причинам:

  1. GET-запросы можно отправлять через обычную адресную строку браузера, но ответ будет не слишком удобоваримым. Потенциальная автоматизация от этого не пострадает, но не будет и должной наглядности. Плагин сделает его более читаемым для человеческого глаза.
  2. POST-запросы нельзя отправлять через браузер, но можно средствами самой ОС (например, с помощью curl). Проблема этого способа в том, что он требует довольно глубоких познаний в области синтаксиса команд, а также работы с командой строкой. Плагин значительно более дружелюбен к новичкам.

Поясним: GET-запросы – это, по сути, вопросы, на которые Xeoma будет отвечать; POST-запросы – это инструкции, которые Xeoma будет выполнять. Для простоты мы будем отправлять команды на ту же машину, где открыт браузер, но API будет работать и при отправке команд удалённо, если доступен нужный порт (по умолчанию это 10090).

Первая команда запрашивает у Xeoma список используемых на данный момент на сервере модулей:

http://IP:10090/api?login=USERNAME&password=PWD&modules=

IP – это IP-адрес сервера (на той же машине будет localhost);
USERNAME – это имя пользователя Xeoma (имя главного администратора всегда Administrator);
PWD – это пароль данного пользователя.

В плагине команда будет выглядеть примерно так:

Нажав на кнопку Send, мы получим вот такой ответ (обязательно выберите пункты JSON и Pretty в параметрах ниже):

Здесь указаны обе наши цепочки (заключены в скобки {}), модуль-за-модулем. Под каждой цепочкой указано имя камеры, чтобы проще было их распознать (это особенно актуально для серверов, где автоматизация подразумевает большое число камер с одинаковыми цепочками).

Вторая команда запрашивает у Xeoma настройки конкретного модуля:

http://IP:10090/api?login=USERNAME&password=PWD&settings=MODULE_ID&get=

MODULE_ID – это уникальное имя модуля. Помните имена с номерам из ответа на предыдущий запрос (например, Date.Marking.13)? Это и есть уникальные имена.

В итоге команда будет выглядеть примерно так:

В этот раз ответ будет заметно длиннее:

Проще всего ориентироваться в нём по параметру type – типу объекта. Основных типов немного:

  • Label – это текстовое сообщение, обычно оно служит объяснением работы следующего объекта. Неизменяемый тип.
  • EditBox – это поле для ввода и редактирования текста пользователем. Изменяемый тип.
  • ComboBox – это выпадающий список или бегунок. У них часто встречается параметр translatedValues – это НЕ те параметры, которые можно изменять; реальные параметры всегда указаны в values. Изменяемый тип.
  • EditableComboBox – это тоже выпадающий список, но его содержимое может редактировать пользователь. Изменяемый тип.
  • CheckBox – это поле для галочки. Изменяемый тип.
  • ImageAreaSelector – это холст для рисования зоны у тех детекторов, которые работают с заданными зонами кадра. Изменяемый тип.
  • ProgressBar – это полоса, показывающая проценты от 0 до 100. Неизменяемый тип.
  • UndefinedType – это ссылка на веб-страницу, она не отображается в браузере (мы вернёмся к ней чуть позже). Неизменяемый тип.

И, наконец, последняя команда: она отправляет Xeoma инструкцию (POST), по которой будут изменены настройки того или иного модуля. Здесь всё немного сложнее, так как нам понадобится и URL, и изменяемые параметры. Сама команда составляется так:

http://IP:10090/api?login=USERNAME&password=PWD&settings=MODULE_ID&set=

Параметры и их значения указываем так:

{
“parameter1_name”:“parameter1_value”,
“parameter2_name”:“parameter2_value”,

}

Название параметров берём из пункта «id» в ответе на предыдущую команду (у каждого объекта оно своё).
Пример:

Внимание: обязательно укажите POST в качестве типа команды, а также выберите пункты raw и Text под строкой с командой. Будьте внимательны со строчными и прописными буквами, кавычками, запятыми и двоеточиями. Здесь важен каждый символ.

Если всё сделано правильно, то в ответ мы получим:

Новые настройки применились и сохранились.

В противном случае ответ будет таким:

Это обычно указывает на ошибку в синтаксисе команды, стоит тщательно проверить текстовую составляющую.

Работа с большинством типов объектов достаточно очевидна (например, CheckBox может быть либо true, либо false; EditBox позволяет указывать любой текст (как в одну строку, так и в несколько), и т.д.), но ImageAreaSelector заслуживает отдельного рассмотрения. Чтобы «нарисовать» нужную область в JSON, воспользуемся 0 и 1, где нули обозначают пиксели вне зоны детектирования, а единицы – пиксели внутри зоны детектирования. Для начала нужно задать масштаб в пикселях через параметры detectionAreaWidth (ширина) и detectionAreaHeight (высота) – по аналогии с, например, размерами холста в Photoshop. Допустим мы хотим работать с прямоугольником 6×4:
"detectionAreaWidth":6
"detectionAreaHeight":4

Таким образом, полностью пустая область без зоны детектирования будет выглядеть так:
000000
000000
000000
000000

Теперь добавим единицы, чтобы задать зону:
001111
001111
000111
000111

Удалив все лишние абзацы, получим такую команду:

Теперь наша зона детектирования выглядит так:

Теперь попробуем поменять настройки другого модуля – Маркировка. Допустим мы хотим изменить сам текст, его положение и размер:

Всё готово:

Как уже упоминалось ранее, JSON чаще всего применяется для интеграции через веб, т.е. прекрасно подходит для работы с веб-страницами. Xeoma воспринимает ещё одну команду, позволяющую сгенерировать готовую страницу с настройками нужного модуля:

http://IP:10090/api?login=USERNAME&password=PWD&settings=MODULE_ID

Здесь мы и вернёмся к UndefinedType – такие объекты на полученной странице отображаться не будут, но в коде они останутся, чтобы не сбить выравнивание всех остальных элементов:

Это касается всех модулей, изменения применятся по нажатию кнопки Сохранить внизу.
Если вы веб-разработчик, то, скорее всего, уже догадались, к чему мы клоним. Да, поскольку каждый элемент такой страницы (надписи, поля для ввода и т.д.) – это отдельный объект, то их можно взять со страницы, перестроить и поместить на собственной веб-странице, созданной для удобств: вашего и клиентов.

«Погодите-ка! – скажете вы. – А не станет ли это здоровенной дырой в безопасности? Ведь если потенциальный взломщик хорошенько подготовится, изучит этот API, то ему останется только подобрать мой пароль – и сервер можно хоронить.»
Мы тоже об этом подумали и можем предложить такие варианты защиты:

  1. Первый и самый надёжный способ – закрыть всё с помощью Apache (не североамериканских индейцев, а вот этого Apache). В этой статье мы подробно объясняем, как именно.
  2. API работает по веб-порту Xeoma (по умолчанию это 10090), но его можно легко сменить в настройках модуля Веб Сервер.
  3. Если этот порт доступен из внешних сетей (проброшен), то на файерволле роутера можно настроить правила и ограничения, чтобы этот доступ не попал не в те руки.

Как вы могли заметить, используемые в данном API имена модулей не всегда совпадают с их привычными именами. Поэтому представляем вашему вниманию таблицу, где собраны все модули с точными именами:

Модуль Имя Имя в JSON
ИСТОЧНИКИ
Универсальная камера UniversalCamera
Микрофон AudioSource
Захват экрана ScreenCapture
Чтение файла FileInput
Другая Xeoma WebConnectorReceiver
FTP Приёмник FTPReceiver
HTTP Приёмник HttpReceiver
ФИЛЬТРЫ
Детектор движения MotionDetector
PTZ-слежение PtzTracking
PTZ-слежение Senstar SenstarPtz
Счётчик посетителей VisitorsCounter
Детектор объектов ObjectDetector
Расписание Scheduler
Маркировка DateMarking
Маскирование зон AreaCensor
Коррекция панорамного изображения FisheyeUnwraper
Быстрое включение / выключение ButtonSwitcher
Детектор дня NightBlocker
HTTP Переключатель HttpSwitcher
HTTP Маркировщик HttpMarking
Детектор звука AudioDetector
Поворот изображения ImageTurn
Распознавание автономеров AutoNumberPlateRecognition
Детектор проблем ProblemsDetector
Детектор лиц FaceDetector
Объединитель ImageMerger
Уменьшение ImageResize
Обрезка изображения ImageCropping
Детектор оставленных предметов AbandonedObjectsDetector
Детектор дыма SmokeDetector
Детектор пересечения линии CrossLineDetector
Детектор Праздношатания LoiteringDetector
Реле-переключатель RelaySwitch
Условие Condition
НАЗНАЧЕНИЯ
Просмотр Preview
Просмотр и архив Preview%2BArchive
Сохранение в файл FileOutput
Отправка email Email
Отправка SMS SmsSender
Веб сервер WebconnectorTransmitter
RTSP Транслятор RtspTranslator
Отправка на FTP FtpOutput
HTTP Отправка на другую Xeoma HttpOutput
Звуковой сигнал AlarmSound
Запуск приложения AppRunner
Отправка HTTP команд HttpRequestSender
Всплывающее окно (на клиенте) ClientWindowPopup
Отправка автономеров на FTP AnprFtpUploader

5 октября 2018

Читайте также:
API Xeoma для синхронизации со сторонними сервисами и программами
Пример интеграции: Xeoma и приложение Telegram