Интеграция в существующую систему

В этой статье описан типовой сценарий внедрения Flussonic Watcher с контролируемой продажей камер по подписке и учетом абонентов и их услуг в сторонней системе. Далее будут использоваться термины:

клиент — клиент компании Эрливидео, владелец сервиса
абонент — абонент у клиента, пользователь сервиса
биллинг — система внешняя к Watcher, в ней ведется тарификация услуг клиента абонентам и взимание денег

Сценарий следующий:

На партию камер заливается модифицированная прошивка с [Flussonic Agent](ispolzovanie-flussonic-agent.md#watcher-agent-page)
В этой прошивке зашита информация о том, к какому Flussonic Watcher надо привязать эту камеру
Камеру с серийником клиент заносит в систему инвентаризации биллинга, пока она ещё лежит на складе
При продаже абоненту, сотрудник клиента связывает в биллинге серийный номер камеры с идентификатором абонента
Камера получает данные для авторизации от нашего сервера при активации. Эти данные никак не связаны с идентификатором абонента, это авторизация камеры
Активированная камера немедленно начинает попытки соединения с Flussonic Watcher
Сервер активации посылает данные о камере напрямую в Watcher или в биллинг
Биллинг получает информацию о свежесозданной камере, добавляет к ней идентификатор абонента, занесенный ранее в систему инвентаризации
Биллинг отправляет информацию о свежесозданной камере в Watcher и камера там заводится. Этот и предыдущий пункты необходимо реализовать в рамках интеграции на стороне клиента
Теперь камера может подключиться к Watcher и начать отдавать поток

Важно то, что при такой организации процесса не требуется никакой настройки роутеров, камер и прочих сетевых устройств у абонента. После включения камеры в сеть она автоматически появится в личном кабинете.

Агент и модификация прошивки не являются обязательным требованием, всё может работать и со стандартными, неизмененными камерами, ниже будут описаны детали.

Подробнее об агенте в подробной статье.

API биллинга

Со стороны клиента надо реализовать в биллинге API для приема данных о свежесозданных камерах и отправку этих данных в Watcher. Такая схема с проксированием данных нужна для добавления информации о владельце камеры и услугах, которые доступны на этой камере.

Вся концепция подобного использования биллинга подразумевает, что именно он является центральным местом хранения данных в системе, а не Flussonic Watcher. Такая практика является стандартной и позволяет централизованно управлять услугами в разных системах, связывая, например, умный дом и видеонаблюдение в едином проекте.

Сервер активации, обслуживаемый Эрливидео, присылает запрос на сконфигурированный url (по вопросу конфигурации необходимо обратиться к техподдержке) с CSV или списком JSON объектов.

Все данные, которые присылает сервер активации надо переслать в Flussonic Watcher без изменений, если только нет задачи по какой-либо причине их поменять. Так, например, может прийти флаг ptz=1, его можно выставить в 0, если не хочется вообще управлять этой камерой в Watcher.

Поля, передаваемые от сервера активации (Эрливидео) в биллинг:

agent_model (строка) — модель камеры
agent_serial (строка) — серийный номер камеры
agent_id (строка) — уникальный номер агента на камере
agent_key (строка) — специальное поле, используемое для авторизации камеры Watcher’ом
stream_url (строка) — основной RTSP-URL потока
substream_url (строка) — вторичный RTSP-URL потока
thumbnails (строка) — URL снепшотов с камеры
onvif_url (строка) — URL по которому камера будет отвечать по onvif протоколу
onvif_profile (строка) — служебное поле
ptz (0 или 1) — вкл/выкл PTZ

Пришедшая от сервера активации информация должна создавать в биллинге новые записи для камер, либо «склеивать» эту информацию с уже существующими в биллинге или другой системе учета камер, камеры по параметру agent_serial (серийный номер камеры). Важно понимать, что agent_id может поменяться в случае, если камеру сбросили или передали другому абоненту. Серийный номер у камеры меняться не должен.

Т.е. если в биллинге существует система инвентаризации в которой камера привязывается к абоненту до первого включения, то новая запись появляться не будет, вместо этого надо заполнить пропущенные поля в существующей строчке в БД.

На стороне биллинга можно быть реализована возможность дозаполнять атрибуты к камерам, например привязка к владельцу или детали по управлению услугами для формирования тарифных планов.

Управление камерами в Watcher

Биллинг может управлять камерами, которые существуют в Watcher. В частности при получении данных от сервера активации он может дополнить данные своими полями и отправить информацию о камерах в Watcher.

Атрибуты заполняемые на стороне биллинга:

owner — (логин привязанного абонента).
dvr_depth (целое число в днях) - кол-во дней записи архива для камеры. 0 — отключает архив.
enabled (0 или 1) - вкл/выкл камеры.
access (private/public) - видимость камеры, публичная она будет (для всех абонентов) или приватная (только для owner'а камеры).

Разработка механизма создания тарифных планов и логики, которая будет влиять на доступ, глубину архива и прочие настройки, находится на стороне клиента.

После добавления полей индивидуальной настройки (owner, dvr_depth, enabled, access) необходимо отправить расширенный список камер в формате CSV в Watcher, по ссылке: http(s)://URL_ВАШЕГО_ВОТЧЕРА/vsaas/api/v2/cameras/import.

curl -v http://localhost:80/vsaas/api/v2/cameras/import \
  -d \
  '[{
  "name":"cam1","stream_url":"fake://clock","access":"private",
  "enabled":true,"dvr_depth":3,"agent_id":"123098456","agent_serial":"mJ0ODnktZFc",
  "agent_key":"salt:secretkey","owner":"alex@smith.com","dvr_path":"movies"
  }]' \
  -H "X-Vsaas-Api-Key: 7ab056b1-5bb1-4501-b528-d69538392842" \
  -H "Content-Type: application/json"
....
{
  "deleted": 0, 
  "updated": 0, 
  "errors": {}, 
  "created": 1
}

Здесь X-Vsaas-Api-Key: 7ab056b1-5bb1-4501-b528-d69538392842 это API key из настроек Watcher.

В случае если биллинг отправляет в Watcher камеру с идентификатором несуществующего пользователя (поле owner), Watcher создает нового пользователя. Его пароль при этом не передается. Мы подразумеваем, что клиент не хранит пароли абонентов в открытом виде и никак не может передать. Для того, что бы абонент мог залогиниться в Watcher, необходимо настроить внешний авторизационный бекенд в Watcher.

Управление пользователями (абонентами)

Параллельно с информацией по камерам можно отправлять в Watcher информацию об абонентах.

Вызов http(s)://URL_ВАШЕГО_ВОТЧЕРА/vsaas/api/v1/users

Пример:

curl -v http://localhost:80/vsaas/api/v2/users \
  -d \
  '[{
  "login":"user@domain.com","dvr_allowed":true,"external_id":"12346780"
  }]' \
  -H "X-Vsaas-Api-Key: 7ab056b1-5bb1-4501-b528-d69538392842" \
  -H "Content-Type: application/json"
...
[
  {
    "authorized_ip": null, 
    "enabled": null, 
    "id": null, 
    "note": null, 
    "is_admin": null, 
    "dvr_allowed": true, 
    "notification_email": null, 
    "external_id": "12346780", 
    "login": "user@domain.com"
  }
]

Полный список полей, которые можно отправлять по ссылке на полную документацию