API камер Hikvision и Dahua: руководство для разработчика с примерами

Ключевые запросы к API Hikvision и Dahua: быстрый старт

Для доступа к API камер Hikvision и Dahua используется HTTP с Digest-аутентификацией. Проще всего начать с утилиты curl. Основные задачи — получить снимок (снапшот) и информацию об устройстве. Вот базовые команды: для Hikvision используйте эндпоинты ISAPI, например, /ISAPI/Streaming/channels/101/picture для снимка. Для Dahua — CGI-запросы, например, /cgi-bin/snapshot.cgi. Замените USER:PASSWORD и CAMERA_IP на ваши данные.

Hikvision: запросы к ISAPI

Для камер Hikvision основной программный интерфейс — это ISAPI. Он позволяет получать данные и управлять функциями через HTTP-запросы. Ниже приведены наиболее частые примеры запросов API Hikvision для получения снимка и системной информации.

Получение снапшота с первого канала

Эта команда сохранит изображение с первого основного потока (channel 101) в файл hikvision_snapshot.jpg.

curl --digest -u USER:PASSWORD http://CAMERA_IP/ISAPI/Streaming/channels/101/picture --output hikvision_snapshot.jpg

Получение информации об устройстве

Запрос вернёт XML-файл с данными о модели камеры, версии прошивки и серийном номере. Результат будет сохранён в hikvision_device_info.xml.

curl --digest -u USER:PASSWORD http://CAMERA_IP/ISAPI/System/deviceInfo --output hikvision_device_info.xml

Dahua: запросы через CGI

Камеры Dahua часто используют CGI-скрипты для реализации своего HTTP API. Эти эндпоинты также позволяют выполнять базовые операции, включая получение снимков и сведений об устройстве.

Получение снапшота

Эта команда скачает снимок с первого канала камеры Dahua в файл dahua_snapshot.jpg. Убедитесь, что указанный канал активен.

curl --digest -u USER:PASSWORD http://CAMERA_IP/cgi-bin/snapshot.cgi?channel=1 --output dahua_snapshot.jpg

Получение системной информации

Запрос вернёт XML или JSON-ответ с основными данными о камере, такими как модель и версия ПО. Результат будет сохранён в dahua_system_info.xml.

curl --digest -u USER:PASSWORD http://CAMERA_IP/cgi-bin/system.cgi?action=getInfo --output dahua_system_info.xml

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

Что такое API в IP-камерах и для чего его используют?

В первом разделе мы показали, как выполнить запросы к API камер Hikvision и Dahua. Теперь разберемся, что такое API, зачем он нужен и какие задачи можно решить с его помощью, выходя за рамки стандартных возможностей приложения или веб-интерфейса.

API (Application Programming Interface) – это набор правил и инструкций, который позволяет различным программам "общаться" друг с другом. В контексте IP-камер это означает, что вы можете отправлять камере команды и получать от нее информацию не через ее стандартное меню или приложение, а с помощью программного кода или скриптов. Это открывает возможности для глубокой интеграции и автоматизации.

Практическое использование API: интеграция и автоматизация

Использование API IP-камеры позволяет превратить ее из простого устройства записи в полноценный элемент сложной экосистемы безопасности или "Умного дома". Вот несколько примеров:

• Интеграция с системами "Умный дом". Через API можно получать события (например, детекцию движения, пересечение линии) и управлять камерой из единого центра "Умного дома" – будь то Home Assistant, MajorDoMo или другая кастомная платформа. Вы сможете, например, настроить автоматическое включение света на участке при обнаружении движения на Hikvision DS-2CD2787G2HT-LIZS, отправку снимков в мессенджер при срабатывании тревоги или запись видео только при активации определенного сценария.

• Создание кастомных панелей мониторинга (дашбордов). Если стандартный интерфейс не удовлетворяет вашим требованиям, API позволяет извлекать нужные данные (статус камеры, температуру, состояние датчиков) и отображать их на собственной панели мониторинга. Это особенно полезно для комплексных систем безопасности, где требуется максимально адаптированный вывод информации.

• Автоматизация на основе событий. Камеры Hikvision и Dahua обладают мощной видеоаналитикой. Через API вы можете получать детальные данные о событиях: кто вошел, когда, в какой зоне. Это дает базу для сложных сценариев: при появлении человека в запретной зоне система может не только отправить уведомление, но и автоматически заблокировать дверь через СКУД, активировать сирену или включить запись на всех камерах сразу.

