Перейти к содержанию

Работа с API платформы

В руководстве представлены некоторые примеры работы с API платформы NtechCity, однако оно не является полным описанием всех доступных API-методов. Для получения полного перечня доступных методов API со схемами рекомендуется использовать openapi-спецификацию.

Веб-интерфейс API

Взаимодействие с API доступно в веб-интерфейсе по относительному пути v1/docs инсталляции.

API Web UI
API Web UI

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

Платформа использует ObjectID

Идентификаторами большой части сущностей в main-api и платформе выступают MongoDB ObjectID. Исключение составляют функциональные решения - для них идентификатором выступает строка.

Создание сущностей PUT-методами

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

Авторизация в платформе

В платформе используется схема с access/refresh-токенами.

Система не даст получить никакие данные, если в запросе не передать валидный access-токен.

Токен можно получить по логину и паролю. Пример:

curl -X POST "http://ntech.city/v1/login" \
 -H "accept: application/json" \
 -H "content-type: application/json" \
 -d '{"username":"lg","password":"pw","device_id":"string"}'

Ответом будет пара токенов:

{
  "access": "eyJ<...>.eyJ<...>.YIi<...>", // (1)! 
  "refresh": "xb09aa92-5d40-41bc-ba22-9f18a5bb8389" // (2)!
}
  1. Короткоживущий access-токен
  2. Токен для обновления access-токена. Операция обновления (и отслеживания актуальности токена) реализуется клиентом

Access-токен является JWT-токеном, из которого можно извлечь время окончания его действия. На базе этой информации можно строить логику работы клиентского приложения.

Полезная нагрузка access-токена:

{
  "exp": 1712313999, // (1)!
  "iat": 1712312199, // (2)!
  "org_id": "80755db904e7318decb2fb68", // (3)!
  "user_id": "b74aa2ffd6e655d9a3dc3d7b", // (4)!
  "adm": false, // (5)!
  "org_adm": false // (6)!
}
  1. Время истечения
  2. Время выдачи
  3. Идентификатор организации
  4. Идентификатор пользователя
  5. Наличие роли "Администратор" у пользователя
  6. Наличие роли "Администратор" у организации

Обновление токена

Для обновления необходимо отправить платформе полученный при авторизации refresh-токен и device_id:

curl -X POST "http://ntech.city/v1/refresh" \
 -H "accept: application/json"\
 -H "content-type: application/json" \
 -d '{"refresh_token":"xb09aa92-5d40-41bc-ba22-9f18a5bb8389","device_id":"string"}'

Запрос вернет новую пару токенов, которую клиент должен сохранить на своей стороне:

{
  "access": "eyJ<...>.eyJ<...>.YIi<...>",
  "refresh": "4be973c1-3a48-480e-88a6-76110ab24712"
}

Функциональные решения

Объект ФР описывает набор нейронных сетей для анализа видеопотока или изображения, а также некоторые правила их применения.

В качестве примера в этом руководстве будет рассмотрен ФР-3.

Список функциональных решений

Пример запроса списка доступных ФР:

curl -X GET "http://ntech.city/v1/main-api/hb/functional-solutions" \
 -H "accept: application/json" \
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>"

Ответ (в ФР-3 задачи анализа КП и задачи наблюдения за автомобилями разделены на отдельные сущности функциональных решений):

{
  "collection": [
    {
      "name": "Мониторинг ТКО - контейнеры и мусор",
      "description": "Мониторинг ТКО. Часть для работы с контейнерами, площадками и мусором.",
      "available_for": ["000000000000000000000000"],
      "is_enabled": true,
      "required_models": {
        "garbage": {
          "garbage": ["garbage_types4"]
        },
        "dumpster": {
          "dumpster": ["dumpster_types23", "dumpster_types22"]
        },
        "dumpster_enclosure": {
          "dumpster_enclosure": []
        }
      },
      "shot_settings": {
        "interval_sec": 1800,
        "roi": null
      },
      "stream_settings": null,
      "service_route_name": "trash",
      "service_url": "http://fs-ntl-tbo:18920",
      "swagger_path": "/openapi.json",
      "ui_settings": null,
      "id": "trash"
    },
    {
      "name": "Мониторинг ТКО - транспортные средства",
      "description": "Мониторинг ТКО. Часть для работы с транспортыми средствами.",
      "available_for": ["000000000000000000000000"],
      "is_enabled": true,
      "required_models": {
        "car": {
          "car": ["car_license_plate", "car_trash"]
        }
      },
      "shot_settings": {
        "interval_sec": 10,
        "roi": null
      },
      "stream_settings": null,
      "service_route_name": "tko_cars",
      "service_url": "http://localhost",
      "swagger_path": "",
      "ui_settings": null,
      "id": "tbo_cars"
    }
  ],
  "next_page": null
}

Получение по ID

Можно запросить ФР по его строковому идентификатору:

curl -X GET "http://ntech.city/v1/main-api/hb/functional-solutions/trash" \
 -H "accept: application/json" \
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>" \

Ответом будет объект функционального решения:

