Liveness Session Operations - Create Liveness Session

Servicio:

Azure AI Services

Versión de la API:

v1.2-preview.1

Cree una nueva sesión de detección de ejecución.
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 /detectLiveness/singleModal para hasta 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 sesión de ejecución. Para recuperar un resultado, use la sesión Get Liveness. Para auditar las solicitudes individuales realizadas por un cliente al recurso, use las entradas de auditoría de sesión de ejecución de lista.

POST {endpoint}/face/{apiVersion}/detectLiveness/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.
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.

Respuestas

Nombre	Tipo	Description
200 OK	CreateLivenessSessionResult	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 Liveness Session

Solicitud de ejemplo

HTTP

POST {endpoint}/face/v1.2-preview.1/detectLiveness/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
CreateLivenessSessionContent	Modelo de solicitud para crear una sesión de ejecución.
CreateLivenessSessionResult	Respuesta de la creación de sesiones de ejecució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.
FaceErrorResponse	Respuesta que contiene los detalles del error.
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.

CreateLivenessSessionContent

Modelo de solicitud para crear una sesión de ejecución.

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.
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.

CreateLivenessSessionResult

Respuesta de la creación de sesiones de ejecución.

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.

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.

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.