Compartilhar via

Liveness Session Operations - Create Liveness Session

  • Referência
Serviço:
Azure AI Services
Versão da API:
v1.2-preview.1

Crie uma nova sessão de detecção de vida útil.
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 /detectLiveness/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 Sessão de Atividade. Para recuperar um resultado, use a Sessão Get Liveness. Para auditar as solicitações individuais que um cliente fez ao seu recurso, use as Entradas de Auditoria de Sessão de Atividade de Lista.

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

Respostas

Nome 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 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 Liveness Session

Solicitação de exemplo

POST {endpoint}/face/v1.2-preview.1/detectLiveness/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
CreateLivenessSessionContent

Modelo de solicitação para criar sessão de dinâmica.
CreateLivenessSessionResult

Resposta da criação da sessão de atividade.
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.
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.

CreateLivenessSessionContent

Modelo de solicitação para criar sessão de dinâmica.

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

CreateLivenessSessionResult

Resposta da criação da sessão de atividade.

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.

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.

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.