Liveness Session Operations - Create Liveness Session

Servizio:

Azure AI Services

Versione API:

v1.2-preview.1

Creare una nuova sessione di rilevamento dell'attività.
Una sessione è ideale per gli scenari dei dispositivi client in cui gli sviluppatori vogliono autorizzare un dispositivo client a eseguire solo un rilevamento di attività senza concedere l'accesso completo alla risorsa. Le sessioni create hanno un periodo di vita limitato e autorizzano i client a eseguire l'azione desiderata prima della scadenza dell'accesso.

Le autorizzazioni includono...

• • Possibilità di chiamare /detectLiveness/singleModal per un massimo di 3 tentativi.
  • Durata del token di 10 minuti.

Nota

L'accesso client può essere revocato eliminando la sessione tramite l'operazione Delete Liveness Session. Per recuperare un risultato, usare la sessione Get Liveness. Per controllare le singole richieste effettuate da un client alla risorsa, usare le voci List Liveness Session Audit.

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

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
apiVersion	path	True	string	Versione API
endpoint	path	True	string uri	Endpoint di Servizi cognitivi supportati (protocollo e nome host, ad esempio: https://{nome-risorsa}.cognitiveservices.azure.com).

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
livenessOperationMode	True	LivenessOperationMode	Tipo di modalità di attività da seguire per il client.
authTokenTimeToLiveInSeconds		integer	Secondi per cui la sessione deve durare. L'intervallo è compreso tra 60 e 86400 secondi. Il valore predefinito è 600.
deviceCorrelationId		string	Guid univoco per ogni dispositivo dell'utente finale. Questo è quello di fornire limitazione della frequenza e anti-martello. Se 'deviceCorrelationIdSetInClient' è true in questa richiesta, questo 'deviceCorrelationId' deve essere null.
deviceCorrelationIdSetInClient		boolean	Indica se consentire al client di impostare il proprio "deviceCorrelationId" tramite Vision SDK. Il valore predefinito è false e 'deviceCorrelationId' deve essere impostato nel corpo della richiesta.
enableSessionImage		boolean	Indica se archiviare o meno l'immagine della sessione.
livenessSingleModalModel		LivenessModel	Versione del modello usata per la classificazione del liveness. Si tratta di un parametro facoltativo e, se non è specificato, verrà scelta la versione più recente del modello supportato
sendResultsToClient		boolean	Indica se consentire o meno l'invio di un corpo di risposta "200 - Operazione riuscita" al client, che può essere indesiderato per motivi di sicurezza. Il valore predefinito è false, i client riceveranno una risposta del corpo vuota '204 - NoContent'. Indipendentemente dalla selezione, la chiamata a Session GetResult conterrà sempre un corpo della risposta che consente l'implementazione della logica di business.

Risposte

Nome	Tipo	Descrizione
200 OK	CreateLivenessSessionResult	Una chiamata con esito positivo crea una sessione per un dispositivo client e fornisce un token di autorizzazione per l'uso da parte dell'applicazione client per uno scopo e un tempo limitati.
Other Status Codes	FaceErrorResponse	Risposta di errore imprevista. Intestazioni x-ms-error-code: string

Sicurezza

Ocp-Apim-Subscription-Key

Chiave privata per la sottoscrizione di Viso di Intelligenza artificiale di Azure.

Tipo: apiKey
In: header

AADToken

Flusso OAuth2 di Azure Active Directory

Tipo: oauth2
Flow: accessCode
URL di autorizzazione: https://api.example.com/oauth2/authorize
URL token: https://api.example.com/oauth2/token

Ambiti

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

Esempio

Create Liveness Session

Esempio di richiesta

HTTP

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

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

Risposta di esempio

Codice di stato:

200

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

Definizioni

Nome	Descrizione
CreateLivenessSessionContent	Modello di richiesta per la creazione di una sessione di attività.
CreateLivenessSessionResult	Risposta alla creazione della sessione di attività.
FaceError	Oggetto error. Per informazioni dettagliate sui codici di errore e i messaggi restituiti dal servizio Viso, vedere il collegamento seguente: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Risposta contenente i dettagli dell'errore.
LivenessModel	Versione del modello usata per la classificazione del liveness.
LivenessOperationMode	Modalità operativa di attività per guidare l'esperienza dell'utente finale del client.

CreateLivenessSessionContent

Modello di richiesta per la creazione di una sessione di attività.

Nome	Tipo	Valore predefinito	Descrizione
authTokenTimeToLiveInSeconds	integer	600	Secondi per cui la sessione deve durare. L'intervallo è compreso tra 60 e 86400 secondi. Il valore predefinito è 600.
deviceCorrelationId	string		Guid univoco per ogni dispositivo dell'utente finale. Questo è quello di fornire limitazione della frequenza e anti-martello. Se 'deviceCorrelationIdSetInClient' è true in questa richiesta, questo 'deviceCorrelationId' deve essere null.
deviceCorrelationIdSetInClient	boolean		Indica se consentire al client di impostare il proprio "deviceCorrelationId" tramite Vision SDK. Il valore predefinito è false e 'deviceCorrelationId' deve essere impostato nel corpo della richiesta.
enableSessionImage	boolean		Indica se archiviare o meno l'immagine della sessione.
livenessOperationMode	LivenessOperationMode		Tipo di modalità di attività da seguire per il client.
livenessSingleModalModel	LivenessModel		Versione del modello usata per la classificazione del liveness. Si tratta di un parametro facoltativo e, se non è specificato, verrà scelta la versione più recente del modello supportato
sendResultsToClient	boolean		Indica se consentire o meno l'invio di un corpo di risposta "200 - Operazione riuscita" al client, che può essere indesiderato per motivi di sicurezza. Il valore predefinito è false, i client riceveranno una risposta del corpo vuota '204 - NoContent'. Indipendentemente dalla selezione, la chiamata a Session GetResult conterrà sempre un corpo della risposta che consente l'implementazione della logica di business.

CreateLivenessSessionResult

Risposta alla creazione della sessione di attività.

Nome	Tipo	Descrizione
authToken	string	Token di connessione per fornire l'autenticazione per Vision SDK in esecuzione in un'applicazione client. Questo token di connessione dispone di autorizzazioni limitate per eseguire solo l'azione richiesta e scade dopo l'ora TTL. È anche controllabile.
sessionId	string	ID sessione univoco della sessione creata. Scadrà 48 ore dopo la creazione o potrebbe essere eliminato prima usando l'operazione session DELETE corrispondente.

FaceError

Oggetto error. Per informazioni dettagliate sui codici di errore e i messaggi restituiti dal servizio Viso, vedere il collegamento seguente: https://aka.ms/face-error-codes-and-messages.

Nome	Tipo	Descrizione
code	string	Uno di un set definito dal server di codici di errore.
message	string	Rappresentazione leggibile dell'errore.

FaceErrorResponse

Risposta contenente i dettagli dell'errore.

Nome	Tipo	Descrizione
error	FaceError	Oggetto error.

LivenessModel

Versione del modello usata per la classificazione del liveness.

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

LivenessOperationMode

Modalità operativa di attività per guidare l'esperienza dell'utente finale del client.

Nome	Tipo	Descrizione
Passive	string	Utilizza una tecnica di attività passiva che non richiede azioni aggiuntive dall'utente. Richiede la normale illuminazione interna e la luminosità elevata dello schermo per ottenere prestazioni ottimali. E quindi, questa modalità ha una busta operativa stretta e non sarà adatta per gli scenari che richiedono che l'utente finale sia in condizioni di illuminazione luminosa. Nota: questa è l'unica modalità supportata per la soluzione Mobile (iOS e Android).
PassiveActive	string	Questa modalità usa una tecnica ibrida di attività passiva o attiva che richiede la cooperazione dell'utente. È ottimizzato per richiedere il movimento attivo solo in condizioni di illuminazione non ottimali. A differenza della modalità passiva, questa modalità non ha restrizioni di illuminazione e quindi offre una busta operativa più ampia. Questa modalità è preferibile nelle soluzioni basate sul Web a causa della mancanza di controllo automatico della luminosità dello schermo disponibile nei browser che ostacola la busta operativa della modalità passiva su soluzioni basate sul Web.