Open API Ivideon: первые шаги

41082e00522842188bb87df454820af4.png
Как же быстро время пролетело: наш предыдущий пост вышел на Хабре 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 секунд. Развитие этой функции дает возможность записывать клипы по каким-то внешним событиям, не связанным непосредственно с камерами — например, открылась дверь, сработал датчик движения и так далее. Мы также прорабатываем функцию, которая либо заменит эти клипы, либо станет дополнением к ним — это запись от начала до конца.

Типы использования

3ddbde24708446e6b880d7d1fca0897a.jpg

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

Первая схема подходит для обычных пользователей, которые просто хотят что-то автоматизировать, а также для крупных компаний, использующих возможности Open API для себя. Так как на наших камерах есть детектор движения и детектор звука, с помощью API вы можете интегрировать систему в свою умный дом: получать SMS при каком-то событии, запрашивать live-видео и т.д.

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

Примеры использования

e56ba4bc32eb43e6b11b547751596f9f.png

Один наш крупный партнер установил себе сотни камер и стал искать способ, как упростить передачу прав доступа на камеры. Стандартно Ivideon через веб-интерфейс позволяет передавать права на просмотр онлайна, передавать права на просмотр архива и передавать права на управление камерами (двигать камеры, включать и выключать). Однако все эти права нужно было передавать вручную: выбрать камеру, выбрать e-mail пользователя, указать, какие права ему передать. Когда у вас 10 камер, с этим справится один человек. Когда у вас сотни камер, разбросанных по всей России, и десятки пользователей — начинается сильная боль.

Как вы понимаете, очень неудобно учитывать все передачи прав. С помощью технологии, которая получила название «Группировка камер», появляется возможность указать иерархию: например, крупный регион, город в регионе, отдельные районы в городе и так далее. Камеры можно распределить по всему дереву, и давать человеку доступ (или забирать доступ) сразу к определенной группе камер.

eb3f206365a94bd1b9f5be2fa48125a2.png

Следующий пример использования Open API будет интересен и обычным пользователям, поскольку затрагивает функциональность умного дома. Среди наших клиентов есть несколько компаний, занимающихся технологиями умного дома. Например, в США работает команда, разрабатывающая систему, которая позволяет открывать гараж или какое-то отдельное помещение, передавая одноразово сгенерированный код доступ третьим лицам.

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

Этой системе не хватало самого главного — видеонаблюдения. А что если курьер украдет из гаража велосипед? В идеале нужно было видеть, что курьер пришел, занес посылку и ушел, ничего с собой не забрав. Для этого можно опубликовать событие в приложении непосредственно в нужный момент, и при этом записать клип. Можно также все время вести live-трансляцию прямо в мобильное приложение. Такую систему легко реализовать с помощью подходящего микроконтроллера и любой камеры с Ivideon на борту.

Когда происходит какое-то событие, за которым должна следовать запись видео, на центральном контроллере умного дома нужно установить идентификацию события — оно отправится нам, после чего нашего облако отправит на камеру команду «запиши». Затем вы отправляете к нам запрос и получаете ссылку, по которой можно скачать видеоклип, куда-то отправить или встроить.

4d8010a010e24b12b39d136b47f92a8b.png

Допустим, вы получаете образование удаленно, и все лекции обрабатываете на дому, но на экзамены все равно вынуждены приходить. В тоже время, сдавать экзамены можно и с помощью системы видеонаблюдения. В присутствии проктора происходит компьютерное тестирование знаний учащегося. Сначала происходит идентификация, например, демонстрация паспорта. Затем происходит выдача заданий, интервьюирование с конкретным человеком. Преподавателю в процессе транслируется видео с веб-камеры и с экрана. Запись хранится какое-то время в облаке и в случае возникновения спорных вопросов предоставляется сторонам конфликта.

80762a26827141d0a7e66f3ff6883047.png

Мы и раньше интегрировались с корпоративными и бизнес-приложениями (СКУД, ОПС, кассовыми аппаратами), но развитие 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: цвет, текст, язык и многое другое.

f27e09e7b5a34723bfebd17d4452eeb7.png

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

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) и потестировать работу на примере своего умного дома, стартапа или готового бизнеса.

Комментарии (0)

© Habrahabr.ru