Skip to content

API для управления папками

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

Дополнительную информацию о папках см. на странице Распределение камер по папкам и добавление в Избранное. Дополнительную информацию об интеграции с биллингом см. на странице Интеграция в существующую систему биллинга.

В этом разделе приводятся примеры API-запросов для работы с папками. Полный список параметров запросов и ответов см. по ссылке.

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

Получение списка папок

Чтобы получить список папок в конкретной Организации, используйте запрос

GET URL_ВАШЕГО_WATCHER/vsaas/api/v2/organizations/(идентификатор организации)/folders

Если в заголовке передать ключ x-vsaas-session текущего пользователя, то запрос вернет список папок, доступных текущему пользователю. Чтобы получить список всех папок в Организации, используйте x-vsaas-api-key.

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

Пример запроса папок в Организации с идентификатором 6

curl 'http://localhost/vsaas/api/v2/organizations/6/folders' \
-H 'x-vsaas-session: tPbYSDBiaX4C8_BMuySsr63r-qQ'

В Организации две папки — корневая папка Cameras, созданная по умолчанию, и вложенная в нее New folder, созданная пользователем.

[
    {
        "map_topleft": null,
        "parent_id": null,
        "map_topright": null,
        "order_num": 1,
        "coordinates": null,
        "camera_count": 2,
        "map_bottomleft": null,
        "organization_id": 6,
        "id": 7,
        "title": "Cameras",
        "level": 0
    },
    {
        "map_topleft": null,
        "parent_id": 7,
        "map_topright": null,
        "order_num": 1,
        "coordinates": null,
        "camera_count": 1,
        "map_bottomleft": null,
        "organization_id": 6,
        "id": 18,
        "title": "New folder",
        "level": 1
    }
]

Создание папки

Чтобы создать папку, отправьте запрос

POST URL_ВАШЕГО_WATCHER/vsaas/api/v2/organizations/(идентификатор организации)/folders

Обязательные параметры запроса:

  • title (string) — название папки
  • parent_id (integer) — идентификатор родительской папки.

Необязательные параметры:

  • order_num (integer) — порядковый номер папки в списке. Если параметр не задан или занят, назначается следующий свободный порядковый номер.

Если для папки нужно задать многоуровневый графический план, то можно использовать следующие параметры:

  • coordinates (string) — координаты центра изображения, широта и долгота разделятся пробелом, разделитель дробной части точка.
  • map_bottomleft (string) — координаты нижнего левого угла изображения.
  • map_topleft (string) — координаты верхнего левого угла изображения.
  • map_topright (string) — координаты верхнего правого угла изображения.

  • map_file (object) — изображение графического плана:

    • b64_content (string) — изображение в формате base64
    • delete (boolean) — true, если нужно удалить ранее добавленный файл (при наличии), или false, если нужно его оставить
    • mime_type (string) — MIME-тип изображения

Пример

curl --request POST \
--url http://localhost/vsaas/api/v2/organizations/6/folders \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"title": "Folder name",
"parent_id": 7
}'

Запрос вернет параметры созданной папки. Обратите внимание, что объект map_file в ответе содержит только параметр url.

{"map_topleft":null,
"parent_id":7,
"map_topright":null,
"map_file":{"url":null},
"order_num":4,
"coordinates":null,
"camera_count":0,
"map_bottomleft":null,
"organization_id":6,
"id":22,
"title":"Folder name",
"level":1}

Изменение папки

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

PUT URL_ВАШЕГО_WATCHER/vsaas/api/v2/organizations/(идентификатор организации)/folders/(идентификатор папки)

В запрос можно передать те же параметры, что и при создании папки, а также следующие дополнительные параметры, позволяющие изменить положение папки в дереве:

move_after (integer) — идентификатор папки, следом за которой нужно поместить текущую папку. move_before (integer) — идентификатор папки, перед которой нужно поместить текущую папку. move_inside (integer) — идентификатор папки, в которую нужно поместить текущую папку.

Ниже приведены более подробные примеры использования этих параметров.

Пример изменения названия папки

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"title": "toor"
}'

Запрос вернет все параметры измененного объекта, как в примере выше.

Изменение положения папки в дереве:

Примеры ниже приведены для следующего дерева папок в Организации:

Перемещение папки

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/folders/3/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"move_after": 4
}'

Результат:

Изменение родителя

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/folders/3/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"move_inside": 4
}'

Результат:

Удаление папки

Запрос на удаление папки:

DELETE URL_ВАШЕГО_WATCHER/vsaas/api/v2/organizations/(идентификатор организации)/folders/(идентификатор папки)

Пример 

curl --request DELETE \
--url 'http://localhost/vsaas/api/v2/organizations/1/folders/1' \
--header 'x-vsaas-session: <vsaas_session>'

В случае успешного выполнения запроса Watcher вернет {"success":true}.

