Liveness Session Operations - Create Liveness With Verify Session

Servicio:

Azure AI Services

Versión de la API:

v1.2-preview.1

Cree una nueva sesión de ejecución con comprobación. El dispositivo cliente envía VerifyImage durante la llamada /detectLivenessWithVerify/singleModal.
Una sesión es mejor para escenarios de dispositivos cliente en los que los desarrolladores desean autorizar a un dispositivo cliente a realizar solo una detección de ejecución sin conceder acceso completo a su recurso. Las sesiones creadas tienen un período de vida limitado y solo autorizan a los clientes a realizar la acción deseada antes de que expire el acceso.

Los permisos incluyen...

• • Capacidad de llamar a /detectLivenessWithVerify/singleModal para un máximo de 3 reintentos.
  • Duración del token de 10 minutos.

Nota

• • El acceso de cliente se puede revocar mediante la eliminación de la sesión mediante la operación Eliminar ejecución con comprobación de sesión.
  • Para recuperar un resultado, use Get Liveness With Verify Session.
  • Para auditar las solicitudes individuales realizadas por un cliente al recurso, use las entradas List Liveness With Verify Session Audit Entries (Enumerar vida con comprobar la auditoría de sesión).

Opción alternativa: el dispositivo cliente envía VerifyImage durante la llamada /detectLivenessWithVerify/singleModal.

Nota

Se deben tomar medidas adicionales para validar que el cliente envía la propiedad VerifyImage esperada.

POST {endpoint}/face/{apiVersion}/detectLivenessWithVerify/singleModal/sessions

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
apiVersion	path	True	string	Versión de API
endpoint	path	True	string uri	Puntos de conexión de Cognitive Services admitidos (protocolo y nombre de host, por ejemplo: https://{resource-name}.cognitiveservices.azure.com).

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Description
livenessOperationMode	True	LivenessOperationMode	Tipo de modo de vida que debe seguir el cliente.
authTokenTimeToLiveInSeconds		integer	Segundos para los que debe durar la sesión. El intervalo es de 60 a 86400 segundos. El valor predeterminado es 600.
deviceCorrelationId		string	Guid único por cada dispositivo de usuario final. Esto es para proporcionar limitación de velocidad y anti-martillo. Si "deviceCorrelationIdSetInClient" es true en esta solicitud, "deviceCorrelationId" debe ser NULL.
deviceCorrelationIdSetInClient		boolean	Indica si se va a permitir que el cliente establezca su propio "deviceCorrelationId" mediante el SDK de Vision. El valor predeterminado es false y "deviceCorrelationId" debe establecerse en este cuerpo de la solicitud.
enableSessionImage		boolean	Indica si almacena o no la imagen de sesión.
livenessSingleModalModel		LivenessModel	Versión del modelo que se usa para la clasificación de vida. Se trata de un parámetro opcional y, si no se especifica, se elegirá la versión más reciente del modelo compatible.
returnVerifyImageHash		boolean	Indica si devuelve o no el hash de comprobación de la imagen.
sendResultsToClient		boolean	Indica si se va a permitir que el cuerpo de respuesta "200 - Correcto" se envíe al cliente, lo que puede no ser deseable por motivos de seguridad. El valor predeterminado es false, los clientes recibirán una respuesta de cuerpo vacío "204 - NoContent". Independientemente de la selección, la llamada a Session GetResult siempre contendrá un cuerpo de respuesta que permita implementar la lógica de negocios.
verifyConfidenceThreshold		number	Umbral de confianza de la comprobación facial.

Respuestas

Nombre	Tipo	Description
200 OK	CreateLivenessWithVerifySessionResult	Una llamada correcta crea una sesión para un dispositivo cliente y proporciona un token de autorización para que lo use la aplicación cliente con un propósito y un tiempo limitados.
Other Status Codes	FaceErrorResponse	Una respuesta de error inesperada. Encabezados x-ms-error-code: string

Seguridad

Ocp-Apim-Subscription-Key

Clave secreta de la suscripción de Azure AI Face.

Tipo: apiKey
En: header

AADToken

Flujo de OAuth2 de Azure Active Directory

Tipo: oauth2
Flujo: accessCode
Dirección URL de autorización: https://api.example.com/oauth2/authorize
Dirección URL del token: https://api.example.com/oauth2/token

Ámbitos

Nombre	Description
https://cognitiveservices.azure.com/.default

Ejemplos

Create LivenessWithVerify Session

Solicitud de ejemplo

HTTP

POST {endpoint}/face/v1.2-preview.1/detectLivenessWithVerify/singleModal/sessions

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

Respuesta de muestra

status code:

200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm"
}

Definiciones

Nombre	Description
CreateLivenessWithVerifySessionJsonContent	Solicitud de creación de liveness con verify session.
CreateLivenessWithVerifySessionResult	Respuesta de la sesión de ejecución con comprobación de la creación con la imagen de comprobación proporcionada.
FaceError	Objeto de error. Para obtener detalles completos sobre los códigos de error y los mensajes devueltos por face Service, consulte el vínculo siguiente: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Respuesta que contiene los detalles del error.
FaceRectangle	Rectángulo dentro del cual se puede encontrar una cara.
LivenessModel	Versión del modelo que se usa para la clasificación de vida.
LivenessOperationMode	Modo de operación de ejecución para impulsar la experiencia del usuario final del cliente.
LivenessWithVerifyImage	Detalle de la cara para la comprobación.
QualityForRecognition	Indica la calidad de la imagen para el reconocimiento.