{
  "name": "Мониторинг ТКО - контейнеры и мусор",
  "description": "Мониторинг ТКО. Часть для работы с контейнерами, площадками и мусором.",
  "available_for": ["000000000000000000000000"],
  "is_enabled": true,
  "required_models": {
    "garbage": {
      "garbage": ["garbage_types4"]
    },
    "dumpster": {
      "dumpster": ["dumpster_types23", "dumpster_types22"]
    },
    "dumpster_enclosure": {
      "dumpster_enclosure": []
    }
  },
  "shot_settings": {
    "interval_sec": 1800,
    "roi": null
  },
  "stream_settings": null,
  "service_route_name": "trash",
  "service_url": "http://fs-ntl-tbo:18920",
  "swagger_path": "/openapi.json",
  "ui_settings": null,
  "id": "trash"
}

Лицензии

При создании процессингов необходимы идентификаторы лицензий, иначе система не позволит ничего создать.

Для получения списка доступных лицензий есть отдельный API-метод.

Запрос:

curl -X GET "http://ntech.city/v1/main-api/license" \
 -H "accept: application/json" \
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>"

Ответ:

[
  {
    "id": "trash_lic",
    "license_info": {
      "fs_id": "trash",
      "dt_start": null,
      "dt_end": null,
      "prc_count": 10000,
      "shot_mode": true,
      "stream_mode": true,
      "features": {}
    }
  },
  {
    "id": "tbo_cars_lic",
    "license_info": {
      "fs_id": "tbo_cars",
      "dt_start": null,
      "dt_end": null,
      "prc_count": 10000,
      "shot_mode": true,
      "stream_mode": true,
      "features": {}
    }
  }
]

Камеры

Создание камеры

Шард shot-manager

При создании камеры необходимо указать шард сервиса, который будет заниматься обработкой кадров и видео-потоков. В случае работы с ТБО используются только кадры, соответственно для камер достаточно указать shotmanager_shard. Получить доступные шарды можно следующим образом:

curl -X GET "http://ntech.city/v1/main-api/camera/shotmanager-shards" \
 -H "accept: application/json" \
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>"

Ответ:

{
  "http://shot-manager-0:18730": {
    "name": "Default shotmanger shard",
    "description": null
  }
}

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

Создание камеры

Для создания камеры необходимо отправить PUT-запрос, пример:

curl -X PUT "http://ntech.city/v1/main-api/camera/312b3c1ecd877fe36206a0b2" \
 -H "accept: application/json" \
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>" \
 -H "content-type: application/json" \
 -d '{"external_id":null,"name":"Название камеры","stream_url":"rtsp://ip:port:554/live?id=5850","shot_url":null,"integration_id":null,"coords":{"lon":43.466431,"lat":56.252282},"alt":0,"azimuth":0,"fl":0,"available_for":[],"labels":null,"is_enabled":false,"videomanager_shard":null,"shotmanager_shard":"http://shot-manager-0:18730"}'

В теле запроса передается объект камеры со следующими полями:

{
  "external_id": null, // (1)!
  "name": "Название камеры", // (2)!  
  "stream_url": "rtsp://ip:port/live?id=48f8d848", // (3)!
  "shot_url": null, // (4)!
  "integration_id": null,
  "coords": {
    "lon": 43.466431,
    "lat": 56.252282
  },
  "alt": 0,
  "azimuth": 0,
  "fl": 0,
  "available_for": [], // (5)!
  "labels": null,
  "is_enabled": false, // (6)!
  "videomanager_shard": null,
  "shotmanager_shard": "http://shot-manager-0:18730" // (7)!
}
  1. ID во внешней системе, можно не указывать
  2. Название камеры
  3. Адрес, по которому доступен поток
  4. Адрес для получения кадров напрямую, если у VMS-системы есть такая функция
  5. Доступность камеры, по умолчанию будет доступна организации-создателю и double-A
  6. Включение или отключение камеры
  7. Идентификатор шарда шотменеджера

Ответом на запрос будет объект камеры или ошибка:

{
  "external_id": null,
  "name": "Название камеры",
  "stream_url": "rtsp://ip:port/live?id=48f8d848",
  "shot_url": null,
  "integration_id": null,
  "coords": {
    "lon": 43.466431,
    "lat": 56.252282
  },
  "alt": 0,
  "azimuth": 0,
  "fl": 0,
  "available_for": [],
  "labels": null,
  "is_enabled": false,
  "videomanager_shard": null,
  "shotmanager_shard": "http://shot-manager-0:18730",
  "id": "312b3c1ecd877fe36206a0b2",
  "owner": "80755db904e7318decb2fb68"
}

Список камер

Для получения списка камер необходимо отправить GET-запрос:

curl -X GET "http://ntech.city/v1/main-api/camera" \
 -H "accept: application/json"\
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>"

Ответом будет пагинированный список камер:

{
  "collection": [
    {
      "external_id": null,
      "name": "Верхне-Печерская 3, подъезд 1",
      "stream_url": "rtsp://ip:port/live?id=48f8d848",
      "shot_url": null,
      "integration_id": null,
      "coords": {
        "lon": 44.067305,
        "lat": 56.296998
      },
      "alt": 0,
      "azimuth": 0,
      "fl": 0,
      "available_for": [],
      "labels": null,
      "is_enabled": true,
      "videomanager_shard": null,
      "shotmanager_shard": "http://shot-manager-0:18730",
      "id": "312b3c1ecd877fe36206a0b1",
      "owner": "80755db904e7318decb2fb68"
    },
    {
      "external_id": null,
      "name": "Василия Иванова 14/7",
      "stream_url": "rtsp://ip:port/live?id=48f8d848",
      "shot_url": null,
      "integration_id": null,
      "coords": {
        "lon": 43.828389,
        "lat": 56.361713
      },
      "alt": 0,
      "azimuth": 0,
      "fl": 0,
      "available_for": [],
      "labels": null,
      "is_enabled": true,
      "videomanager_shard": null,
      "shotmanager_shard": "http://shot-manager-0:18730",
      "id": "8e309633842d15f6b41c9e8f",
      "owner": "80755db904e7318decb2fb68"
    }
  ],
  "next_page": "8e309633842d15f6b41c9e8f"
}

Здесь и в других API-методах листинга можно получить следующую страницу, передав query-параметр page:

curl -X GET "http://ntech.city/v1/main-api/camera?limit=1&page=312b3c1ecd877fe36206a0b1" \
 -H "accept: application/json"\
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>"

Обновление информации о камере

Атрибуты камеры можно обновить, отправив PATCH-запрос. Права на обновление есть только у администратора организации:

curl -X PATCH "http://ntech.city/v1/main-api/camera/1345df4940b0efd60dc9924e" \
 -H "accept: application/json" \
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>" \
 -H "content-type: application/json" \
 -d '{"coords":{"lon":43.828388,"lat":56.361713}}'

В ответ будет отправлен обновленный объект камеры:

{
  "external_id": null,
  "name": "Гордеевская 40",
  "stream_url": "rtsp://ip:port/live?id=48f8d848",
  "shot_url": null,
  "integration_id": null,
  "coords": {
    "lon": 43.828388,
    "lat": 56.361713
  },
  "alt": 0,
  "azimuth": 0,
  "fl": 0,
  "available_for": [],
  "labels": null,
  "is_enabled": true,
  "videomanager_shard": null,
  "shotmanager_shard": "http://shot-manager-0:18730",
  "id": "1345df4940b0efd60dc9924e",
  "owner": "80755db904e7318decb2fb68"
}

Процессинги

Для "включения" обработки видео-потоков или кадров необходимо создать процессинг.

Процессинг - сущность, которая говорит системе "запусти ФР для камеры #1 от лица организации Х используя лицензию Z"

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

Создание процессинга

Аналогично камерам - создание осуществляется путем отправки PUT-запроса.

Объект процессинга:

{
  "enabled_models": null, // (1)! 
  "shot_settings": { // (2)! 
    "interval_sec": null, // (3)! 
    "roi": [ // (4)! 
      565,
      412,
      764,
      688
    ]
  },
  "stream_settings": null,
  "meta": {}, // (5)! 
  "is_enabled": true, // (6)! 
  "license_id": "trash_lic", // (7)! 
  "id": "461b43a850b722f5af479977",
  "cam_id": "b873bc0030e94b7fd702ffed", // (8)! 
  "org_id": "80755db904e7318decb2fb68", // (9)! 
  "fs_id": "trash", // (10)! 
  "status": "active" // (11)! 
}
  1. Включенные модели нейронных сетей, при null - наследуются от объекта ФР
  2. Настройки обработки кадров
  3. Частота снятия и анализа кадров, при null - наследуется от объекта ФР
  4. Зона интереса, поддерживаются только прямоугольники
  5. Произвольный словарь, при необходимости локальный бекенд может помечать свои процессинги
  6. Включение/отключение процессинга
  7. Идентификатор лицензии
  8. Идентификатор камеры
  9. Идентификатор организации-создателя
  10. Идентификатор функционального решения
  11. Статус (устанавливается системой)

Пример запроса на создание:

curl -X PUT "http://ntech.city/v1/main-api/processing/461b43a850b722f5af479978" \
 -H "accept: application/json"\
 -H "authorization: Bearer <JWT_ACCESS_TOKEN>"\
 -H "content-type: application/json" \
 -d '{"enabled_models":null,"shot_settings":{"interval_sec":400,"roi":[565,412,764,688]},"stream_settings":null,"meta":{},"is_enabled":false,"license_id":"trash_lic","cam_id":"b873bc0030e94b7fd702ffed","fs_id":"trash"}' \

Ответ:

{
  "enabled_models": null,
  "shot_settings": {
    "interval_sec": 400,
    "roi": [565, 412, 764, 688]
  },
  "stream_settings": null,
  "meta": {},
  "is_enabled": false,
  "license_id": "trash_lic",
  "id": "461b43a850b722f5af479978",
  "cam_id": "b873bc0030e94b7fd702ffed",
  "org_id": "80755db904e7318decb2fb68",
  "fs_id": "trash",
  "status": "disabled_by_user"
}