Интеграция с внешней учётной системой¶

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

Выберите сценарий:

• Личные камеры пользователя — создайте пользователя и его организацию, назначьте доступный пресет и подключите камеры.
• Доступ к общим камерам — организация и камеры уже существуют; выполните отдельный пример ограниченного доступа к папке.

В этой схеме:

• Администратор — отвечает за установку Watcher и подключение внешней системы.
• Пользователь — сотрудник, которому предоставлен доступ к камерам объекта.
• Учётная система — связывает объекты предприятия и пользователей с организациями, камерами и пресетами Watcher.

Используйте API v3. Сохраните во внешней учётной системе идентификаторы пользователя, организации и камер из ответов Watcher. Полные контракты — в справочниках Client API и Admin API.

Сервисная учетная запись и авторизация запросов¶

Для описанной административной схемы создайте отдельную сервисную учетную запись с access_level: "admin". Получите JWT через /login или выпустите персональный API-ключ по инструкции авторизации. Дальнейшие примеры подразумевают заголовки:

Authorization: Bearer <token>
Content-Type: application/json

Сервисная учетная запись управляет пользователями и камерами через Admin API. Организации создаются через Client API с доменным правом управления организациями. В приведённом примере владелец организации — создаваемый пользователь; для Client API права владельца и системного администратора различаются.

В доменах без даты создания либо созданных раньше 16 января 2026 года, 08:30:29.622 UTC, вне основного домена действует дополнительная проверка логина при создании и административном изменении организаций: допускается billing либо имя с суффиксом _master. Учтите это при подготовке учетной записи.

Для операций с папками или ключами активации нужны права в соответствующей организации. Назначьте сервисной учетной записи нужные организационные права по инструкции API пользователей либо выполняйте пользовательский сценарий от имени пользователя. Административная роль сама по себе эти проверки не заменяет.

Создание пресетов¶

Пресет задает выбранные параметры архива и аналитики. Создайте его через Admin API:

POST /watcher/admin-api/v3/presets

{
  "title": "Архив 7 дней",
  "is_adjustable": false,
  "dvr": {"expiration": 604800}
}

Сохраните id из ответа. is_adjustable: false запрещает применять к камере пользовательские изменения параметров DVR и аналитики поверх этого пресета. Для изменения параметров камер обновите сам пресет либо назначьте другой.

Подключение пользователя¶

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

Шаг 1. Создать пользователя¶

POST /watcher/admin-api/v3/users

{
  "name": "resident-example",
  "fullname": "Ирина Смирнова",
  "password": "ExamplePassword",
  "email": "resident@example.com",
  "external_id": "account-123"
}

Сохраните id. Логин находится в name, адрес для уведомлений — в email. external_id связывает учетную запись с записью внешней учётной системы.

Без organization_id Admin API добавляет пользователя в организацию целевого домена по умолчанию. Если указать организацию явно, потребуется право управления ее пользователями, в том числе у администратора Watcher.

Шаг 2. Создать организацию с пользователем-владельцем¶

POST /watcher/client-api/v3/organizations

{
  "title": "Дом на Садовой, квартира 12",
  "owner": {"id":15},
  "limits": {"streams":4,"users":10}
}

Замените 15 на идентификатор пользователя. Сохраните id организации. Вместе с организацией создается папка Cameras. Владелец получает полномочия управления организацией и доступ к ее камерам; отдельные права на папки ему не требуются.

При необходимости исключите пользователя из организации по умолчанию запросом DELETE /watcher/client-api/v3/organizations/{default_organization_id}/users/{user_id}. Убедитесь, что он сохраняет членство в своей организации.

Привяжите созданный пресет к созданной организации. В запросе 7 замените идентификатором организации, 42 — идентификатором пресета:

PUT /watcher/client-api/v3/organizations/7/presets

{"preset_id":42}

Если организации доступно несколько пресетов, пользователь с правом управления камерами может выбирать между ними. Ограничьте список теми пресетами, которые пользователь вправе выбирать. Создание и изменение пресетов выполняет администратор Watcher.

Камеры с агентом¶

Для камеры с агентом получите ключ активации через Client API от имени пользователя с правом управления камерами организации:

POST /watcher/client-api/v3/agent_activation_token

{"organization_id":7,"preset_id":42,"title":"Вход"}

Из ответа возьмите token и используйте его в процедуре активации агента. Пресет должен быть доступен организации. Если preset_id не указан, Watcher выбирает доступный пресет по умолчанию либо первый доступный; отсутствие доступных пресетов приводит к ошибке.

