Как использовать API Ezviz: базовые сценарии и автоматизация

Как использовать API Ezviz: базовые сценарии и автоматизация

Кому и зачем это нужно

Если вы владелец дома, кафе или офисного здания и уже поставили камеры Ezviz, а хотите, чтобы всё работало без ручных перезапусков, то API – ваш помощник. Он позволяет брать список устройств, получать видеопоток, включать запись и даже интегрировать систему с внешними датчиками. Для инсталляторов API открывает путь к централизованному управлению сразу десятками камер через один сервер.

Что такое Ezviz API

Ezviz – это бренд видеонаблюдения, выпускаемый Hikvision. У него есть REST‑компоненты, которые открыты для подключения со стороны программного обеспечения. Через API можно выполнять операции, аналогичные тем, которые доступны в мобильном приложении: авторизация, чтение списка устройств, установка параметров, получение событий. Все запросы формируются через HTTPS и требуют токена, полученного при логине.

Требования к окружению

• Python 3.8+ (или любой язык с поддержкой HTTP‑запросов)
• Библиотека requests (для Python) или аналогичная
• Список логинов и паролей камер – в безопасном месте

Авторизация и получение токена

Для начала сделайте POST‑запрос к https://open.ezviz.net/api/v1.0/user/login. Тело запроса в JSON:

{
  "userName": "admin",
  "password": "123456",
  "companyId": ""
}

Ответ содержит поле token. Оно уникально, но живет в течение часа. Храните его в переменной и добавляйте в заголовок Authorization: Bearer <token> для всех последующих запросов.

Получить список устройств

GET‑запрос к https://open.ezviz.net/api/v1.0/products?productType=Camera вернёт массив объектов, каждый из которых описывает камеру: id, имя, IP‑адрес, текущий статус. Чтобы не запрашивать список каждый раз, стоит кэшировать его на несколько минут.

GET /products?productType=Camera HTTP/1.1
Host: open.ezviz.net
Authorization: Bearer <token>

Получить события (оповещение о движении)

Реализация проста: GET‑запрос к /events?productId=1234&take=10 возвращает последние 10 событий—тут можно заметить, когда камера засняла движение. События удобно сохранять в БД и использовать для обработки в real‑time.

Старт/стоп записи через API

PUT‑запрос к /recording/setState с телом:

{
  "productId": "1234",
  "state": "Start"
}

Ответ подтверждает, что запись запущена. Для остановки используйте state: "Stop".

Получить прямой поток (RTSP)

API не отдаёт сам поток, но через вызов /p2p/rtspUrl?productId=1234 можно получить прямую RTSP‑адрес. Вы можете передать его в любой медиаплеер или библиотеку.

Складывать API в домашнюю автоматизацию

Пример с RaspberryPi: каждая камера отправляет HTTP‑уведомление в прошедшие 5 секунд, если зафиксирована тревога. Скрипт на Python разбирает «payload», проверяет статус записи и, если всё в порядке, сохраняет клип в облачное хранилище. Ниже короткий пример:

import requests, json, time

TOKEN = "..."

def get_events(prod_id):
    r = requests.get(f"https://open.ezviz.net/api/v1.0/events?productId={prod_id}",
                     headers={"Authorization": f"Bearer {TOKEN}"})
    return r.json()

while True:
    ev = get_events("1234")
    for e in ev.get("eventList", []):
        if e["eventType"] == "motion":
            print("Движение:", e["time"])
    time.sleep(5)

Безопасность и правила

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

В большинстве стран в праве действует строгий контроль за хранением видеоданных. Убедитесь, что ваша система соответствует требованиям GDPR, если вы работаете в ЕС, или требованиям ФЗ-152 в РФ.

Стоимость услуг и оборудования

Элементы системы можно подобрать в каталоге поставщика y‑ss.ru. Там есть цены на IP‑камеры Ezviz и комплектующие. При установке на объекте стоит оценить стоимость камер, серверного оборудования и облачного хранилища, а также время работ. Пример расчёта:

Краткая шпаргалка по API Ezviz

• Авторизация → /api/v1.0/user/login
• Список камер → /api/v1.0/products?productType=Camera
• События → /api/v1.0/events?productId=XXX
• Запись → /api/v1.0/recording/setState
• RTSP‑URL → /api/v1.0/p2p/rtspUrl?productId=XXX

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