Запрос камер в папке

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

GET URL_ВАШЕГО_WATCHER/vsaas/api/v2/cameras?folder_id=(идентификатор папки)

Пример

curl --request GET \
--url 'http://localhost/vsaas/api/v2/cameras?folder_id=7' \
--header 'x-vsaas-session: <vsaas_session>'

Запрос вернет все параметры всех камер, добавленных в папку. Камеры из дочерних папок не включаются в ответ.

В данном случае запрос вернул две камеры:

[
    {
        "agent_key": null,
        "agent_id": null,
        "thumbnails_url": "",
        "motion_detector_enabled": false,
        "static": true,
        "onvif_profile": null,
        "groups": [],
        "precise_thumbnails": false,
        "enabled": true,
        "dvr_space": null,
        "folder_id": 7,
        "precise_thumbnails_days": 0,
        "dvr_lock_days": 1,
        "agent_model": null,
        "user_attributes": {},
        "playback_config": {
            "token": "2.-s9tHGUHAAEABcXhj_yu3vqQhCc5l9Zv1aS-onP8IcVoG4Pl"
        },
        "thumbnails": false,
        "folder_coordinates": null,
        "substream_url": "",
        "preset": {
            "vision_alg": null,
            "vision_params": {},
            "vision_areas": null,
            "is_adjustable": true,
            "vision_enabled": null,
            "dvr_depth": 2,
            "domain_id": 1,
            "dvr_space": null,
            "vision_gpu": null,
            "id": 8,
            "is_default": true,
            "dvr_lock_days": 1,
            "title": "2+1days_adjustable",
            "is_deleted": false
        },
        "comment": "",
        "vision_alg": null,
        "last_change": {
            "object_type": "Camera",
            "created_at": 1623922927,
            "object_id": "samplecamera2-1584a116d9",
            "user": "admin"
        },
        "streamer_id": 1,
        "onvif_ptz": false,
        "preset_id": 8,
        "dvr_path": "/dvr",
        "coordinates": "",
        "permissions": {
            "dvr": true,
            "ptz": true,
            "edit": true,
            "view": true,
            "actions": true
        },
        "postal_address": "",
        "agent_serial": null,
        "dvr_depth": 2,
        "organization_id": 6,
        "video_only": false,
        "external_id": null,
        "stream_url": "file://vod/sample-10s.mp4 ",
        "agent_status": null,
        "vision_areas": null,
        "onvif_url": null,
        "vision_enabled": null,
        "last_event_time": null,
        "stream_status": {
            "alive": false,
            "lifetime": 5948,
            "source_error": null,
            "http_port": 80,
            "https_port": null,
            "bitrate": 4294,
            "server": "localhost"
        },
        "name": "samplecamera2-1584a116d9",
        "has_actions": false,
        "vision_gpu": null,
        "title": "SampleCamera2"
    },
    {
        "agent_key": null,
        "agent_id": null,
        "thumbnails_url": "",
        "motion_detector_enabled": false,
        "static": true,
        "onvif_profile": null,
        "groups": [],
        "precise_thumbnails": false,
        "enabled": true,
        "dvr_space": null,
        "folder_id": 7,
        "precise_thumbnails_days": 0,
        "dvr_lock_days": 1,
        "agent_model": null,
        "user_attributes": {},
        "playback_config": {
            "token": "2.-s9tHGUHAAEABcXhj_yu3gCkwPvOTwRbY3O60MZ0Qb117UHv"
        },
        "thumbnails": false,
        "folder_coordinates": null,
        "substream_url": "",
        "preset": {
            "vision_alg": null,
            "vision_params": {},
            "vision_areas": null,
            "is_adjustable": false,
            "vision_enabled": null,
            "dvr_depth": 1,
            "domain_id": 1,
            "dvr_space": null,
            "vision_gpu": null,
            "id": 7,
            "is_default": true,
            "dvr_lock_days": 1,
            "title": "1+1days_non-adjustable",
            "is_deleted": false
        },
        "comment": "",
        "vision_alg": null,
        "last_change": {
            "object_type": "Camera",
            "created_at": 1623923311,
            "object_id": "samplecamera4-fd2f695a2e",
            "user": "admin"
        },
        "streamer_id": 1,
        "onvif_ptz": false,
        "preset_id": 7,
        "dvr_path": "/dvr",
        "coordinates": "",
        "permissions": {
            "dvr": true,
            "ptz": true,
            "edit": true,
            "view": true,
            "actions": true
        },
        "postal_address": "",
        "agent_serial": null,
        "dvr_depth": 1,
        "organization_id": 6,
        "video_only": false,
        "external_id": null,
        "stream_url": "file://vod/sample-5s.mp4 ",
        "agent_status": null,
        "vision_areas": null,
        "onvif_url": null,
        "vision_enabled": null,
        "last_event_time": null,
        "stream_status": {
            "alive": false,
            "lifetime": 6008,
            "source_error": null,
            "http_port": 80,
            "https_port": null,
            "bitrate": 4081,
            "server": "localhost"
        },
        "name": "samplecamera4-fd2f695a2e",
        "has_actions": false,
        "vision_gpu": null,
        "title": "SampleCamera4"
    }
]