• Пакетная настройка и управление. Для систем, включающих десятки и сотни камер, ручная настройка становится трудоемкой. API позволяет создавать скрипты, которые массово изменяют параметры (например, сетевые настройки, расписание записи, параметры видеоаналитики) на всех устройствах одновременно. Это значительно сокращает время на развертывание и обслуживание.

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

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

Подготовка к работе: аутентификация и поиск документации

После того как вы убедились в работоспособности базовых запросов к API своих IP-камер Hikvision или Dahua, следующий критически важный шаг — понять механизм аутентификации и найти актуальную документацию. Без этого двигаться дальше к сложным задачам невозможно.

Как работает Digest Authentication

Если вы пытались передавать логин и пароль прямо в URL или использовать стандартную Basic-аутентификацию, скорее всего, получили отказ. Большинство современных IP-камер Hikvision (ISAPI) и Dahua используют более безопасный метод — Digest Authentication. Это ключевой механизм для аутентификации API Hikvision и Dahua.

В отличие от Basic Authentication, где учетные данные передаются в открытом виде (пусть и закодированными в Base64, но легко дешифруемыми), Digest Authentication защищает ваш пароль. Пароль не отправляется напрямую на сервер. Вместо этого происходит двухэтапный процесс:

1. Ваш клиент (например, скрипт на Python или утилита curl) отправляет первый запрос к камере без заголовка Authorization.
2. Камера отвечает статусом 401 Unauthorized (Не авторизован) и в заголовке WWW-Authenticate возвращает специальный "разовый" код — nonce (от "number used once").
3. Клиент, используя логин, пароль и полученный nonce, вычисляет криптографический хэш. Этот хэш и отправляется камере во втором запросе в заголовке Authorization.
4. Камера, зная логин, пароль и свой nonce, выполняет те же вычисления и сравнивает полученный хэш со своим. Если они совпадают, доступ предоставляется.

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

Поиск официальной документации

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

Документация Hikvision ISAPI

Для камер Hikvision основной источник информации — это официальный портал разработчиков. Здесь вы найдете подробные руководства, описания эндпоинтов ISAPI и примеры кода. Настоятельно рекомендуем начинать поиск именно с него, чтобы получить самую свежую и корректную информацию:

• Hikvision Developer Center (раздел "ISAPI" или "Integration Guides")

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

Документация Dahua HTTP API

С Dahua ситуация несколько иная. Производитель не имеет единого централизованного портала для API, как Hikvision. Документация по HTTP API для камер Dahua чаще всего распространяется в виде PDF-файлов и может значительно различаться для разных линеек продуктов и версий прошивок. Поэтому поиск потребует больше усилий.

Эффективный подход к поиску Dahua HTTP API PDF:

1. Определите точную модель и версию прошивки вашей камеры. Это ключевая информация, так как API может меняться от версии к версии.
2. Используйте целенаправленный поиск в Google: Введите запросы типа "Dahua HTTP API PDF [модель вашей камеры]", "Dahua CGI API [версия прошивки]" или "Dahua Private Protocol SDK [модель/серия]".
3. Изучите неофициальные ресурсы и форумы: Часто разработчики делятся найденными документами или примерами на специализированных форумах, но всегда проверяйте информацию на актуальность и соответствие вашему устройству.

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

Продвинутые сценарии: PTZ, события и видеопотоки

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

Управление PTZ-камерами (Pan-Tilt-Zoom)

PTZ-камеры позволяют программно изменять направление обзора, увеличивать или уменьшать изображение, а также фокусироваться. Это ключевая функция для систем, где требуется оперативное реагирование на события или слежение за объектами. Управление может осуществляться через команды для непрерывного движения (continuous move) или вызов предустановленных позиций (presets).

Примеры управления PTZ для Hikvision (ISAPI)

Для камер Hikvision команды PTZ отправляются с использованием протокола ISAPI. Для непрерывного движения (например, поворота влево) используется следующий запрос:

curl -X PUT --digest -u admin:PASSWORD "http://CAMERA_IP/ISAPI/PTZCtrl/channels/1/continuous" -d '<PTZData version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema"><pan>-50</pan><tilt>0</tilt><zoom>0</zoom></PTZData>' -H "Content-Type: application/xml"

