Вебхуки

Вы можете настроить FindFace Multi для автоматической отправки уведомлений об определенных событиях, эпизодах, скриншотах счетчиков на заданный URL-адрес. Для этого создайте и настройте вебхук. При возникновении нужного события/эпизода/скриншота счетчика FindFace Multi отправит HTTP-запрос на URL-адрес, указанный в настройках вебхука.

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

В этом разделе:

Настройка вебхука

Важно

Для создания вебхука необходимы права администратора.

Примечание

Перед использованием вебхуков убедитесь, что хотя бы один из следующих параметров задан в файле /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py: SERVICE_EXTERNAL_ADDRESS или EXTERNAL_ADDRESS.

Для создания вебхука выполните следующие действия:

  1. Перейдите на вкладку Настройки. Выберите Вебхуки.

  2. Нажмите + Новый вебхук.

    create_webhook_ru

  3. Введите заголовок вебхука.

    webhook_ru

  4. Укажите адрес, на который будут отправляться оповещения.

  5. Вы можете отправлять уведомления в пакетном режиме. Укажите максимальное количество уведомлений в пакете. Фактическое количество может быть меньшим.

  6. Укажите максимальное количество попыток отправить уведомление. Интервал между попытками увеличивается экспоненциально с максимумом 100 секунд.

    Важно

    Для того чтобы получить все сообщения с момента потери соединения, если оно имеет место, установите значение 0. Установите 1, чтобы пропустить старые сообщения.

  7. FindFace Multi будет автоматически отправлять оповещения о событиях, эпизодах, скриншотах счетчика, удовлетворяющих заданным фильтрам. Фильтровать события можно по следующим параметрам:

    Универсальные фильтры для событий распознавания (лицо, силуэт, транспортное средство):

    Секции: face_events, body_events, car_events.

    • "allowed_bs_types": режим отслеживания объектов на видео, возможные значения: overall, realtime.

    • "camera_group_in": id группы камер, число.

    • "camera_in": id камеры, число.

    • "confidence_gte": минимальное значение уверенности алгоритма, число.

    • "matched_lists_in": id списка наблюдения, число.

    • "matched_card_in": id совпавшей карточки, число.

    • "matched": результат сопоставления с картотекой, логическое значение. Установите true или false, если отправку оповещения должны вызывать только события с совпадениями или только события без совпадений.

    Фильтры для событий распознавания лиц:

    Секция: face_events.

    • "liveness_gte": минимальное значение уверенности алгоритма в том, что лицо витально, десятичное число.

    • "headpose_yaw_angle_gte": минимальный поворот головы, число (градусы). Если голова полностью повернута влево, угол равен -180. Если полностью повернута вправо, то 180. Нейтральное положение головы соответствует 0.

    • "headpose_yaw_angle_lte": максимальный поворот головы, число (градусы). Если голова полностью повернута влево, угол равен -180. Если полностью повернута вправо, то 180. Нейтральное положение головы соответствует 0.

    • "headpose_pitch_angle_gte": минимальный наклон головы, число (градусы). Если голова наклонена вперед, а подбородок касается груди, угол равен -180. Если голова наклонена назад и обращена к небу, то 180. Нейтральное положение головы соответствует 0.

    • "headpose_pitch_angle_lte": максимальный наклон головы, число (градусы). Если голова наклонена вперед, а подбородок касается груди, угол равен -180. Если голова наклонена назад и обращена к небу, то 180. Нейтральное положение головы соответствует 0.

    • "gender_in": пол, словарь строк. Возможные значения: "male", "female".

    • "age_lte": максимальный возраст, число.

    • "age_lte": минимальный возраст, число.

    • "glasses_in": очки, словарь строк. Возможные значения: "none", "eye" (очки), "sun" (солнцезащитные очки).

    • "emotions_in": эмоции, словарь строк. Возможные значения: "any", "angry", "fear", "sad", "neutral", "disgust", "happy", "surprise".

    • "beard_in": борода, словарь строк. Возможные значения: "none", "beard".

    • "medmask_in": медицинская маска, словарь строк. Возможные значения: "correct", "incorrect", "none".

    • "liveness_in": оценка витальности liveness, словарь строк. Возможные значения: "real", "fake".

    Фильтры для событий распознавания силуэтов:

    Секция: body_events.

    • "headwear_in": тип головного убора (шапка/кепка, капюшон/платок, без убора), словарь строк. Возможные значения: "hat", "hood", "none".

    • "upper_clothes_in": обобщенная категория одежды верхней части тела (с длинными рукавами, с короткими рукавами, без рукавов), словарь строк. Возможные значения: "long_sleeves", "short_sleeves", "without_sleeves".

    • ”detailed_upper_clothes_in”: детализированный тип одежды верхней части тела (куртка, пальто, жилет без рукавов, толстовка, футболка, рубашка, платье), словарь строк. Возможные значения: ”jacket”`, ``”coat”, ”sleeveless”, ”sweatshirt”, ”t-shirt”, ”shirt”, ”dress”.

    • "top_color_in": цвет одежды верхней части тела, словарь строк. Возможные значения: white, "black", "grey", "brown", "red", "orange", "yellow", "green", "lightblue", "blue", "purple", "pink", "beige", "violet".

    • "lower_clothes_in": тип одежды нижней части тела (брюки, юбка, шорты, неопределенный), словарь строк. Возможные значения:"pants", "obscured", "skirt", "shorts".

    • "bottom_color_in": цвет одежды нижней части тела, словарь строк. Возможные значения: white, "black", "grey", "brown", "red", "orange", "yellow", "green", "lightblue", "blue", "purple", "pink", "beige", "violet".

    • "bag_hand_in": наличие сумки в руке(ах), словарь строк. Возможные значения: "none", "hand".

    • "bag_back_in": наличие сумки на спине, словарь строк. Возможные значения: "none", "back".

    • "vest_type_score_gte": минимальная достоверность распознавания наличия жилета, число.

    • "vest_type_score_lte": максимальная достоверность распознавания наличия жилета, число.

    • "vest_type_in": наличие средства индивидуальной защиты в виде жилета, словарь строк. Возможные значения:"green/yellow", "orange", "not_visible", "none".

    • "helmet_type_score_lte": максимальная достоверность распознавания наличия шлема, число.

    • "helmet_type_score_gte": минимальная достоверность распознавания наличия шлема, число.

    • "helmet_type_in": наличие средства индивидуальной защиты в виде шлема, словарь строк. Возможные значения: "red/orange", "white", "other", "not_visible", "none".

    • "age_group_score_lte": максимальная достоверность распознавания возрастной группы, число.

    • "age_group_score_gte": минимальная достоверность распознавания возрастной группы, число.

    • "age_group_in": возраст по группе, словарь строк. Возможные значения: "0-16", "17-35", "36-50", "50+".

    • "gender_score_lte": максимальная достоверность распознавания пола, число.

    • "gender_score_gte": минимальная достоверность распознавания пола, число.

    • "gender_in": пол, словарь строк. Возможные значения: "male", "female".

    Фильтры для событий распознавания транспортных средств:

    Секция: car_events.

    • "category_confidence_gte": минимальная достоверность распознавания категории транспортного средства, число.

    • "category_confidence_lte": максимальная достоверность распознавания категории транспортного средства, число.

    • "category_type_in": категория транспортного средства, словарь строк. Возможные значения: "unknown", "A", "B", "BE", "C", "CE", "D", "DE", "other".

    • "color_in" цвет транспортного средства, словарь строк. Возможные значения: "beige", "black", "blue", "brown", "cyan", "gold", "green", "grey", "orange", "pink", "purple", "red", "violet", "white", "yellow", "coming_soon", "unknown".

    • "body_in": тип кузова транспортного средства, словарь строк. Возможные значения: "suv", "sedan", "crossover", "convertible", "coupe", "wagon", "cab", "minibus", "minivan", "limousine", "coming_soon", "unknown".

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

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

    • "license_plate_number_in": регистрационный номер транспортного средства, словарь строк. Подстановочные знаки не поддерживаются.

    • "license_plate_color_in": цвет номерного знака, словарь строк. Возможные значения: "unknown", "white", "yellow", "blue", "green", "grey".

    • "license_plate_color_confidence_lte": максимальная достоверность распознавания цвета номерного знака, число.

    • "license_plate_color_confidence_gte": минимальная достоверность распознавания цвета номерного знака, число.

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

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

    • "special_vehicle_type_in": спецназначение транспортного средства, словарь строк. Возможные значения: "taxi", "route_transport", "car_sharing", "ambulance", "police", "rescue_service", "gas_service", "military", "road_service", "other_special", "not_special", "unknown".

    • "weight_type_in": весовая категория транспортного средства. Возможные значения: "B_light", "B_heavy", "C_light", "C_heavy", "D_light", "D_long", "other".

    • "weight_type_confidence_lte": максимальная достоверность распознавания весовой категории транспортного средства, число.

    • "weight_type_confidence_gte": минимальная достоверность распознавания весовой категории транспортного средства, число.

    • "orientation_in": ракурс транспортного средства, словарь строк. Возможные значения: "front", "back", "side".

    • "orientation_confidence_lte": максимальная достоверность распознавания ракурса автомобиля, число.

    • "orientation_confidence_gte": минимальная достоверность распознавания ракурса автомобиля, число.

    Эпизоды с людьми:

    Секция: human_episodes.

    • "allowed_types": статус эпизода, возможные значения: открытие эпизода (episode_open), добавление нового события в эпизод (episode_event), закрытие эпизода (episode_close).

    • "camera_group_in": id группы камер, число.

    • "camera_in": id камеры, число.

    • "matched_lists_in": id списка наблюдения, число.

    • "face_matched": статус совпадения лица в эпизоде с картотекой, логическое значение. Установите true, если только эпизоды с совпадениями лиц, или false, если только эпизоды без совпадений лиц должны вызывать отправку оповещения.

    • "body_matched": статус совпадения силуэта в эпизоде с картотекой, логическое значение. Установите true, если только эпизоды с совпадениями силуэтов, или false, если только эпизоды без совпадений силуэтов должны вызывать отправку оповещения.

    • "events_count_gte": минимальное количество событий в эпизоде, число.

    • "events_count_lte": максимальное количество событий в эпизоде, число.

    Эпизоды с транспортными средствами:

    Секция: car_episodes.

    • "allowed_types": статус эпизода, возможные значения: открытие эпизода (episode_open), добавление нового события в эпизод (episode_event), закрытие эпизода (episode_close).

    • "camera_group_in": id группы камер, число.

    • "camera_in": id камеры, число.

    • "matched_lists_in": id списка наблюдения, число.

    • "car_matched": статус совпадения транспортного средства в эпизоде с картотекой, логическое значение. Установите true, если только эпизоды с совпадениями ТС, или false, если только эпизоды без совпадений ТС должны вызывать отправку оповещения.

    • "events_count_gte": минимальное количество событий в эпизоде, число.

    • "events_count_lte": максимальное количество событий в эпизоде, число.

    Скриншоты счетчиков:

    Секция: counters.

    • "counter_in": id счетчика, число.

    • "camera_group_in": id группы камер, число.

    • "camera_in": id камеры, число.

    • "faces_gte": минимальное количество лиц в скриншоте счетчика, число.

    • "faces_lte": максимальное количество лиц в скриншоте счетчика, число.

    • "silhouettes_gte": минимальное количество силуэтов в скриншоте счетчика, число.

    • "silhouettes_lte": максимальное количество силуэтов в скриншоте счетчика, число.

    • "cars_gte": минимальное количество транспортных средств в скриншоте счетчика, число.

    • "cars_lte": максимальное количество транспортных средств в скриншоте счетчика, число.

    • "proximity_min_lte": отправить оповещение, если минимальное задетектированное расстояние в метрах меньше указанной величины, число.

    • "proximity_min_gte": отправить оповещение, если минимальное задетектированное расстояние в метрах больше указанной величины, число.

    • "proximity_avg_lte": отправить оповещение, если среднее задетектированное расстояние в метрах меньше указанной величины, число.

    • "proximity_avg_gte": отправить оповещение, если среднее задетектированное расстояние в метрах больше указанной величины, число.

    • "proximity_max_lte": отправить оповещение, если максимальное задетектированное расстояние в метрах меньше указанной величины, число.

    • "proximity_max_gte": отправить оповещение, если максимальное задетектированное расстояние в метрах больше указанной величины, число.

    {
"face_events": {
"matched_lists_in": [],
"camera_group_in": [],
"camera_in": [],
"matched_card_in": [],
"matched": true,
"confidence_gte": 0.75,
"allowed_bs_types": [
"overall",
"realtime"
],
"liveness_gte": 0.65,
"headpose_yaw_angle_gte": -180,
"headpose_yaw_angle_lte": 180,
"headpose_pitch_angle_gte": -180,
"headpose_pitch_angle_lte": 180,
"gender_in": [],
"age_lte": 0,
"age_gte": 0,
"glasses_in": [],
"emotions_in": [],
"beard_in": [],
"medmask_in": [],
"liveness_in": []
},
"body_events": {
"matched_lists_in": [],
"camera_group_in": [],
"camera_in": [],
"matched_card_in": [],
"matched": true,
"confidence_gte": 0.75,
"allowed_bs_types": [
"overall",
"realtime"
],
"headwear_in": [],
"upper_clothes_in": [],
"detailed_upper_clothes_in": [],
"top_color_in": [],
"lower_clothes_in": [],
"bottom_color_in": [],
"bag_hand_in": [],
"bag_back_in": [],
"vest_type_score_gte": 0,
"vest_type_score_lte": 0,
"vest_type_in": [],
"helmet_type_score_lte": 0,
"helmet_type_score_gte": 0,
"helmet_type_in": [],
"age_group_score_lte": 0,
"age_group_score_gte": 0,
"age_group_in": [],
"gender_score_lte": 0,
"gender_score_gte": 0,
"gender_in": []
},
"car_events": {
"matched_lists_in": [],
"camera_group_in": [],
"camera_in": [],
"matched_card_in": [],
"matched": true,
"confidence_gte": 0.75,
"allowed_bs_types": [
"overall",
"realtime"
],
"category_confidence_gte": 0,
"category_confidence_lte": 0,
"category_type_in": [],
"color_in": [],
"body_in": [],
"make_in": [],
"model_in": [],
"license_plate_number_in": [],
"license_plate_color_in": [],
"license_plate_color_confidence_lte": 0,
"license_plate_color_confidence_gte": 0,
"license_plate_country_in": [],
"license_plate_region_in": [],
"special_vehicle_type_in": [],
"weight_type_in": [],
"weight_type_confidence_lte": 0,
"weight_type_confidence_gte": 0,
"orientation_in": [],
"orientation_confidence_lte": 0,
"orientation_confidence_gte": 0
},
"human_episodes": {
"allowed_types": [
"episode_open",
"episode_event",
"episode_close"
],
"matched_lists_in": [],
"camera_in": [],
"camera_group_in": [],
"events_count_gte": 0,
"events_count_lte": 999,
"face_matched": true,
"body_matched": true },
"car_episodes": {
"allowed_types": [
"episode_open",
"episode_event",
"episode_close"
],
"matched_lists_in": [],
"camera_in": [],
"camera_group_in": [],
"events_count_gte": 0,
"events_count_lte": 999,
"car_matched": true },
"counters": {
"counter_in": [],
"camera_in": [],
"camera_group_in": [],
"faces_gte": 1,
"faces_lte": 100,
"silhouettes_gte": 1,
"silhouettes_lte": 100,
"cars_gte": 1,
"cars_lte": 100,
"proximity_min_lte": 100,
"proximity_min_gte": 0,
"proximity_avg_lte": 100,
"proximity_avg_gte": 0,
"proximity_max_lte": 100,
"proximity_max_gte": 0
}
}

    Важно

    Используйте только фильтры, соответствующие цели поиска. Для выключения фильтра удалите его из вебхука. Не оставляйте фильтр пустым ([]), поскольку в этом случае фильтр вернет пустой результат.

    Примечание

    Для получения всех оповещений передайте скобки без вложенных фильтров:

    {}

    Совет

    Пример №1. Получение оповещений обо всех событиях c транспортными средствами:

    { "car_events": {} }

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

    { "human_episodes": { "allowed_types": ["episode_open"], "face_matched": true, "body_matched": true }}

    Примечание

    Вы можете задать несколько значений в фильтрах с квадратными скобками. В этом случае вебхук будет активироваться при совпадении одного из значений фильтра. В примере ниже вы будете оповещены о событии с силуэтом с группы камер 1 или 3, если совпала карточка с id 12 или 25.

    {
        "body_events": {
                "camera_group_in": [1, 3],
                "matched_card_in": [12, 25],
        },
}

  8. Поставьте флажок Активная.

  9. Нажмите Сохранить.

Как работает вебхук

Для тестирования работы вебхука можно использовать следующий простой веб-сервер на Python, обеспечивающий захват отправленных вебхуком оповещений о событиях:

from pprint import pprint
from aiohttp import web


async def handle(request):
    pprint(await request.json())
    return web.Response(status=200)


app = web.Application()
# for aiohttp v 3.x
# app.add_routes([web.post('/', handle)])

# for aiohttp v 2.x
app.router.add_post('/', handle)

web.run_app(app, port=8888)

Важно

Используемый вами сервер-ловушка оповещений по вебхуку должен возвращать ответ HTTP 200 после получения вебхука от FindFace Multi, по аналогии с примером выше.

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

Для просмотра статуса отправки вебхука в FindFace Multi выполните следующую команду:

sudo journalctl CONTAINER_NAME=findface-multi-findface-multi-legacy-1 -f | grep 'Webhook'

Подробные данные в вебхуках (Verbose)

По умолчанию оповещения по вебхуку содержат только идентификаторы таких сущностей, как карточки, списки наблюдения, камеры и группы камер. Для того чтобы получать подробную информацию по данным сущностям, включите подробный режим оповещений по вебхукам (режим verbose).

Для этого откройте файл конфигурации /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py и установите в нем 'VERBOSE_WEBHOOKS': True:

sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py

...
FFSECURITY = {
    ...
    # send serialized cards, card-lists, camera and camera groups in webhooks
    'VERBOSE_WEBHOOKS': True,
    ...
}
...

После внесения изменений обязательно перезапустите контейнер findface-multi-findface-multi-legacy-1.

sudo docker container restart findface-multi-findface-multi-legacy-1