Open API Ivideon: первые шаги
Как же быстро время пролетело: наш предыдущий пост вышел на Хабре 2 года назад. Когда молчишь так долго, ты либо мертв, либо усердно работаешь, чтобы в один момент взорваться новостями и поведать что-то стоящее.
Если вы не знаете, кто мы, то объясним в четырех словах: сервис видеонаблюдения через Интернет. За остальными подробностями отсылаем к самой первой статье.
Вот и в Ivideon занимались стоящим проектом — Open API. Да, это открытый API, позволяющий нашим клиентам и партнерам упростить и автоматизировать взаимодействие с нашим сервисом. И даже создавать новые продукты!
Проект пока что находится на стадии бета-тестирования, но вы, если желаете, можете попробовать API. Подробнее об этом расскажем в конце статьи.
Как мы пришли к Open API
К идее начать разработку мы пришли самым простым способом — клиенты просили предоставить возможность управлять Ivideon«ом как сервисом: самостоятельно подключать и отключать камеры видеонаблюдения, менять тарифные планы, управлять настройками камер, изменять качество и расписание записи, увеличивать или уменьшать громкость, воспроизводить запись в приложении клиента или на сайте.
Раз есть спрос, значит, мы должны были обеспечить предложение: предоставить наш интерфейс другим компаниям и пользователям, хорошо структурировав его и написав внятную документацию.
Структура
Параллельно с API шло развитие наших интеграционных компонентов SDK, отвечающих за воспроизведение: это Web SDK, написанный на Javascript, и Mobile SDK. В основе обоих SDK лежит модифицированный видеоплеер из проекта VLC, используемый для воспроизведения live-видео и архивного видео на веб-странице или в мобильном приложении. То есть это fork непосредственно VLC библиотеки с достаточно большим количеством дополнений, и оптимизаций, которые мы сделали сами.
Алгоритм действий нашей системы подразумевает появления некоторых задержек, но на камерах у нас реализован предбуфер, записывающий видео за несколько секунд до того, как непосредственно произошло событие. Предбуфер позволяет компенсировать всякие сетевые задержки.
Предбуфер хранит последние 5 секунд (примерно) живого видео, но при этом камера его никуда не отправляет. Если приходит запрос, камера начинает запись, берет последние 5 секунд и также их отправляет. Поэтому в любой запрос мы включаем чуть более раннее видео, чем отмечено самим запросом.
Возможности
С помощью Open API вы можете создать собственную альтернативу личному кабинету Ivideon. Вы можете экспортировать видео по запросу, настроить регулярное событие, которое будет раз в день запрашивать видео за определенный промежуток времени, получать ссылку на видео и скачивать его себе. Мы стремимся к тому, чтобы все доступные компоненты могли быть настроены клиентом под свои нужды. Это касается цветов, картинок, кнопок, внешнего вида, стиля и так далее, чтобы всё визуально вписалось в любую клиентскую систему.
Отдельная ветка функций связана с событиями. Суть такая: в сторонней системе пользователь может создавать события, публиковать его в нашем API, и камера по этому событию будет производить запись видеоклипа. Сейчас она производит запись исключительно короткого клипа, в районе 10 — 30 секунд. Развитие этой функции дает возможность записывать клипы по каким-то внешним событиям, не связанным непосредственно с камерами — например, открылась дверь, сработал датчик движения и так далее. Мы также прорабатываем функцию, которая либо заменит эти клипы, либо станет дополнением к ним — это запись от начала до конца.
Типы использования
Есть две схемы, как всё работает: для личного использования и когда клиент выступает в роли реселлера.
Первая схема подходит для обычных пользователей, которые просто хотят что-то автоматизировать, а также для крупных компаний, использующих возможности Open API для себя. Так как на наших камерах есть детектор движения и детектор звука, с помощью API вы можете интегрировать систему в свою умный дом: получать SMS при каком-то событии, запрашивать live-видео и т.д.
По второй схеме бизнес-партнер, который с нами интегрирован, может создавать других пользователей, то есть перепродавать услуги своим клиентам.
Примеры использования
Один наш крупный партнер установил себе сотни камер и стал искать способ, как упростить передачу прав доступа на камеры. Стандартно Ivideon через веб-интерфейс позволяет передавать права на просмотр онлайна, передавать права на просмотр архива и передавать права на управление камерами (двигать камеры, включать и выключать). Однако все эти права нужно было передавать вручную: выбрать камеру, выбрать e-mail пользователя, указать, какие права ему передать. Когда у вас 10 камер, с этим справится один человек. Когда у вас сотни камер, разбросанных по всей России, и десятки пользователей — начинается сильная боль.
Как вы понимаете, очень неудобно учитывать все передачи прав. С помощью технологии, которая получила название «Группировка камер», появляется возможность указать иерархию: например, крупный регион, город в регионе, отдельные районы в городе и так далее. Камеры можно распределить по всему дереву, и давать человеку доступ (или забирать доступ) сразу к определенной группе камер.
Следующий пример использования Open API будет интересен и обычным пользователям, поскольку затрагивает функциональность умного дома. Среди наших клиентов есть несколько компаний, занимающихся технологиями умного дома. Например, в США работает команда, разрабатывающая систему, которая позволяет открывать гараж или какое-то отдельное помещение, передавая одноразово сгенерированный код доступ третьим лицам.
Ваш дом сам примет за вас посылку, пока вы находитесь в отъезде. Курьер приезжает с грузом, получает одноразовый код, открывающий гараж, кладет туда посылку, после чего дверь закрывается и блокируется.
Этой системе не хватало самого главного — видеонаблюдения. А что если курьер украдет из гаража велосипед? В идеале нужно было видеть, что курьер пришел, занес посылку и ушел, ничего с собой не забрав. Для этого можно опубликовать событие в приложении непосредственно в нужный момент, и при этом записать клип. Можно также все время вести live-трансляцию прямо в мобильное приложение. Такую систему легко реализовать с помощью подходящего микроконтроллера и любой камеры с Ivideon на борту.
Когда происходит какое-то событие, за которым должна следовать запись видео, на центральном контроллере умного дома нужно установить идентификацию события — оно отправится нам, после чего нашего облако отправит на камеру команду «запиши». Затем вы отправляете к нам запрос и получаете ссылку, по которой можно скачать видеоклип, куда-то отправить или встроить.
Допустим, вы получаете образование удаленно, и все лекции обрабатываете на дому, но на экзамены все равно вынуждены приходить. В тоже время, сдавать экзамены можно и с помощью системы видеонаблюдения. В присутствии проктора происходит компьютерное тестирование знаний учащегося. Сначала происходит идентификация, например, демонстрация паспорта. Затем происходит выдача заданий, интервьюирование с конкретным человеком. Преподавателю в процессе транслируется видео с веб-камеры и с экрана. Запись хранится какое-то время в облаке и в случае возникновения спорных вопросов предоставляется сторонам конфликта.
Мы и раньше интегрировались с корпоративными и бизнес-приложениями (СКУД, ОПС, кассовыми аппаратами), но развитие API позволяет к видеонаблюдению добавить видеоаналитику — простор для введения новых фич огромный. Трудно сейчас предположить, сможете ли вы искать покемонов с помощью камер видеонаблюдения, но вы точно узнаете о зарегистрированном камерой потенциально опасном событии.
Для малого и среднего бизнеса одно из самых уязвимых мест (в финансовом плане) расположено сразу у кассы. Выявление шаблонных алгоритмов действий кассира помогает определить воровство или нарушение дисциплины (когда кассир не обслуживает клиентов, а занят своими делами). Система видеонаблюдения отслеживает кассовые события параллельно с фиксируемой камерой видеозаписью, позволяя наглядно определить факт мошенничества. Самый простой пример: в случае, если покупатель не забрал чек, значит его не обязательно «закрывать» или фискализировать — кассир отменяет чек и деньги забирает себе.
Мониторинг событий у кассовых терминалов — это лишь один из возможных вариантов. Если кто-то захочет в будущем поставить камеры наблюдения на пляж и найти всех людей с родинкой в форме пятиконечной звезды — Ivideon подключится к решению. :-)
DIY пример использования Open API
Один из интересных примеров использования Open API приходится на область автоматизации дома. Например, некто трезвонит вам в дверь, камера реагирует и делает запись, а затем отправляет вам уведомление о событии.
Ivideon API использует OAuth 2.0 для авторизации, запросы поступают на сервер openapi-alpha.ivideon.com. Для работы по протоколу Oauth 2.0 нам понадобится access_token.
POST /auth/oauth/token HTTP/1.1
Host: openapi-alpha.ivideon.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic S2V5cmRwbHk6YjhmQzRkYTMxZTQwZWZkMTkxZDAwMzETM2FkZDcwZGU=
Cache-Control: no-cache
grant_type=password&username={user_name}&password={user_password}
{
"api_host": "openapi-alpha-eu01.ivideon.com",
"access_token": "100-U6c3d3e17-c845-4d13-bf57-6fd99ea7807a",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "archive attachment_tokens cameras_list cloud_recording get_events live manage_events manage_groups mute_camera_alerts servers_management shared_archive shared_live subscribe_events turn_off_camera user_info users_management voice-messaging",
"owner_type": "user",
"refresh_token": "e95bed0c5fb2413b8d6e55d8dcf16630",
"owner_id": 100001043052
}
Чтобы получить token вам необходимо указать имя пользователя (user_name в примере) и пароль (user_password в примере) и client_id и client_secret в заголовке HTTP Basic Authorization.
Для использования SDK вам необходимо передать ему access_token и ID камеры. Плеер получит видео с Ivideon Cloud. Получив доступ, вы сможете настроить все компоненты SDK: цвет, текст, язык и многое другое.
Создание события: запись видео и отправка уведомления.
POST /events?op=CREATE&access_token={access_token} HTTP/1.1
Host: openapi-alpha-eu01.ivideon.com
Content-Type: application/json
Cache-Control: no-cache
{
"type":"eventType",
"time": 1464263172,
"clip_settings":{
"duration":60
},
"notify": true,
"device_id":"100-6a18e46fc9ab4219261bee3bfb6cda35:0",
"device_type":"camera"
}
{
"result": {
"status": "new",
"delivered": true,
"preview": null,
"clip": null,
"type": "eventType",
"user": 100001043052,
"device_type": "camera",
"time": 1464263172,
"clip_duration": null,
"_id": "Xl3149lugdmF8sO4.1",
"data": null,
"id": "Xl3149lugdmF8sO4.1",
"device_id": "100-6a18e46fc9ab4219261bee3bfb6cda35:0"
},
"success": true
}
Перейдем к экспорту видео. В случае использования событий нужно еще раз повторно запросить статус события.
{
"result": {
"status": "new",
"delivered": true,
"preview": "https://msk88.ivideon.com/preview/motion/2016-07-21/gAS0dis1gsvLsf3REn0eTQWbRwkHAkN1.jpeg",
"clip": "https://msk98.ivideon.com/events/clips/2016-07-21/H1xyCDXSsRl4TqBkWQUfHDTHIQlfDMS1.mp4",
"type": "motion/started",
"user": "4005500726931",
"device_type": "camera",
"time": 1469096014,
"clip_duration": 4,
"data": null,
"id": "8cgclg2IFQYo4hFv.21",
"device_id": "100-b6251a97fa9d26c8952f786ecefa9551:0"
},
"success": true
}
В preview — фотка, в clip — видео. Как только они там появляются — можно забирать.
Остальные примеры запросов вы сможете увидеть в нашем гайде по интеграции, когда он будет опубликован.
Как связаться и получить доступ
У нас пока всего несколько тестовых проектов, т.е. мы принимаем заявки в индивидуальном порядке и с каждым лично находим способы взаимодействия. Пока мы в бета-тестировании вам нужно будет написать нам и мы вышлем вам интеграционный комплект: SDK, логин/пароль к API, документацию, и т.д. В дальнейшем все это будет доступно «из коробки».
Сейчас API полнофункционально, то есть все функции, которые необходимы для полноценной работы, там присутствуют, однако, скорее всего, там есть баги. В общем, стадия бета-тестировать во всей своей красе. Но если вас это не пугает, вы можете подать заявку (integration_support@ivideon.com) и потестировать работу на примере своего умного дома, стартапа или готового бизнеса.