• pan, tilt, zoom: значения от -100 до 100, где 0 — остановка.
• Канал (channels/1) обычно соответствует номеру видеоканала.

Вызов предустановленной позиции (preset) позволяет камере мгновенно перейти в заранее заданное положение:

curl -X PUT --digest -u admin:PASSWORD "http://CAMERA_IP/ISAPI/PTZCtrl/channels/1/presets/1/goto"

• presets/1: номер предустановленной позиции, настроенной на камере.

Примеры управления PTZ для Dahua (CGI)

Dahua часто использует CGI-скрипты для управления PTZ. Например, для поворота влево с определенной скоростью:

curl --digest -u admin:PASSWORD "http://CAMERA_IP/cgi-bin/ptz.cgi?action=start&channel=0&code=Left&arg1=1"

• action=start: начать движение. Для остановки используйте action=stop.
• channel=0: обычно канал 0 для PTZ-камер.
• code=Left: направление движения (Right, Up, Down, LeftUp, LeftDown, RightUp, RightDown, ZoomIn, ZoomOut, FocusNear, FocusFar и т.д.).
• arg1=1: скорость движения (значение от 1 до 9, где 9 максимальная).

Вызов предустановки у Dahua:

curl --digest -u admin:PASSWORD "http://CAMERA_IP/cgi-bin/ptz.cgi?action=start&channel=0&code=PresetCall&arg1=1"

• arg1=1: номер предустановленной позиции.

Получение RTSP-адреса видеопотока

Хотя стандартный RTSP-адрес часто можно найти в веб-интерфейсе камеры, иногда для динамического формирования или подтверждения ссылки удобно получить его через API. Это гарантирует актуальность потока, особенно если настройки камеры менялись.

Hikvision (ISAPI)

Для получения RTSP-ссылки на основной видеопоток с камеры Hikvision можно использовать следующий эндпоинт:

curl --digest -u admin:PASSWORD "http://CAMERA_IP/ISAPI/Streaming/channels/101/rtspPreviewUrl"

В ответе вы получите XML, содержащий URL для RTSP-потока. Например:

<rtspPreviewUrl version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
    <url>rtsp://admin:PASSWORD@CAMERA_IP:554/Streaming/channels/101/preview</url>
</rtspPreviewUrl>

Канал 101 обычно означает первый основной поток (main stream) первой камеры.

Dahua (CGI)

Dahua не всегда предоставляет прямой API-эндпоинт, который возвращает готовую RTSP-ссылку. Чаще всего приходится конструировать ее на основе полученных через API настроек потоков. Базовая структура RTSP-ссылки Dahua выглядит так: rtsp://<логин>:<пароль>@<IP-адрес>:554/cam/realmonitor?channel=<номер канала>&subtype=<тип потока>. Номер канала и тип потока (0 для основного, 1 для дополнительного) можно получить из API-запросов к конфигурации потоков (например, /cgi-bin/configManager.cgi?action=getConfig&name=Encode).

Работа с событиями: детекция движения, пересечение линии и другие

Получение событий с камеры — основа для создания интеллектуальных систем безопасности. Это позволяет автоматизировать реакции: включать свет, отправлять уведомления или запускать запись только при наличии активности. Здесь мы рассмотрим, как получать API события, такие как детекция движения или пересечение линии.

Hikvision: Alert Stream

Камеры Hikvision предлагают мощный механизм подписки на события — Alert Stream. Это HTTP-соединение, которое камера поддерживает открытым и отправляет в него XML-сообщения по мере возникновения событий. Для подключения к Alert Stream используйте:

curl -X GET --digest -u admin:PASSWORD "http://CAMERA_IP/ISAPI/Event/notification/alertStream" -H "Content-Type: text/xml"

Этот запрос откроет постоянный поток XML-данных. Пример данных, которые приходят при детекции движения:

<EventNotificationAlert version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
    <ipAddress>192.168.1.64</ipAddress>
    <portNo>80</portNo>
    <protocol>HTTP</protocol>
    <macAddress>D8:AC:30:D5:A2:3B</macAddress>
    <channelID>1</channelID>
    <dateTime>2023-10-27T10:30:00+03:00</dateTime>
    <activePostCount>1</activePostCount<
    <eventType>VMD</eventType> <!-- Видео детекция движения -->
    <eventState>active</eventState> <!-- Начало события -->
    <eventDescription>VMDAlarm</eventDescription>