После активации запрос GET /watcher/client-api/v3/agent_activation_token/{token} от имени создателя ключа возвращает stream_name. Сохраните его как имя камеры. Список камер пользователя также можно прочитать через GET /watcher/admin-api/v3/streams?organization_id=7.

Сценарий активации может выполнять пользователь в интерфейсе Watcher. Если ключи готовит администратор, сервисной учетной записи нужны организационные права. Не передавайте учетные данные администратора монтажнику или пользователю.

Камера без агента¶

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

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

Добавление камеры¶

Получите папки созданной организации запросом GET /watcher/client-api/v3/organizations/7/folders?limit=100 и сохраните id нужной папки. Для личной камеры можно выбрать корневую Cameras. Далее 7 замените идентификатором созданной организации, 42 — пресета, 12 — выбранной папки. Если список возвращает next, продолжите его через cursor. Для этого запроса сервисной учетной записи нужны организационные права, описанные выше.

PUT /watcher/admin-api/v3/streams/new-camera

{
  "title": "Вход",
  "organization_id":7,
  "preset_id":42,
  "folder_id":12,
  "inputs":[{"url":"rtsp://camera.example.com/main"}]
}

Папка должна принадлежать организации. Перед созданием проверьте доступность пресета организации. При создании обычной камеры Watcher генерирует имя на основе названия; new-camera в URL не станет ее именем. Сохраните name из ответа и используйте именно его в последующих запросах.

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

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

Добавление пользователя¶

Основная учетная запись создается в первом шаге. Дополнительных пользователей можно создавать через POST /watcher/client-api/v3/users с organization_id, если вызывающая учетная запись управляет пользователями этой организации. Само членство доступа к видео не дает — выдайте права на папки или организационный просмотр явно.

Для проверки пароля во внешней системе предусмотрен HTTP-бэкенд. Он не заменяет настройку организаций и прав.

Смена пресета¶

Назначьте другой доступный пресет. В следующих двух примерах замените entrance-example и parking-example именами существующих камер из ответов Watcher, а 43 — идентификатором доступного им пресета:

PUT /watcher/admin-api/v3/streams/entrance-example

{"preset_id":43}

Для группы камер:

POST /watcher/admin-api/v3/streams/multiedit

{"streams":[{"name":"entrance-example","preset_id":43},{"name":"parking-example","preset_id":43}]}

multiedit также имеет настройки DVR и другие поля своей схемы; используйте текущий справочник Admin API. Если одна из перечисленных камер не найдена, запрос отклоняется с 404. При успешном применении ответ — 204. После изменения перечитайте настройки и проверьте фактическую запись архива.

Приостановка доступа¶

Отключите учетную запись пользователя:

PUT /watcher/admin-api/v3/users/15

{"disabled":true}

Watcher удаляет ее активные сессии. Для возобновления передайте disabled: false; пользователь выполняет новый вход.

Если надо остановить только личную камеру, используйте PUT /watcher/admin-api/v3/streams/{name} с {"disabled":true}. Это влияет на всех потребителей этой камеры. Для общей камеры отзывайте права конкретного пользователя, сохраняя камеру доступной остальным.

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

Отзыв доступа и удаление¶

Следующий независимый пример исключает пользователя 15 из существующей организации общих камер 8. Для пользователя с личной организацией используйте её идентификатор и предварительно проверьте последствия удаления владельца по API пользователей.

DELETE /watcher/client-api/v3/organizations/8/users/15

Удаляются членство, организационные права и папочные права в этой организации. Для полного удаления учетной записи администратор использует DELETE /watcher/admin-api/v3/users/15.

Пароль меняется через обновление пользователя:

PUT /watcher/admin-api/v3/users/15

{"password":"NewExamplePassword"}

При смене пароля пользователя другой учетной записью его сессии удаляются. Удаление организации — отдельная каскадная операция; сначала проверьте ее состав и последствия по API организаций.

Статус камер¶

Читайте GET /watcher/admin-api/v3/streams?organization_id=7 либо GET /watcher/admin-api/v3/streams/{name}. Обходите все страницы через next/cursor.

Поле stats содержит текущее состояние камеры, включая status и alive, когда эти сведения доступны. disabled в настройках означает административное отключение камеры; его нельзя использовать как признак сетевой доступности. Отсутствие актуальной статистики также не равно административной блокировке.

