Liveness Session Operations - Create Liveness With Verify Session

Referência

Serviço:: Azure AI Services

Versão da API:: v1.2-preview.1

Crie uma nova sessão de dinâmica com verificação. O dispositivo cliente envia VerifyImage durante a chamada /detectLivenessWithVerify/singleModal.
Uma sessão é melhor para cenários de dispositivo cliente em que os desenvolvedores desejam autorizar um dispositivo cliente a executar apenas uma detecção de atividade sem conceder acesso total ao recurso. As sessões criadas têm um tempo de vida limitado e só autorizam os clientes a executar a ação desejada antes que o acesso expire.

As permissões incluem...

- Capacidade de chamar /detectLivenessWithVerify/singleModal para até três tentativas.
- Um tempo de vida do token de 10 minutos.

Nota

- O acesso ao cliente pode ser revogado excluindo a sessão usando a operação Excluir Liveness With Verify Session.
- Para recuperar um resultado, use a sessão Get Liveness With Verify.
- Para auditar as solicitações individuais feitas por um cliente ao seu recurso, use o Modo de Vida da Lista com As Entradas de Auditoria de Sessão de Verificação.

Opção alternativa: o dispositivo cliente envia VerifyImage durante a chamada /detectLivenessWithVerify/singleModal.

Nota

