Liveness Session Operations - Create Liveness Session

Serviço:

Azure AI Services

Versão da API:

v1.2-preview.1

Crie uma nova sessão de deteção de liveness.
Uma sessão é melhor para cenários de dispositivo cliente em que os desenvolvedores desejam autorizar um dispositivo cliente a executar apenas uma deteção de vivacidade sem conceder acesso total ao recurso. As sessões criadas têm uma vida útil limitada e só autorizam os clientes a executar a ação desejada antes que o acesso expire.

As permissões incluem...

• • Capacidade de chamar /detectLiveness/singleModal para até 3 tentativas.
  • Uma vida útil do token de 10 minutos.

Observação

O acesso do cliente pode ser revogado excluindo a sessão usando a operação Excluir sessão de vivacidade. Para recuperar um resultado, use a sessão Get Liveness. Para auditar as solicitações individuais que um cliente fez ao seu recurso, use Listar entradas de auditoria da sessão Liveness.

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

Parâmetros do URI

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

Corpo do Pedido

Name	Necessário	Tipo	Description
livenessOperationMode	True	LivenessOperationMode	Tipo de modo de vivacidade que o cliente deve seguir.
authTokenTimeToLiveInSeconds		integer	Segundos a sessão deve durar. O alcance é de 60 a 86400 segundos. O valor padrão é 600.
deviceCorrelationId		string	GUID exclusivo para cada dispositivo do usuário final. Isto é para fornecer limitação de taxa e anti-martelo. Se 'deviceCorrelationIdSetInClient' for true nesta solicitação, esse 'deviceCorrelationId' deverá ser null.
deviceCorrelationIdSetInClient		boolean	Se deve ou não permitir que o cliente defina seu próprio 'deviceCorrelationId' através do Vision SDK. O padrão é false, e 'deviceCorrelationId' deve ser definido neste corpo de solicitação.
enableSessionImage		boolean	Se armazena ou não a imagem da sessão.
livenessSingleModalModel		LivenessModel	A versão do modelo utilizada para a classificação da vivacidade. Este é um parâmetro opcional e, se não for especificado, será escolhida a versão mais recente do modelo suportado
sendResultsToClient		boolean	Permitir ou não o envio de um organismo de resposta "200 - Sucesso" ao cliente, o que pode ser indesejável por razões de segurança. O padrão é false, os clientes receberão uma resposta de corpo vazio '204 - NoContent'. Independentemente da seleção, chamar Session GetResult sempre conterá um corpo de resposta permitindo que a lógica de negócios seja implementada.

Respostas

Name	Tipo	Description
200 OK	CreateLivenessSessionResult	Uma chamada bem-sucedida cria uma sessão para um dispositivo cliente e fornece um token de autorização para uso pelo aplicativo cliente por um propósito 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 Ative Directory

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

Âmbitos

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

Exemplos

Create Liveness Session

Pedido de amostra

HTTP

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

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

Resposta da amostra

Código de estado:

200

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

Definições

Name	Description
CreateLivenessSessionContent	Modelo de solicitação para criação de sessão de liveness.
CreateLivenessSessionResult	Resposta de criação de sessão de liveness.
FaceError	O objeto de erro. Para obter detalhes abrangentes sobre códigos de erro e mensagens retornadas pelo Face Service, consulte o seguinte link: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Uma resposta contendo detalhes do erro.
LivenessModel	A versão do modelo utilizada para a classificação da vivacidade.
LivenessOperationMode	O modo de operação liveness para impulsionar a experiência do usuário final do cliente.

CreateLivenessSessionContent

Modelo de solicitação para criação de sessão de liveness.

Name	Tipo	Default value	Description
authTokenTimeToLiveInSeconds	integer	600	Segundos a sessão deve durar. O alcance é de 60 a 86400 segundos. O valor padrão é 600.
deviceCorrelationId	string		GUID exclusivo para cada dispositivo do usuário final. Isto é para fornecer limitação de taxa e anti-martelo. Se 'deviceCorrelationIdSetInClient' for true nesta solicitação, esse 'deviceCorrelationId' deverá ser null.
deviceCorrelationIdSetInClient	boolean		Se deve ou não permitir que o cliente defina seu próprio 'deviceCorrelationId' através do Vision SDK. O padrão é false, e 'deviceCorrelationId' deve ser definido neste corpo de solicitação.
enableSessionImage	boolean		Se armazena ou não a imagem da sessão.
livenessOperationMode	LivenessOperationMode		Tipo de modo de vivacidade que o cliente deve seguir.
livenessSingleModalModel	LivenessModel		A versão do modelo utilizada para a classificação da vivacidade. Este é um parâmetro opcional e, se não for especificado, será escolhida a versão mais recente do modelo suportado
sendResultsToClient	boolean		Permitir ou não o envio de um organismo de resposta "200 - Sucesso" ao cliente, o que pode ser indesejável por razões de segurança. O padrão é false, os clientes receberão uma resposta de corpo vazio '204 - NoContent'. Independentemente da seleção, chamar Session GetResult sempre conterá um corpo de resposta permitindo que a lógica de negócios seja implementada.

CreateLivenessSessionResult

Resposta de criação de sessão de liveness.

Name	Tipo	Description
authToken	string	Token de portador para fornecer autenticação para o Vision SDK em execução em um aplicativo cliente. Este token ao portador tem permissões limitadas para executar apenas a ação necessária e expira após o tempo TTL. Também é auditável.
sessionId	string	O ID de sessão exclusivo da sessão criada. Ele expirará 48 horas após ter sido criado ou poderá ser excluído mais cedo usando a operação DELETE de sessão correspondente.

FaceError

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

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

FaceErrorResponse

Uma resposta contendo detalhes do erro.

Name	Tipo	Description
error	FaceError	O objeto de erro.

LivenessModel

A versão do modelo utilizada para a classificação da vivacidade.

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

LivenessOperationMode

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

Name	Tipo	Description
Passive	string	Utiliza uma técnica de vivacidade passiva que não requer ações adicionais do usuário. Requer iluminação interior normal e alto brilho do ecrã para um desempenho ideal. E, portanto, este modo tem um envelope operacional estreito e não será adequado para cenários que exijam que o utilizador final esteja em condições de iluminação brilhante. Nota: este é o único modo suportado para a solução Mobile (iOS e Android).
PassiveActive	string	Este modo utiliza uma técnica de vivacidade passiva ou ativa híbrida que requer 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, este modo não tem restrições de iluminação e, portanto, oferece um envelope operacional mais amplo. Este modo é preferível em soluções baseadas na Web devido à falta de controle automático de brilho da tela disponível nos navegadores, o que dificulta o envelope operacional do modo passivo em soluções baseadas na Web.