После подключения проверяйте отдельно сохранение настроек и появление видео. Успешный ответ на запрос настройки не подтверждает, что камера доступна по указанному адресу.

Общие камеры: ограниченный пользователь¶

Этот пример дает новому пользователю просмотр выбранной папки с общими камерами и ее подпапок. Организация и камеры уже существуют. Владельцем организации остается обслуживающая учетная запись; пользователя владельцем не назначайте.

Запросы выполняет сервисная учетная запись с правами управления пользователями и камерами именно этой организации. Системная роль admin этих прав не заменяет. Используйте ее JWT или персональный ключ по инструкции авторизации. Во всех запросах ниже нужны заголовки Authorization: Bearer <token> и Content-Type: application/json.

В примере 7 — идентификатор существующей общей организации, 12 — выбранной папки, 15 — нового пользователя. Заменяйте значения идентификаторами из ответов своей установки. Организацию найдите через GET /watcher/client-api/v3/organizations?limit=100, как описано в API организаций.

Шаг 1. Создать обычного пользователя в общей организации¶

POST /watcher/client-api/v3/users

{
  "name": "shared-camera-viewer",
  "password": "ExampleViewerPassword",
  "organization_id": 7,
  "access_level": "generic",
  "user_permissions": {
    "can_edit_users": false,
    "can_edit_streams": false,
    "can_view_streams": false
  }
}

Сохраните id ответа как user_id. Запрос сразу создает членство в указанной организации. Отдельно создавать организацию или назначать пользователя владельцем не требуется. can_view_streams: true открыл бы все камеры организации; can_edit_streams: true дал бы также управление камерами и просмотр видео.

Шаг 2. Получить идентификатор папки¶

GET /watcher/client-api/v3/organizations/7/folders?limit=100

Найдите нужную папку в массиве folders, проверьте ее title и parent_id, сохраните id как folder_id. При непустом next продолжите запрос с cursor=<next> до нахождения нужной папки. Корневая папка Cameras включает все камеры организации: для ограниченного доступа выбирайте отдельную папку с нужными камерами. Доступ распространяется также на ее подпапки.

Шаг 3. Выдать просмотр выбранной папки¶

PUT /watcher/client-api/v3/organizations/7/folders/12/users/15

{
  "can_view": true,
  "can_view_dvr": true,
  "dvr_depth_limit": 0,
  "can_use_ptz": false,
  "can_use_actions": false
}

Здесь разрешены живое видео и весь доступный архив, запрещены PTZ и действия камеры. Для доступа только к живому видео передайте can_view_dvr: false. Значение dvr_depth_limit: 0 снимает ограничение глубины доступа к архиву; оно не меняет срок хранения записей.

Шаг 4. Проверить результат¶

От имени сервисной учетной записи перечитайте права:

GET /watcher/client-api/v3/organizations/7/users/15
GET /watcher/client-api/v3/organizations/7/folders/12/users/15

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

Пример рассчитан на новую учетную запись без ранее выданных прав. У существующего пользователя доступ может сохраняться через другие папки или отдельные камеры. Снятие одного разрешения не отменяет другие разрешения.

Шаг 5. Отозвать доступ¶

Чтобы снять папочные права, сохранив членство и учетную запись:

DELETE /watcher/client-api/v3/organizations/7/folders/12/users/15

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

DELETE /watcher/client-api/v3/organizations/7/users/15

Второй запрос удаляет членство и права в этой организации. Сама учетная запись остается. Повторите проверку доступа от имени пользователя; снятие прав не означает немедленного завершения уже открытой медиасессии. Полное удаление пользователя описано в API пользователей.

Проверка интеграции¶

• Права — проверьте действия сервисной учетной записи в организации, владельцем которой является пользователь. Для Client API системная роль не заменяет организационные права.
• Повтор запроса — не допускайте создания второй камеры после сетевого сбоя; храните выданное имя и сверяйте состояние.
• Доступ к видео — can_edit_streams включает просмотр; can_view_streams распространяется на все камеры организации. Для отдельных камер используйте папки.
• Приостановка — проверьте вход отключенного пользователя и отдельно ранее выпущенные токены общего доступа.
• Пресет — перечитайте пресет камеры и проверьте архив после изменения.
• Удаление — отличайте исключение из организации, удаление пользователя и каскадное удаление организации.

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

Исторические пути и изменения модели перечислены в таблице миграции. Проверяйте не только адрес: в v3 изменились структура полей и проверки прав. Все рабочие примеры этой статьи используют v3.