Liveness Session Operations - Create Liveness Session

Служба:
Azure AI Services
Версия API:
v1.2

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

Разрешения включают...

    • Время существования токена составляет 10 минут.

Note

Доступ к клиенту можно отменить, удалив сеанс с помощью операции удаления сеанса Liveness. Чтобы получить результат, используйте сеанс Get Liveness. Чтобы проверить отдельные запросы, внесенные клиентом в ресурс, используйте записи аудита сеанса liveness списка.

POST {endpoint}/face/{apiVersion}/detectLiveness-sessions

Параметры URI

Имя В Обязательно Тип Описание
apiVersion
 path True

string

Версия API
endpoint
 path True

string (uri)

Поддерживаемые конечные точки Cognitive Services (протокол и имя узла, например https://{имя ресурса}.cognitiveservices.azure.com).

Текст запроса

Имя Обязательно Тип Описание
livenessOperationMode True

LivenessOperationMode

Тип режима активности, который должен следовать клиенту.
authTokenTimeToLiveInSeconds

integer (int32)

minimum: 60
maximum: 86400

Секунды сеанса должны длиться в течение. Диапазон составляет от 60 до 86400 секунд. Значение по умолчанию — 600.
deviceCorrelationId

string

Уникальный guid для каждого устройства конечного пользователя. Это обеспечивает ограничение скорости и анти-молоток. Если параметр deviceCorrelationIdSetInClient имеет значение true в этом запросе, этот параметр deviceCorrelationId должен иметь значение NULL.
deviceCorrelationIdSetInClient

boolean

Следует ли разрешить клиенту устанавливать собственный deviceCorrelationId с помощью пакета SDK для визуального распознавания. Значение по умолчанию равно false, и в тексте запроса должен быть задан параметр deviceCorrelationId.
enableSessionImage

boolean

Независимо от того, хранится ли образ сеанса.
livenessModelVersion

LivenessModel

Версия модели, используемая для классификации активности. Это необязательный параметр, и если это не указано, будет выбрана последняя поддерживаемая версия модели.

Ответы

Имя Тип Описание
200 OK

LivenessSession

Успешный вызов создает сеанс для клиентского устройства и предоставляет маркер авторизации для использования клиентским приложением для ограниченной цели и времени.
Other Status Codes

FaceErrorResponse

Непредвиденное сообщение об ошибке.

Заголовки

x-ms-error-code: string

Безопасность

Ocp-Apim-Subscription-Key

Секретный ключ для подписки Azure AI Face.

Тип: apiKey
В: header

AADToken

Поток OAuth2 Azure Active Directory

Тип: oauth2
Flow: accessCode
URL-адрес авторизации: https://api.example.com/oauth2/authorize
URL-адрес токена: https://api.example.com/oauth2/token

Области

Имя Описание
https://cognitiveservices.azure.com/.default

Примеры

Create Liveness Session

Образец запроса

POST {endpoint}/face/v1.2/detectLiveness-sessions

{
  "livenessOperationMode": "Passive",
  "deviceCorrelationIdSetInClient": false,
  "deviceCorrelationId": "your_device_correlation_id",
  "authTokenTimeToLiveInSeconds": 60
}

Пример ответа

Код состояния:
200 
{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": []
  }
}

Определения

Имя Описание
CreateLivenessSessionContent

Модель запроса для создания сеанса активности.
FaceError

Объект ошибки. Подробные сведения о кодах ошибок и сообщениях, возвращаемых службой распознавания лиц, см. по следующей ссылке: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse

Ответ, содержащий сведения об ошибке.
FaceRectangle

Прямоугольник, в котором можно найти лицо.
LivenessColorDecisionTarget

Целевой объект из цветового изображения, используемого для классификации активности.
LivenessDecision

Результат классификации активности.
LivenessDecisionTargets

Целевые объекты, используемые для классификации активности.
LivenessError

Ошибка классификации активности.
LivenessModel

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

Режим работы с динамической жизнью для обеспечения взаимодействия с конечным пользователем клиента.
LivenessResult

Результаты классификации активности.
LivenessSession

Результат сеанса обнаружения активности.
LivenessSessionAttempt

Попытка сеанса активности.
LivenessSessionResults

Результаты сеанса активности.
OperationState

Текущее состояние сеанса.

CreateLivenessSessionContent

Object

Модель запроса для создания сеанса активности.

Имя Тип Default value Описание
authTokenTimeToLiveInSeconds

integer (int32)

minimum: 60
maximum: 86400 		600

Секунды сеанса должны длиться в течение. Диапазон составляет от 60 до 86400 секунд. Значение по умолчанию — 600.
deviceCorrelationId

string

Уникальный guid для каждого устройства конечного пользователя. Это обеспечивает ограничение скорости и анти-молоток. Если параметр deviceCorrelationIdSetInClient имеет значение true в этом запросе, этот параметр deviceCorrelationId должен иметь значение NULL.
deviceCorrelationIdSetInClient

boolean