Medidas extras devem ser tomadas para validar que o cliente está enviando o VerifyImage esperado.

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

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
apiVersion	path	True	string	Versão da API
endpoint	path	True	string uri	Pontos de extremidade dos Serviços Cognitivos com suporte (protocolo e nome do host, por exemplo: https://{resource-name}.cognitiveservices.azure.com).

Corpo da solicitação

Nome	Obrigatório	Tipo	Description
livenessOperationMode	True	LivenessOperationMode	Tipo de modo de vida que o cliente deve seguir.
authTokenTimeToLiveInSeconds		integer	Segundos para os quais a sessão deve durar. O intervalo é de 60 a 86400 segundos. O valor padrão é 600.
deviceCorrelationId		string	Guid exclusivo por cada dispositivo de usuário final. Isso é para fornecer limitação de taxa e anti-martelada. Se 'deviceCorrelationIdSetInClient' for verdadeiro nesta solicitação, essa 'deviceCorrelationId' deverá ser nula.
deviceCorrelationIdSetInClient		boolean	Se o cliente deve ou não permitir que o cliente defina sua própria 'deviceCorrelationId' por meio do SDK de Visão. O padrão é false e 'deviceCorrelationId' deve ser definido nesse corpo da solicitação.
enableSessionImage		boolean	Armazenar ou não a imagem da sessão.
livenessSingleModalModel		LivenessModel	A versão do modelo usada para a classificação de dinâmica. Esse é um parâmetro opcional e, se isso não for especificado, a versão mais recente do modelo com suporte será escolhida
returnVerifyImageHash		boolean	Se retorna ou não o hash da imagem de verificação.
sendResultsToClient		boolean	Se deseja ou não permitir que um corpo de resposta '200 – Êxito' seja enviado ao cliente, o que pode ser indesejável por motivos de segurança. O padrão é false, os clientes receberão uma resposta de corpo vazia '204 – NoContent'. Independentemente da seleção, chamar o Session GetResult sempre conterá um corpo de resposta que permite que a lógica de negócios seja implementada.
verifyConfidenceThreshold		number	Limite de confiança da verificação facial.

Respostas

Nome	Tipo	Description
200 OK	CreateLivenessWithVerifySessionResult	Uma chamada bem-sucedida cria uma sessão para um dispositivo cliente e fornece um token de autorização para uso pelo aplicativo cliente para uma finalidade e tempo limitados.
Other Status Codes	FaceErrorResponse	Uma resposta de erro inesperada. Cabeçalhos x-ms-error-code: string

Nome

Tipo

Description

200 OK

CreateLivenessWithVerifySessionResult

Uma chamada bem-sucedida cria uma sessão para um dispositivo cliente e fornece um token de autorização para uso pelo aplicativo cliente para uma finalidade e tempo limitados.

Other Status Codes

FaceErrorResponse

Uma resposta de erro inesperada.

Cabeçalhos

x-ms-error-code: string

Segurança

Ocp-Apim-Subscription-Key

A chave secreta para sua assinatura do Azure AI Face.

Tipo: apiKey
Em: header

AADToken

O fluxo OAuth2 do Azure Active Directory

Tipo: oauth2
Flow: accessCode
URL de Autorização: https://api.example.com/oauth2/authorize
URL do Token: https://api.example.com/oauth2/token

Escopos

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

Exemplos

Create LivenessWithVerify Session

Solicitação de exemplo

HTTP

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

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

Resposta de exemplo

Código de status:: 200

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

Definições

Nome	Description
CreateLivenessWithVerifySessionJsonContent	Solicitação para criar a dinâmica com a sessão de verificação.
CreateLivenessWithVerifySessionResult	Resposta da sessão de atividade com verificação da criação com a imagem de verificação fornecida.
FaceError	O objeto de erro. Para obter detalhes abrangentes sobre códigos de erro e mensagens retornadas pelo Serviço de Detecção Facial, consulte o seguinte link: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Uma resposta que contém detalhes do erro.
FaceRectangle	Um retângulo no qual um rosto pode ser encontrado.
LivenessModel	A versão do modelo usada para a classificação de dinâmica.
LivenessOperationMode	O modo de operação de atividade para conduzir a experiência do usuário final do cliente.
LivenessWithVerifyImage	O detalhe da face para verificação.
QualityForRecognition	Indica a qualidade da imagem para reconhecimento.

CreateLivenessWithVerifySessionJsonContent

Solicitação para criar a dinâmica com a sessão de verificação.

Nome	Tipo	Valor padrão	Description
authTokenTimeToLiveInSeconds	integer	600	Segundos para os quais a sessão deve durar. O intervalo é de 60 a 86400 segundos. O valor padrão é 600.
deviceCorrelationId	string		Guid exclusivo por cada dispositivo de usuário final. Isso é para fornecer limitação de taxa e anti-martelada. Se 'deviceCorrelationIdSetInClient' for verdadeiro nesta solicitação, essa 'deviceCorrelationId' deverá ser nula.
deviceCorrelationIdSetInClient	boolean		Se o cliente deve ou não permitir que o cliente defina sua própria 'deviceCorrelationId' por meio do SDK de Visão. O padrão é false e 'deviceCorrelationId' deve ser definido nesse corpo da solicitação.
enableSessionImage	boolean		Armazenar ou não a imagem da sessão.
livenessOperationMode	LivenessOperationMode		Tipo de modo de vida que o cliente deve seguir.
livenessSingleModalModel	LivenessModel		A versão do modelo usada para a classificação de dinâmica. Esse é um parâmetro opcional e, se isso não for especificado, a versão mais recente do modelo com suporte será escolhida
returnVerifyImageHash	boolean		Se retorna ou não o hash da imagem de verificação.
sendResultsToClient	boolean		Se deseja ou não permitir que um corpo de resposta '200 – Êxito' seja enviado ao cliente, o que pode ser indesejável por motivos de segurança. O padrão é false, os clientes receberão uma resposta de corpo vazia '204 – NoContent'. Independentemente da seleção, chamar o Session GetResult sempre conterá um corpo de resposta que permite que a lógica de negócios seja implementada.
verifyConfidenceThreshold	number		Limite de confiança da verificação facial.

CreateLivenessWithVerifySessionResult

Resposta da sessão de atividade com verificação da criação com a imagem de verificação fornecida.

Nome	Tipo	Description
authToken	string	Token de portador para fornecer autenticação para o SDK da Visão em execução em um aplicativo cliente. Esse token de portador tem permissões limitadas para executar apenas a ação necessária e expira após a hora TTL. Também é auditável.
sessionId	string	A ID de sessão exclusiva da sessão criada. Ele expirará 48 horas depois de ter sido criado ou poderá ser excluído mais cedo usando a operação DELETE de sessão correspondente.
verifyImage	LivenessWithVerifyImage	O detalhe da face para verificação.

FaceError

O objeto de erro. Para obter detalhes abrangentes sobre códigos de erro e mensagens retornadas pelo Serviço de Detecção Facial, consulte o seguinte link: https://aka.ms/face-error-codes-and-messages.

Nome	Tipo	Description
code	string	Um de um conjunto definido pelo servidor de códigos de erro.
message	string	Uma representação legível pelo ser humano do erro.

FaceErrorResponse

Uma resposta que contém detalhes do erro.

Nome	Tipo	Description
error	FaceError	O objeto de erro.

FaceRectangle

Um retângulo no qual um rosto pode ser encontrado.

Nome	Tipo	Description
height	integer	A altura do retângulo, em pixels.
left	integer	A distância da borda esquerda se a imagem até a borda esquerda do retângulo, em pixels.
top	integer	A distância da borda superior se a imagem até a borda superior do retângulo, em pixels.
width	integer	A largura do retângulo, em pixels.

LivenessModel

A versão do modelo usada para a classificação de dinâmica.

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

LivenessOperationMode

O modo de operação de atividade para conduzir a experiência do usuário final do cliente.

Nome	Tipo	Description
Passive	string	Utiliza uma técnica de vida passiva que não requer ações adicionais do usuário. Requer iluminação interna normal e brilho de tela alta para um desempenho ideal. Portanto, esse modo tem um envelope operacional estreito e não será adequado para cenários que exigem que os usuários finais estejam em condições de iluminação brilhantes. Observação: este é o único modo com suporte para a solução Móvel (iOS e Android).
PassiveActive	string	Esse modo utiliza uma técnica de vida ativa ou passiva híbrida que exige a cooperação do usuário. Ele é otimizado para exigir movimento ativo apenas em condições de iluminação abaixo do ideal. Ao contrário do modo passivo, esse modo não tem restrições de iluminação e, portanto, oferece um envelope operacional mais amplo. Esse modo é preferível em soluções baseadas na Web devido à falta de controle automático de brilho de tela disponível em navegadores, o que dificulta o envelope operacional do modo passivo em soluções baseadas na Web.

LivenessWithVerifyImage

O detalhe da face para verificação.

Nome	Tipo	Description
faceRectangle	FaceRectangle	A região do rosto em que a classificação da imagem de comparação foi feita.
qualityForRecognition	QualityForRecognition	Qualidade da imagem facial para reconhecimento.

QualityForRecognition

Indica a qualidade da imagem para reconhecimento.

Nome	Tipo	Description
high	string	Alta qualidade.
low	string	Baixa qualidade.
medium	string	Qualidade média.

Compartilhar via

Liveness Session Operations - Create Liveness With Verify Session

Parâmetros de URI

Corpo da solicitação

Respostas

Segurança

Ocp-Apim-Subscription-Key

AADToken

Escopos

Exemplos

Create LivenessWithVerify Session

Solicitação de exemplo

Resposta de exemplo

Definições

CreateLivenessWithVerifySessionJsonContent

CreateLivenessWithVerifySessionResult

FaceError

FaceErrorResponse

FaceRectangle

LivenessModel

LivenessOperationMode

LivenessWithVerifyImage

QualityForRecognition

Recursos adicionais