Ключевые понятия Oz API

Oz API обеспечивает полноценный REST API-интерфейс для биометрии лица: как сравнения лиц, так и Liveness-проверок. В этой статье описаны основные концепции Oz API.

Аутентификация, роли пользователей и управление доступом

В целях безопасности каждый вызов Oz API требует наличия в заголовке токена доступа. Чтобы получить этот токен, вызовите метод POST /api/authorize/auth с полученными от нас логином и паролем. В ответе вы получите токен доступа. Его нужно будет указывать в заголовке X-Forensics-Access-Token во всех последующих вызовах методов Oz API. Подробнее процесс аутентификации описан здесь.

Для пользователей системы есть набор ролей, различающихся по предоставляемым возможностям: от роли CLIENT, которая дает возможность проводить проверки и скачивать отчеты без прав администратора, до ADMIN с полным доступом практически ко всем объектам системы. Детальная информация по ролям находится здесь.

Сохранение данных

Основная сущность в Oz API – это папка (заявка): в папку вы можете загружать медиафайлы, запускать для них анализы и получать результаты не только для отдельных анализов, но и для папки в целом. В одной папке может быть любое количество медиафайлов, для каждого из которых можно назначить любое количество анализов. Анализы также могут назначаться для нескольких медиафайлов сразу.

Типы медиафайлов и теги

Oz API работает и с фото-, и с видеофайлами. Видео при этом может быть как файлом в «обычном» понимании, то есть контейнером в формате MP4 или MOV, так и последовательностью кадров в ZIP-архиве. Чтобы определить тип медиафайла, Oz API использует MIME-тип файла.

Кроме типа файла, важно также понимать, что именно запечатлено на фото или видео: например, это может быть фотография лицевой стороны документа или селфи-видео, снятое человеком. Для описания содержания фото или видео используются теги, и на основе этих тегов система решает, какие анализы будут назначены для того или иного медиафайла. Наиболее часто используемые теги:

• photo_id_front – для лицевой стороны документа

• photo_selfie – для референтного фото, не являющегося документом

• video_selfie_blank – для Liveness-видео, снятого не средствами Oz Liveness SDK

• если фото или видео снято средствами нашего SDK, теги выставляются автоматически

Асинхронные анализы

Поскольку анализ видео может занять несколько секунд, анализы проводятся асинхронно. Сначала вы запускаете анализ (POST /api/folders/{{folder_id}}/analyses/), а затем следите за результатами, периодически запрашивая их с сервера, пока обработка не закончится (GET /api/analyses/{{analyse_id}} для определенного анализа или GET /api/folders/{{folder_id}}/analyses/ для всех анализов, назначенных на папку). Кроме того, можно использовать вебхуки. С примером опроса и использования вебхука можно ознакомиться здесь.

Более детальная информация о возможностях Oz API содержится в соответствующей секции нашего руководства разработчика.