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

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

Далее будут использоваться термины:

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

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

Перед добавлением абонентской камеры в любом случае необходимо создать в Watcher соответствующую структуру организаций и пресетов, назначить абоненту те или иные права. Это можно сделать как из интерфейса Watcher, так и с помощью соответствующих запросов API для управления организациями, папками, пользователями. Механизм сопоставления тарифных планов биллинга и пресетов Watcher, а также логика, которая будет влиять на доступ, глубину архива и прочие настройки, находится на стороне биллинга.

Сценарии интеграции при использовании камер с агентом и без него отличаются. Они описаны ниже отдельно.

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

Создание пресетов¶

Пресет — это предварительно заданный набор настроек архива и аналитики, которые можно применить на камере. Пресеты соответствуют тарифам в биллинге, поэтому их нужно настроить перед добавлением камер.

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

Ненастраиваемый пресет на камере

Владельцы Организаций не могут создавать, редактировать и удалять пресеты: такие права есть только у Администратора Watcher. Если к Организации привязано несколько пресетов, то владелец Организации сможет поменять один пресет на другой в настройках камеры.

Пресеты можно создавать из биллинга с помощью следующего API-запроса:

POST http(s)://URL_ВАШЕГО_WATCHER/vsaas/api/v2/presets

Обязательный параметр title — название пресета.

Пример запроса для создания ненастраиваемого пресета (параметр is_adjustable=false), задающего глубину архива 2 дня:

curl -v POST http://127.0.0.1/vsaas/api/v2/presets \
-d '{"title":"non-adjustable preset","is_adjustable":false, "organization_id":"1", "dvr_depth": 2}' \
-H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a368d' \
-H "Content-Type: application/json"

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

{
    "is_default": false,
    "is_deleted": false,
    "title": "non-adjustable preset",
    "dvr_space": null,
    "id": 1,
    "is_adjustable": false,
    "dvr_depth": 2,
    "vision_areas": null,
    "precise_thumbnails_days": 0,
    "vision_enabled": null,
    "vision_alg": null,
    "vision_gpu": null,
    "domain_id": 1,
    "dvr_lock_days": null,
    "vision_params": {}
}

Также доступны запросы GET/PUT/DELETE http(s)://URL_ВАШЕГО_WATCHER/vsaas/api/v2/presets/{preset_id} для получения/изменения/удаления пресета с заданным идентификатором.

Камеры с агентом¶

Сценарий работы интеграции при использовании камер с агентом:

На партию камер устанавливается модифицированная прошивка с Flussonic Agent. В этой прошивке содержится информация о том, к какому Flussonic Watcher надо привязать эту камеру
Камеру с серийным номером оператор связи заносит в систему инвентаризации биллинга, пока она ещё лежит на складе
При продаже абоненту сотрудник оператора связи в биллинге ставит в соответствие серийному номеру камеры идентификатор абонента
При подключении к сети камера получает данные для авторизации от сервера активации. Эти данные никак не связаны с идентификатором абонента, это авторизация камеры.
Активированная камера немедленно начинает попытки соединения с Flussonic Watcher
Сервер активации посылает данные о камере в биллинг

Note

Сервер активации может отправлять данные о камере напрямую в Watcher, если при активации камеры с агентом уже известна информация о ее владельце (например, если камера IRIS активирована из приложения). Это зависит от типа агента и требований к интеграции. Для настройки сервера активации обратитесь в техническую поддержку Flussonic Watcher.
Биллинг получает информацию о свежесозданной камере, добавляет к ней информацию о пресете (тарифе) и организации.
Биллинг отправляет информацию о свежесозданной камере в Watcher. Этот и предыдущий пункты необходимо реализовать в рамках интеграции на стороне биллинга.
Теперь камера может подключиться к Watcher и начать отдавать поток

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

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

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

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

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 (строка) — служебное поле
can_ptz (0 или 1) — вкл/выкл PTZ
abonent_sign (целое число) — зашифрованная информация об организации и пользователе-владельце камеры. Присутствует только для соответствующего типа агента, когда абонент вручную добавляет камеру в свою организацию через мобильное приложение или веб-интерфейс Watcher. Если это поле заполнено, добавление информации о владельце камеры не требуется.

Warning

Получив данные, биллинг должен вернуть серверу активации ответ "200". В противном случае сервер активации будет повторять отправку данных вплоть до получения этого подтверждения.

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

Note

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

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

После добавления полей индивидуальной настройки (preset_id, enabled, organization_id) необходимо отправить информацию о камере в формате CSV или JSON в Watcher, используя один из следующих запросов:

POST http(s)://URL_ВАШЕГО_WATCHER/vsaas/api/v2/cameras/import для добавления нескольких камер

POST http(s)://URL_ВАШЕГО_WATCHER/vsaas/api/v2/cameras для добавления одной камеры

Пример запроса для добавления нескольких камер приведен ниже. Обратите внимание, что параметр X-Vsaas-Api-Key необходимо заменить на тот, который указан в настройках Watcher.

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

Если не указать в запросе идентификатор пресета и организации, то камера будет добавлена в организацию по умолчанию с пресетом по умолчанию.

Камера без агента¶

Сценарий интеграции для камер без агента (например, RTSP, ONVIF) обычно следующий:

Камера подключается к внутренней сети оператора связи
Абонент оставляет оператору связи запрос на подключение к камере.
Запрос на добавление камеры абоненту или выдачу абоненту прав на камеру поступает от оператора связи в биллинг.
Если подключается новая личная камера абонента, например, в систему умного дома:
- Предполагается, что в Watcher уже создан пользователь и организация для абонента. Если их нет, нужно их создать из интерфейса или с помощью соответствующих запросов API из биллинга.
- Биллинг заполняет необходимые атрибуты камеры в соответствии с тарифом.
- Биллинг отправляет в Watcher запрос на добавление камеры абоненту (см. пример ниже).
Если абонент хочет подключиться к общей камере, например, к домофону или к системе "Безопасный город":
- Предполагается, что в Watcher уже создана соответствующая камера и организация. Если их нет, нужно их создать из интерфейса или с помощью соответствующих запросов API из биллинга.
- Биллинг заполняет необходимые атрибуты пользователя (абонента) для добавления в организацию, в которую добавлена необходимая камера.
- Биллинг отправляет в Watcher запрос на создание или обновление пользователя (абонента) (см. пример ниже).

Добавление камеры¶

POST http(s)://URL_ВАШЕГО_WATCHER/vsaas/api/v2/cameras/import для добавления нескольких камер.

POST http(s)://URL_ВАШЕГО_WATCHER/vsaas/api/v2/cameras для добавления одной камеры.

В запросе на добавление камеры обязательно должны быть указаны следующие параметры:

preset_id (целое число) — идентификатор пресета Watcher, соответствующего тарифу в биллинге.
stream_url (строка) — основной RTSP-URL потока.
organization_id (целое число) — идентификатор организации. Организация должна быть уже создана в Watcher.

Простейший пример запроса на добавление одной камеры приведен ниже. Этот запрос можно скопировать и выполнить на сервере с установленным Watcher. Обратите внимание, что параметр X-Vsaas-Api-Key необходимо заменить на тот, который указан в настройках Watcher.

curl -v -X POST http://127.0.0.1/vsaas/api/v2/cameras \
-H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a368d' \
-H 'content-type: application/json' \
-d '{
  "title": "myCamera",
  "stream_url": "fake://clock",
  "preset_id": "1",
  "organization_id": "1"}'

В результате выполнения такого запроса виртуальная камера под названием "myCamera", транслирующая время ("stream_url": "fake://clock"), будет добавлена в организацию по умолчанию ("organization_id": "1") с пресетом по умолчанию ("preset_id": "1"). В ответ на запрос Watcher вышлет JSON со списком всех параметров добавленной камеры.

Добавление пользователя¶

POST http(s)://URL_ВАШЕГО_WATCHER/vsaas/api/v2/users

Пример:

Обратите внимание, что параметр X-Vsaas-Api-Key необходимо заменить на тот, который указан в настройках Watcher.

curl -v POST http://127.0.0.1/vsaas/api/v2/users \
-d '{"login":"user1", "organization_id":"1"}' \
-H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a368d' \
-H "Content-Type: application/json"

В результате выполнения этого запроса пользователь user1 будет добавлен в организацию по умолчанию ("organization_id":"1").

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

Пример с обновлением пользователя см. ниже.

Отключение камеры абоненту по инициативе биллинга¶

В случае, если абонент по какой-то причине не должен больше пользоваться камерой (например, отключил услугу или не внес оплату вовремя), биллинг должен отправить в Watcher соответствующий запрос.

Самый простой вариант — отключить пользователя. Это можно сделать запросом вида PUT https://watcher_api_url/vsaas/api/v2/users/(int:user_id), задав параметру enabled значение false.

Пример:

curl -v -X PUT http://127.0.0.1/vsaas/api/v2/users/5 \
-H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a3687' \
-H 'content-type: application/json' -d '{"enabled":false}'

Также есть следующие основные варианты ограничения прав без отключения пользователя:

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

Отключить камеру можно запросом PUT https://watcher_api_url/vsaas/api/v2/cameras/(string:cam_name), задав параметру enabled значение false.

Пример

curl -v -X PUT -H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a3687' -H 'content-type: application/json' \ http://127.0.0.1/vsaas/api/v2/cameras/inst1cam-8e1a6e020e -d '{"enabled":false}'

Note

Обратите внимание, что название камеры в интерфейсе может не совпадать с названием в БД.
Личная камера абонента, которой никто не пользуется, кроме него, и абонент имеет права на редактирование камер.

Необходимо отключить пользователю возможность редактировать камеры запросом PUT https://watcher_api_url/vsaas/api/v2/users/(int:user_id), задав параметру readonly значение true.

curl -v -X PUT -H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a3687' -H 'content-type: application/json' \ http://127.0.0.1/vsaas/api/v2/users/5 -d '{"readonly": true}'

Затем необходимо отключить сами камеры как описано в п. 1.
Камера в общем доступе, ей пользуются многие абоненты (например, видеодомофон в многоквартирном здании или камера системы "Безопасный город")

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

Запрос на удаление прав на доступ к папке имеет вид

DELETE https://watcher_api_url/vsaas/api/v2/organizations/(int:organization_id)/folders/(int:folder_id)/users/(int:user_id)

Пример запроса на ограничение доступа пользователю с идентификатором 3 к папке с идентификатором 2 в организации с идентификатором 1:

curl -v -X DELETE -H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a368d' -H 'content-type: application/json' \ http://127.0.0.1:80/vsaas/api/v2/organizations/1/folders/2/users/3