Активация Агента из приложения собственной разработки
Активация Агента — это привязка Агента к конкретному серверу Watcher. Для привязки Агенту необходимо знать идентификатор оператора (Operator ID), по которому Агент запрашивает с сервера активации Эрливидео необходимую для подключения информацию. Подробнее о порядке работы Агента см. в разделе Как работает Агент.
Идентификатор оператора может быть встроен в Агент изначально или получен в процессе активации. Если производитель камеры уже добавил в Агент информацию о том, к какому Watcher он должен подключаться, то никакие дополнительные действия от разработчика не требуются: активация будет выполнена автоматически при запуске камеры с неактивированным Агентом независимо от того, используете ли вы приложение/веб-интерфейс Watcher или приложение/веб-интерфейс собственной разработки.
Если в камере Агент общего типа, не привязанный к конкретному серверу Watcher, и вы хотите разработать собственное приложение/веб-интерфейс для работы с таким Агентом, то необходимо будет реализовать API для активации Агента, т.е. для передачи Агенту данных (Operator ID, токен авторизации), с которыми Агент будет обращаться на сервер активации. Далее описано как это сделать.
Note
Если на камере Агент общего типа, не привязанный к конкретному Watcher, но вы используете мобильное приложение Watcher, то активация будет выполнена автоматически, поскольку мобильное приложение Watcher реализует приведенный ниже API.
Также может возникнуть необходимость в доработке прошивки камеры с Агентом таким образом, чтобы Агент можно было активировать поднесением QR-кода, как на камере с Iris. Об этом рассказано в конце этой статьи в разделе Отправка токена авторизации в Агент с помощью QR-кода.
Что такое токен авторизации Агента
Токен авторизации — это зашифрованная информация о названии камеры, ее пресете и организации, в которую ее требуется добавить. Токен служит уникальным идентификатором Агента в процессе активации.
Активация Агента осуществляется в следующем порядке:
- Приложение сообщает в Watcher о том, что нужно активировать камеру с указанием названия, организации и пресета.
- Watcher в ответ сообщает приложению токен авторизации камеры. Далее Watcher будет ждать камеру именно с таким токеном авторизации.
- Приложение передает токен авторизации в Агент (через QR-код или HTTP-запросом).
- Агент передает токен авторизации на сервер активации.
- Сервер активации присваивает токену авторизации agent_id, agent_key, watcher_url и передает их в Агент и в Watcher/биллинг вместе с токеном авторизации.
- Watcher проверяет, известен ли ему такой токен авторизации, и добавляет камеру в указанную организацию абонента с указанным именем и пресетом.
Первые три шага нужно реализовать в приложении.
Запрос токена авторизации
В первую очередь приложение должно запросить у Watcher токен авторизации агента следующим запросом:
POST URL_ВАШЕГО_WATCHER/vsaas/api/v2/agent-activation-tokens
В заголовке передаются параметры x-vsaas-session и content-type: application/json
Caution
В запросе нужно использовать именно ключ x-vsaas-session, подробнее о типах ключей см. на странице Способы авторизации API-запроса. С ключами других типов запрос не сработает.
Тело запроса в формате JSON должно включать следующие параметры:
- "title" — строка, имя камеры, с которым она добавится в Watcher.
- "organization_id" — целое число, идентификатор организации, в которую будет добавлена камера.
- "preset_id" — целое число, идентификатор пресета, с которым будет добавлена камера.
Организации и пресеты должны быть предварительно созданы в Watcher. Вы можете создавать организации и пресеты на свое усмотрение как из интерфейса, так и с помощью API.
В ответ придет JSON со строковым параметром "token". Это и есть токен авторизации, который в дальнейшем нужно будет передать в Агент. Также в ответе может быть указан срок действия токена в параметре valid_till.
Пример (замените x-vsaas-session на свой ключ)
curl -v POST http://127.0.0.1/vsaas/api/v2/agent-activation-tokens \
-d '{"title": "activateCam", "organization_id": "1", "preset_id": "1"}' \
-H 'x-vsaas-session: j9h2Hxu_o9Gf0TyoPjesLLBkBbc' -H "Content-Type: application/json"
Ответ
{"token":"MURAELYI","valid_till":0}
Затем нужно проверить, не добавлена ли уже камера с таким токеном:
GET URL_ВАШЕГО_WATCHER/vsaas/api/v2/agent-activation-tokens/(token)
В заголовке запроса передать x-vsaas-session: ...
В ответ придет JSON со строковым параметром "camera_name". Если токен еще не используется, т.е. камера не добавлена, то параметр будет иметь значение null. В этом случае можно переходить к активации Агента по IP-адресу или QR-коду, как описано далее.
Danger
Если камера уже добавлена, повторное добавление с тем же токеном может привести к ошибкам.
Пример (замените x-vsaas-session на свой ключ)
curl -v GET http://127.0.0.1/vsaas/api/v2/agent-activation-tokens/MURAELYI \
-H 'x-vsaas-session: j9h2Hxu_o9Gf0TyoPjesLLBkBbc' -H "Content-Type: application/json"
Ответ
{"token":"MURAELYI","valid_till":0,"camera_name":null}
Отправка токена авторизации в Агент по IP-адресу
Получив токен авторизации и убедившись в том, что камеры еще нет в Watcher, приложение должно передать полученные данные Агенту. Запрос отправляется на адрес камеры, по которому она доступна из мобильного приложения, с указанием порта 5680:
POST URL_КАМЕРЫ:5680/activate
В заголовке запроса передается параметр Content-Type: application/x-www-form-urlencoded;charset=UTF-8. Другие форматы не поддерживаются.
Передаваемые параметры:
- "operatorid" — уникальный идентификатор оператора связи, зарегистрированного на сервере активации. Его можно посмотреть в интерфейсе Watcher, см. Мобильные приложения. Этот идентификатор не меняется, его можно зафиксировать в коде приложения.
- "sign" — полученный ранее token
- "abonentid" — адрес электронной почты абонента
Пример
curl -v POST http://192.168.1.64:5680/activate \
-d 'operatorid=44766&sign=MURAELYI&abonentid=user.name@gmail.com' \
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
В ответ Агент вернет статус 200 и обратится на сервер активации.
Чтобы проверить, активировался ли Агент, запросите его статус:
URL_КАМЕРЫ:5680/agent-status
Такой запрос вернет параметры:
- version — версия Агента
- status — статус Агента: activate или wait_activate
- serial — серийный номер камеры
Пример
curl -v GET http://192.168.1.64:5680/agent-status
Ответ
{version: 'v19.05-84-gc4b3544bf', status: 'wait_activate', serial: 'f8f86484c5bf6f327e6de196205e7'}
Отправка токена авторизации в Агент с помощью QR-кода
Камеры с Агентом можно активировать поднесением QR-кода к камере. Wi-Fi-камеры IRIS активируются QR-кодом без каких-либо доработок прошивки, а для камер сторонних производителей нужна дополнительная интеграция между разрабатываемым приложением и прошивкой камеры, т.е. модификация прошивки камеры для приема данных из QR-кода и передачи их в файл конфигурации Агента.
Формат QR-кода для камер IRIS — текст, содержащий три строки:
Wifi_SSID
Wifi_Password
operator_id:token
operator_id — это уникальный идентификатор провайдера, зарегистрированного на сервере активации. Его можно посмотреть в интерфейсе Watcher, см. Мобильные приложения. Этот идентификатор не меняется, его можно зафиксировать в коде приложения.
Деактивация агента
Для деактивации рабочего Агента нужно удалить камеру из Watcher.