Skip to content

Миграция интеграции на API v3

Устаревший API Watcher (/vsaas/api/v1, /vsaas/api/v2) и глобальный ключ домена X-Vsaas-Api-Key удалены. Интеграции, использующие эти запросы, перестанут работать после обновления Watcher. Эта статья описывает, как перевести интеграцию на API v3: какой из двух API использовать, как авторизоваться и чем отличается поведение v3 от v2.

Полные справочники API v3:

Если ваша интеграция — это биллинг оператора, воспользуйтесь отдельной статьей Интеграция в существующую систему биллинга: в ней те же принципы разобраны на типовых сценариях биллинга.

Client API и Admin API

В v3 два набора запросов с разными базовыми путями:

  • Client API — /watcher/client-api/v3/.... Основной API для интеграций: организации, пользователи, папки, камеры, права, мозаики, эпизоды аналитики. Доступен любому пользователю, запросы ограничены его правами.
  • Admin API — /watcher/admin-api/v3/.... Только для пользователей с уровнем доступа администратора Watcher. Используется для операций уровня инсталляции: создание пресетов, управление стримерами и доменами.

Большинству интеграций достаточно Client API. Admin API понадобится, если интеграция создает пресеты или работает с несколькими доменами.

Авторизация

Глобального ключа домена в v3 нет: каждый запрос выполняется от имени пользователя и ограничен его правами. Создайте для интеграции отдельную сервисную учетную запись с необходимыми правами и не используйте личные учетные записи сотрудников.

Способы авторизации (подробнее — в статье Авторизация API-запроса):

  • JWT-токен: POST /watcher/client-api/v3/login с Basic-авторизацией возвращает access_token (действует один час) и refresh_token. Новый access_token выдается повторным запросом /login с заголовком Authorization: Bearer <refresh_token>.
  • Персональный API-ключ: выпускается запросом POST /watcher/client-api/v3/users/{user_id}/apikey, не имеет срока действия и не требует обновления — рекомендуемый способ для серверных интеграций.

Токен или ключ передается в заголовке Authorization: Bearer <значение> каждого запроса.

Note

Не выполняйте /login перед каждым запросом: при частых обращениях сервер вернет ошибку 429 Too Many Requests. Используйте API-ключ либо повторно используйте access_token до истечения его срока действия.

Для Admin API запрос POST /watcher/admin-api/v3/login доступен только пользователям с уровнем доступа администратора Watcher; запрос от администратора домена будет отклонен.

Что изменилось в поведении

Миграция не сводится к замене путей запросов. Проверьте в коде интеграции следующие изменения:

  • Ресурс cameras переименован в streams. Отдельного запроса создания камеры нет: камера создается и обновляется одним запросом PUT /watcher/client-api/v3/streams/{name}. Имя камере присваивает Watcher: при создании значение {name} из URL не используется, имя генерируется на основе title и возвращается в поле name ответа — сохраните его, все дальнейшие операции выполняются по нему.
  • Массовый импорт не возвращает имена. Ответ POST /streams/import содержит только счетчики созданных и обновленных камер. Используйте импорт для массового обновления; камеры, которыми интеграция будет управлять, создавайте по одной.
  • Поле name пользователя — это логин. Почта для уведомлений передается в поле email.
  • Блокировка — полем disabled. Поля enabled в v3 нет. При disabled: true и при смене пароля все сессии пользователя завершаются.
  • Смена пароля — через обновление пользователя. PUT /users/{user_id} с полем password; отдельного запроса нет.
  • Права не наследуются между уровнями. Права администратора не дают автоматически прав в организации: например, POST /users с organization_id требует владения организацией или явного права управления пользователями в ней, иначе вернется 403. Административные операции с камерами и пользователями выполняйте через Admin API. Создатель организации становится ее владельцем; владельца можно назначить явно полем owner.id при создании.
  • Доступ к видео выдается на папки. Права просмотра (can_view, can_view_dvr, can_use_ptz) назначаются запросом PUT /organizations/{id}/folders/{folder_id}/users/{user_id} и действуют рекурсивно на вложенные папки. Членство в организации само по себе доступа к видео не дает.
  • Право редактирования камер включает просмотр видео. Пользователь с can_edit_streams автоматически получает can_view_streams; в ответах API этот флаг возвращается со значением true независимо от отправленного значения.
  • Курсорная пагинация. Списки возвращают поля estimated_count, next, prev; постраничного offset нет. Передавайте значение next в параметре cursor следующего запроса.
  • Статус камеры — в полях stats.alive (поток идет; false при задержке больше 12 секунд) и stats.status (running / waiting / error). Полей online/offline нет.
  • Пользователь readonly получает 403 на любой изменяющий запрос (POST/PUT/DELETE/PATCH) независимо от остальных прав.

Соответствие запросов v2 и v3

Основные запросы (полный перечень — в справочниках API):

Запрос в v2 Запрос в v3
X-Vsaas-Api-Key: <ключ домена> Authorization: Bearer <токен или API-ключ>
POST /vsaas/api/v2/auth/login POST /watcher/client-api/v3/login
GET /vsaas/api/v2/profile GET /watcher/client-api/v3/profile
POST /vsaas/api/v2/users/{id}/apikey POST /watcher/client-api/v3/users/{user_id}/apikey
GET /vsaas/api/v2/cameras GET /watcher/client-api/v3/streams
POST /vsaas/api/v2/cameras PUT /watcher/client-api/v3/streams/{name} — имя присваивает Watcher, см. выше
PUT /vsaas/api/v2/cameras/{name} PUT /watcher/client-api/v3/streams/{name}
DELETE /vsaas/api/v2/cameras/{name} DELETE /watcher/client-api/v3/streams/{name}
POST /vsaas/api/v2/cameras/import POST /watcher/client-api/v3/streams/import
GET/POST /vsaas/api/v2/users, PUT/DELETE /users/{id} те же операции под /watcher/client-api/v3/users
GET/POST /vsaas/api/v2/organizations, PUT/DELETE /organizations/{id} те же операции под /watcher/client-api/v3/organizations
.../organizations/{id}/users/{user_id} тот же путь под /watcher/client-api/v3/... (PUT добавляет пользователя в организацию, если он еще не состоит в ней)
.../organizations/{id}/folders/... те же пути под /watcher/client-api/v3/...
GET/POST /vsaas/api/v2/presets GET /watcher/client-api/v3/presets; создание — POST /watcher/admin-api/v3/presets
POST /vsaas/api/v2/agent-activation-tokens POST /watcher/client-api/v3/agent_activation_token
GET /vsaas/api/v2/mosaics GET /watcher/client-api/v3/mosaics
GET /vsaas/api/v2/events GET /watcher/client-api/v3/episodes — модель событий изменена, см. справочник API

Порядок миграции

  1. Создайте сервисную учетную запись и выпустите для нее API-ключ.
  2. Замените авторизацию: удалите X-Vsaas-Api-Key, передавайте Authorization: Bearer <ключ>.
  3. Замените пути запросов по таблице выше и адаптируйте код к изменениям поведения: генерация имен камер, курсорная пагинация, disabled вместо enabled.
  4. Проверьте права сервисной учетной записи на каждой операции: ошибка 403 в v3 чаще всего означает отсутствие прав в конкретной организации, а не неверный токен.
  5. Проверьте работу интеграции на тестовой инсталляции до обновления рабочей.