CreateLivenessWithVerifySessionJsonContent

Solicitud de creación de liveness con verify session.

Nombre	Tipo	Valor predeterminado	Description
authTokenTimeToLiveInSeconds	integer	600	Segundos para los que debe durar la sesión. El intervalo es de 60 a 86400 segundos. El valor predeterminado es 600.
deviceCorrelationId	string		Guid único por cada dispositivo de usuario final. Esto es para proporcionar limitación de velocidad y anti-martillo. Si "deviceCorrelationIdSetInClient" es true en esta solicitud, "deviceCorrelationId" debe ser NULL.
deviceCorrelationIdSetInClient	boolean		Indica si se va a permitir que el cliente establezca su propio "deviceCorrelationId" mediante el SDK de Vision. El valor predeterminado es false y "deviceCorrelationId" debe establecerse en este cuerpo de la solicitud.
enableSessionImage	boolean		Indica si almacena o no la imagen de sesión.
livenessOperationMode	LivenessOperationMode		Tipo de modo de vida que debe seguir el cliente.
livenessSingleModalModel	LivenessModel		Versión del modelo que se usa para la clasificación de vida. Se trata de un parámetro opcional y, si no se especifica, se elegirá la versión más reciente del modelo compatible.
returnVerifyImageHash	boolean		Indica si devuelve o no el hash de comprobación de la imagen.
sendResultsToClient	boolean		Indica si se va a permitir que el cuerpo de respuesta "200 - Correcto" se envíe al cliente, lo que puede no ser deseable por motivos de seguridad. El valor predeterminado es false, los clientes recibirán una respuesta de cuerpo vacío "204 - NoContent". Independientemente de la selección, la llamada a Session GetResult siempre contendrá un cuerpo de respuesta que permita implementar la lógica de negocios.
verifyConfidenceThreshold	number		Umbral de confianza de la comprobación facial.

CreateLivenessWithVerifySessionResult

Respuesta de la sesión de ejecución con comprobación de la creación con la imagen de comprobación proporcionada.

Nombre	Tipo	Description
authToken	string	Token de portador para proporcionar autenticación para el SDK de Vision que se ejecuta en una aplicación cliente. Este token de portador tiene permisos limitados para realizar solo la acción necesaria y expira después del tiempo de TTL. También es auditable.
sessionId	string	Identificador de sesión único de la sesión creada. Expirará 48 horas después de que se creó o se puede eliminar antes mediante la operación delete de sesión correspondiente.
verifyImage	LivenessWithVerifyImage	Detalle de la cara para la comprobación.

FaceError

Objeto de error. Para obtener detalles completos sobre los códigos de error y los mensajes devueltos por face Service, consulte el vínculo siguiente: https://aka.ms/face-error-codes-and-messages.

Nombre	Tipo	Description
code	string	Uno de un conjunto definido por el servidor de códigos de error.
message	string	Representación legible del error.

FaceErrorResponse

Respuesta que contiene los detalles del error.

Nombre	Tipo	Description
error	FaceError	Objeto de error.

FaceRectangle

Rectángulo dentro del cual se puede encontrar una cara.

Nombre	Tipo	Description
height	integer	Alto del rectángulo, en píxeles.
left	integer	Distancia desde el borde izquierdo si la imagen al borde izquierdo del rectángulo, en píxeles.
top	integer	Distancia desde el borde superior si la imagen hasta el borde superior del rectángulo, en píxeles.
width	integer	Ancho del rectángulo, en píxeles.

LivenessModel

Versión del modelo que se usa para la clasificación de vida.

Nombre	Tipo	Description
2022-10-15-preview.04	string
2023-12-20-preview.06	string

LivenessOperationMode

Modo de operación de ejecución para impulsar la experiencia del usuario final del cliente.

Nombre	Tipo	Description
Passive	string	Utiliza una técnica de vida pasiva que no requiere acciones adicionales del usuario. Requiere iluminación interior normal y brillo de pantalla alta para un rendimiento óptimo. Por lo tanto, este modo tiene un sobre operativo estrecho y no será adecuado para escenarios que requieren que el usuario final esté en condiciones de iluminación brillantes. Nota: este es el único modo admitido para la solución Mobile (iOS y Android).
PassiveActive	string	Este modo utiliza una técnica de vida activa o pasiva híbrida que requiere la cooperación del usuario. Está optimizado para requerir movimiento activo solo bajo condiciones de iluminación poco óptimas. A diferencia del modo pasivo, este modo no tiene restricciones de iluminación y, por tanto, ofrece un sobre operativo más amplio. Este modo es preferible en soluciones basadas en Web debido a la falta de control automático de brillo de pantalla disponible en exploradores que dificultan el sobre operativo del modo pasivo en soluciones basadas en Web.

LivenessWithVerifyImage

Detalle de la cara para la comprobación.

Nombre	Tipo	Description
faceRectangle	FaceRectangle	Región facial en la que se realizó la clasificación de la imagen de comparación.
qualityForRecognition	QualityForRecognition	Calidad de la imagen facial para el reconocimiento.

QualityForRecognition

Indica la calidad de la imagen para el reconocimiento.

Nombre	Tipo	Description
high	string	Alta calidad.
low	string	Baja calidad.
medium	string	Calidad media.