Пользователи в папке

Просмотр пользователей в папке

Чтобы получить список пользователей, имеющих права на доступ к папке, используйте запрос

GET URL_ВАШЕГО_WATCHER/vsaas/api/v2/organizations/(идентификатор организации)/folders/(идентификатор папки)/users

curl --request GET \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/users \
--header 'x-vsaas-session: <vsaas_session>' 

[
    {
        "can_use_ptz": true,
        "can_use_actions": true,
        "can_view_dvr": true,
        "user_id": 16,
        "dvr_depth_limit": null
    },
    {
        "can_use_ptz": false,
        "can_use_actions": false,
        "can_view_dvr": true,
        "user_id": 14,
        "dvr_depth_limit": 1
    }
]

Просмотр прав конкретного пользователя во всех доступных ему папках

Чтобы получить список прав пользователя во всех доступных ему папках, используйте запрос

GET URL_ВАШЕГО_WATCHER/vsaas/api/v2/users/(user_id)?fields=folders_permissions'

curl --request GET \
--url http://localhost/vsaas/api/v2/users/2?fields=folders_permissions' \
--header 'x-vsaas-session: <vsaas_session>' 

{
    "folders_permissions": [
        {
            "folder_id": 1,
            "organization_id": 1,
            "can_view_dvr": true,
            "dvr_depth_limit": 365,
            "can_use_ptz": false,
            "can_use_actions": false
        },
        {
            "folder_id": 25,
            "organization_id": 12,
            "can_view_dvr": false,
            "dvr_depth_limit": null,
            "can_use_ptz": false,
            "can_use_actions": false
        }
    ]
}

Просмотр прав конкретного пользователя в папках конкретной Организации

Чтобы узнать, какие права доступа к папкам Организации имеет пользователь, отправьте запрос:

GET URL_ВАШЕГО_WATCHER/vsaas/api/v2/users/(user_id)?fields=folders_permissions'

curl --request GET \
--url http://localhost/vsaas/api/v2/organizations/1/users/2?fields=folders_permissions' \
--header 'x-vsaas-session: <vsaas_session>' 

{
    "folders_permissions": [
        {
            "folder_id": 1,
            "can_view_dvr": true,
            "dvr_depth_limit": 6,
            "can_use_ptz": false,
            "can_use_actions": false
        },
        {
            "folder_id": 13,
            "can_view_dvr": false,
            "dvr_depth_limit": null,
            "can_use_ptz": false,
            "can_use_actions": false
        }
    ]
}

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

Чтобы дать пользователю права на просмотр живого видео и архива, а также управление PTZ, отправьте запрос

POST URL_ВАШЕГО_WATCHER/vsaas/api/v2/organizations/(идентификатор организации)/folders/(идентификатор папки)/users

Параметры запроса:

  • user_id (integer) — идентификатор пользователя
  • can_use_ptz (bool) — true, если пользователь может управлять PTZ, или false, если ему это запрещено
  • can_view_dvr (bool) — true, если пользователь может смотреть архив, или false, если ему это запрещено
  • can_use_actions (bool) — true, если пользователь может использовать действия с камерой, или false, если ему это запрещено
  • dvr_depth_limit (integer) — количество дней архива, доступных пользователю; null означает неограниченный доступ
curl --request POST \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/users \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"can_view_dvr": 10,
"can_use_ptz": 1,
"user_id": 14
}'

{
    "can_use_actions": null,
    "dvr_depth_limit": null,
    "can_use_ptz": 1,
    "user_id": 14,
    "can_view_dvr": 10
}

Изменение прав пользователя в папке

Чтобы изменить права пользователя на просмотр живого видео и архива, а также управление PTZ, отправьте запрос

POST URL_ВАШЕГО_WATCHER/vsaas/api/v2/organizations/(идентификатор организации)/folders/(идентификатор папки)/users

Параметры запроса такие же, как при назначении прав (см. выше).

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/users/1/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"can_use_ptz": 1,
"can_view_dvr": 5
}'

Запрос вернет права пользователя в папке, как в примере выше.

Удаление пользователя из папки

Чтобы отключить пользователю доступ к папке, отправьте запрос

DELETE https://watcher_api_url/vsaas/api/v2/organizations/(organization_id)/folders/(folder_id)/users/(user_id)

curl --request DELETE \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/users/1/ \
--header 'x-vsaas-session: <vsaas_session>' \

В случае успешного выполнения запроса Watcher вернет {"success":true}.