Liveness Session Operations - Create Liveness With Verify Session

Riferimento

Servizio:: Azure AI Services

Versione API:: v1.2-preview.1

Creare una nuova sessione di liveness con verifica. Il dispositivo client invia VerifyImage durante la chiamata /detectLivenessWithVerify/singleModal.
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 /detectLivenessWithVerify/singleModal per un massimo di 3 tentativi.
- Durata del token di 10 minuti.

Nota

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

Opzione alternativa: il dispositivo client invia VerifyImage durante la chiamata /detectLivenessWithVerify/singleModal.

Nota

È necessario adottare misure aggiuntive per verificare che il client invii l'oggetto VerifyImage previsto.

POST {endpoint}/face/{apiVersion}/detectLivenessWithVerify/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
returnVerifyImageHash		boolean	Indica se restituire o meno l'hash dell'immagine di verifica.
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.
verifyConfidenceThreshold		number	Soglia di attendibilità della verifica del viso.

Risposte

Nome	Tipo	Descrizione
200 OK	CreateLivenessWithVerifySessionResult	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

Nome

Tipo

Descrizione

200 OK

CreateLivenessWithVerifySessionResult

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 LivenessWithVerify Session

Esempio di richiesta

HTTP

POST {endpoint}/face/v1.2-preview.1/detectLivenessWithVerify/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
CreateLivenessWithVerifySessionJsonContent	Richiesta di creazione di attività con la sessione di verifica.
CreateLivenessWithVerifySessionResult	Risposta della sessione di liveness con verifica della creazione con la verifica dell'immagine fornita.
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.
FaceRectangle	Rettangolo all'interno del quale è possibile trovare un viso.
LivenessModel	Versione del modello usata per la classificazione del liveness.
LivenessOperationMode	Modalità operativa di attività per guidare l'esperienza dell'utente finale del client.
LivenessWithVerifyImage	Dettaglio del viso per la verifica.
QualityForRecognition	Indica la qualità dell'immagine per il riconoscimento.

CreateLivenessWithVerifySessionJsonContent

Richiesta di creazione di attività con la sessione di verifica.

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
returnVerifyImageHash	boolean		Indica se restituire o meno l'hash dell'immagine di verifica.
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.
verifyConfidenceThreshold	number		Soglia di attendibilità della verifica del viso.

CreateLivenessWithVerifySessionResult

Risposta della sessione di liveness con verifica della creazione con la verifica dell'immagine fornita.

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.
verifyImage	LivenessWithVerifyImage	Dettaglio del viso per la verifica.

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.

FaceRectangle

Rettangolo all'interno del quale è possibile trovare un viso.

Nome	Tipo	Descrizione
height	integer	Altezza del rettangolo, in pixel.
left	integer	Distanza dal bordo sinistro se l'immagine al bordo sinistro del rettangolo, in pixel.
top	integer	Distanza dal bordo superiore se l'immagine al bordo superiore del rettangolo, in pixel.
width	integer	Larghezza del rettangolo, in pixel.

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.

LivenessWithVerifyImage

Dettaglio del viso per la verifica.

Nome	Tipo	Descrizione
faceRectangle	FaceRectangle	Area del viso in cui è stata effettuata la classificazione dell'immagine di confronto.
qualityForRecognition	QualityForRecognition	Qualità dell'immagine del viso per il riconoscimento.

QualityForRecognition

Indica la qualità dell'immagine per il riconoscimento.

Nome	Tipo	Descrizione
high	string	Alta qualità.
low	string	Bassa qualità.
medium	string	Qualità media.

Condividi tramite

Liveness Session Operations - Create Liveness With Verify Session

Parametri dell'URI

Corpo della richiesta

Risposte

Sicurezza

Ocp-Apim-Subscription-Key

AADToken

Ambiti

Esempio

Create LivenessWithVerify Session

Esempio di richiesta

Risposta di esempio

Definizioni

CreateLivenessWithVerifySessionJsonContent

CreateLivenessWithVerifySessionResult

FaceError

FaceErrorResponse

FaceRectangle

LivenessModel

LivenessOperationMode

LivenessWithVerifyImage

QualityForRecognition

Risorse aggiuntive