Следует ли разрешить клиенту устанавливать собственный deviceCorrelationId с помощью пакета SDK для визуального распознавания. Значение по умолчанию равно false, и в тексте запроса должен быть задан параметр deviceCorrelationId.
enableSessionImage

boolean

Независимо от того, хранится ли образ сеанса.
livenessModelVersion

LivenessModel

Версия модели, используемая для классификации активности. Это необязательный параметр, и если это не указано, будет выбрана последняя поддерживаемая версия модели.
livenessOperationMode

LivenessOperationMode

Тип режима активности, который должен следовать клиенту.

FaceError

Object

Объект ошибки. Подробные сведения о кодах ошибок и сообщениях, возвращаемых службой распознавания лиц, см. по следующей ссылке: https://aka.ms/face-error-codes-and-messages.

Имя Тип Описание
code

string

Один из определяемых сервером кодов ошибок.
message

string

Читаемое пользователем представление ошибки.

FaceErrorResponse

Object

Ответ, содержащий сведения об ошибке.

Имя Тип Описание
error

FaceError

Объект ошибки.

FaceRectangle

Object

Прямоугольник, в котором можно найти лицо.

Имя Тип Описание
height

integer (int32)

Высота прямоугольника в пикселях.
left

integer (int32)

Расстояние от левого края, если изображение до левого края прямоугольника в пикселях.
top

integer (int32)

Расстояние от верхнего края, если изображение до верхнего края прямоугольника в пикселях.
width

integer (int32)

Ширина прямоугольника в пикселях.

LivenessColorDecisionTarget

Object

Целевой объект из цветового изображения, используемого для классификации активности.

Имя Тип Описание
faceRectangle

FaceRectangle

Область лица, на которой была сделана классификация активности.

LivenessDecision

Перечисление

Результат классификации активности.

Значение Описание
uncertain

Алгоритм не мог классифицировать целевое лицо как реальное или спуофное.
realface

Алгоритм классифицировал целевое лицо как реальное.
spoofface

Алгоритм классифицировал целевое лицо как спуф.

LivenessDecisionTargets

Object

Целевые объекты, используемые для классификации активности.

Имя Тип Описание
color

LivenessColorDecisionTarget

Целевой объект из цветового изображения, используемого для классификации активности.

LivenessError

Object

Ошибка классификации активности.

Имя Тип Описание
code

string

Код ошибки.
message

string

Сообщение об ошибке.
targets

LivenessDecisionTargets

Целевые объекты, используемые для классификации активности.

LivenessModel

Перечисление

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

Значение Описание
2024-11-15

LivenessOperationMode

Перечисление

Режим работы с динамической жизнью для обеспечения взаимодействия с конечным пользователем клиента.

Значение Описание
Passive

Использует метод пассивной активности, который не требует дополнительных действий от пользователя. Требует нормального освещения помещений и высокой яркости экрана для оптимальной производительности. Таким образом, этот режим имеет узкий операционный конверт и не подходит для сценариев, требующих, чтобы конечный пользователь был в условиях яркого освещения. Примечание. Это единственный поддерживаемый режим для решения Mobile (iOS и Android).
PassiveActive

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

LivenessResult

Object

Результаты классификации активности.

Имя Тип Описание
digest

string

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

LivenessDecision

Классификация активности для целевого лица.
sessionImageId

string

Идентификатор изображения запроса сеанса.
targets

LivenessDecisionTargets

Целевые объекты, используемые для классификации активности.

LivenessSession

Object

Результат сеанса обнаружения активности.

Имя Тип Описание
authToken

string

Маркер носителя для проверки подлинности пакета SDK для визуального распознавания, запущенного в клиентском приложении. Этот маркер носителя имеет ограниченные разрешения для выполнения только необходимых действий и истекает после времени TTL. Он также доступен для аудита.
modelVersion

LivenessModel

Версия модели, используемая для классификации активности. Это необязательный параметр, и если это не указано, будет выбрана последняя поддерживаемая версия модели.
results

LivenessSessionResults

Результаты сеанса активности.
sessionId

string

Уникальный идентификатор для ссылки на этот сеанс.
status

OperationState

Текущее состояние сеанса.

LivenessSessionAttempt

Object

Попытка сеанса активности.

Имя Тип Описание
attemptId

integer (int32)

Идентификатор попытки, начиная с 1.
attemptStatus

OperationState

Состояние попытки.
error

LivenessError

Ошибка вызова динамической активности будет иметь значение NULL, если есть результат.
result

LivenessResult

Результат вызова динамической активности будет иметь значение NULL, если возникает ошибка.

LivenessSessionResults

Object

Результаты сеанса активности.

Имя Тип Описание
attempts

LivenessSessionAttempt[]

Попытки данных базового вызова активности с сеансом.

OperationState

Перечисление

Текущее состояние сеанса.

Значение Описание
NotStarted

Операция не запущена.
Running

Операция выполняется.
Succeeded

Операция успешно завершена.
Failed

Операция завершилась ошибкой.
Canceled

Операция отменена пользователем.