</EventNotificationAlert>

Поле eventType указывает тип события (например, VMD для видео детекции движения, LineDetection для пересечения линии). Поле eventState может быть active (начало события) или inactive (окончание события).

Dahua: Получение событий

Для Dahua существует несколько подходов. Самый распространенный для интеграции — это настройка камеры на HTTP-Push уведомления. В веб-интерфейсе камеры вы указываете URL своего сервера, куда камера будет отправлять POST-запросы с JSON/XML-данными событий (например, детекция движения или вход/выход из зоны). Если требуется программный опрос, можно периодически запрашивать журнал событий:

curl --digest -u admin:PASSWORD "http://CAMERA_IP/cgi-bin/eventManager.cgi?action=getEventLogs&count=10&startTime=2023-10-27T00:00:00"

Этот запрос вернет последние 10 событий, произошедших после указанного времени. Однако для реального времени такой подход менее эффективен, чем Push-уведомления или Alert Stream Hikvision.

Этот раздел показал, как реализовать более сложные сценарии взаимодействия с камерой. При работе с API, особенно с новыми прошивками или сложными запросами, неизбежно возникают ошибки. Давайте разберемся, как их диагностировать.

Частые проблемы и отладка запросов

Даже при наличии точной документации, работа с API IP-камер часто сопряжена с типовыми сложностями. Эти проблемы чаще всего связаны с аутентификацией, некорректными запросами или отсутствием прав. Понимание основных кодов HTTP-ответов и методов отладки поможет вам быстро найти и устранить причину сбоя, экономя часы на поиске решения.

Ошибки HTTP-статуса: что они значат?

Сервер камеры отвечает на каждый ваш запрос кодом состояния HTTP. Это первый и самый важный индикатор того, что пошло не так. Рассмотрим наиболее распространенные коды ошибок, с которыми вы столкнетесь при работе с API Hikvision и Dahua.

Инструменты для отладки API-запросов

Диагностика с помощью браузера (F12)

Один из самых эффективных способов понять, как работает API вашей камеры, — это "подсмотреть" запросы, которые отправляет ее собственный веб-интерфейс. Большинство современных браузеров имеют встроенные инструменты разработчика, доступные по нажатию клавиши F12.

1. Откройте веб-интерфейс вашей камеры в браузере.
2. Нажмите F12, чтобы открыть инструменты разработчика. Перейдите на вкладку «Сеть» (Network).
3. Выполните на веб-интерфейсе камеры то действие, API которого вы хотите изучить (например, сделайте снимок, поверните PTZ-камеру, измените настройку).
4. В списке сетевых запросов вы увидите те, которые были отправлены камерой. Найдите запрос, URL которого содержит ISAPI (для Hikvision) или cgi-bin (для Dahua).
5. Кликните на этот запрос, чтобы просмотреть его детали: метод HTTP (GET/POST), полный URL, заголовки запроса (особенно Authorization для понимания Digest) и тело запроса/ответа.

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

Postman или Insomnia для удобной работы

Для более комфортной итеративной отладки, особенно когда вы активно разрабатываете интеграцию, рекомендуем использовать специализированные клиенты для API, такие как Postman или Insomnia. Эти инструменты значительно упрощают процесс благодаря функциям:

• Удобный интерфейс для конструирования HTTP-запросов (выбор метода, добавление заголовков, параметров, тела запроса).
• Автоматическая обработка аутентификации, включая Digest, что избавляет вас от необходимости вручную рассчитывать хеши.
• Сохранение истории запросов и организация их в коллекции.
• Просмотр ответов в удобном формате (JSON, XML, HTML).

Используя Postman или Insomnia, вы можете быстро менять параметры запроса, тестировать различные эндпоинты и эффективно диагностировать проблемы, связанные как с вашим кодом, так и с поведением API камеры. Это особенно полезно, когда нужно воспроизвести проблему и проверить несколько гипотез.

Когда обратиться к специалистам?

Если после всех вышеперечисленных шагов проблема остается нерешенной, камера продолжает выдавать ошибки или вы не можете найти необходимую документацию для вашей конкретной версии прошивки, возможно, пришло время обратиться за помощью. В таких случаях мы, «Камера39», готовы провести глубокую диагностику. Мы поможем вам разобраться в специфике API вашего оборудования, отладить запросы и настроить необходимую интеграцию.