Liveness Session Operations - Create Liveness With Verify Session

Reference

Služba:: Azure AI Services

Verze rozhraní API:: v1.2

Vytvořte novou relaci živého života s ověřením. Zadejte obrázek ověření během vytváření relace.
Relace je nejvhodnější pro scénáře klientských zařízení, ve kterých chtějí vývojáři autorizovat klientské zařízení, aby provádělo detekci živé aktivity, aniž by udělili úplný přístup ke svému prostředku. Vytvořené relace mají omezenou životnost a autorizuje klienty pouze k provedení požadované akce před vypršením platnosti přístupu.

Oprávnění zahrnují...

- Schopnost volat /detectLivenessWithVerify/singleModal až pro 3 opakování.
- Životnost tokenu je 10 minut.

Poznámka

- Klientský přístup je možné odvolat odstraněním relace pomocí operace Odstranit liveness s ověřením relace.
- Pokud chcete načíst výsledek, použijte relaci Získat liveness s ověřením.
- Pokud chcete auditovat jednotlivé požadavky, které klient provedl pro váš prostředek, použijte položky auditu relace List Liveness with Verify Session.

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

Parametry identifikátoru URI

Name	V	Vyžadováno	Typ	Description
livenessOperationMode	formData	True	LivenessOperationMode	Typ režimu aktivity by měl klient postupovat.
verifyImage	formData	True	file	Stream obrázku pro ověření. Pole hlavičky Content-Disposition pro tuto část musí obsahovat název souboru.
authTokenTimeToLiveInSeconds	formData		integer int32	Sekundy, na které by měla relace trvat. Rozsah je 60 až 86400 sekund. Výchozí hodnota je 600.
deviceCorrelationId	formData		string	Jedinečný identifikátor GUID pro každé zařízení koncového uživatele. Jedná se o zajištění omezování rychlosti a proti kladivu. Pokud je v tomto požadavku hodnota deviceCorrelationIdSetInClient true, musí být hodnota deviceCorrelationId null.
deviceCorrelationIdSetInClient	formData		boolean	Bez ohledu na to, jestli chcete klientovi povolit, aby prostřednictvím sady Vision SDK nastavil vlastní 'deviceCorrelationId'. Výchozí hodnota je false a v tomto textu požadavku musí být nastavená hodnota deviceCorrelationId.
enableSessionImage	formData		boolean	Určuje, jestli image relace neukládáte nebo ne.
livenessModelVersion	formData		LivenessModel	Verze modelu používaná pro klasifikaci aktivity. Jedná se o volitelný parametr a pokud není zadaný, zvolí se nejnovější podporovaná verze modelu.
returnVerifyImageHash	formData		boolean	Zda nebo nevrací hodnotu hash obrázku pro ověření.
verifyConfidenceThreshold	formData		number float	Prahová hodnota pro jistotu ověření tváře. Další podrobnosti najdete v dokumentaci. https://learn.microsoft.com/legal/cognitive-services/face/characteristics-and-limitations?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#recognition-confidence-score
apiVersion	path	True	string	Verze rozhraní API
endpoint	path	True	string uri	Podporované koncové body služeb Cognitive Services (protokol a název hostitele, například: https://{název_prostředku}.cognitiveservices.azure.com).

Odpovědi

Name	Typ	Description
200 OK	LivenessWithVerifySession	Úspěšné volání vytvoří relaci pro klientské zařízení a poskytne autorizační token pro použití klientskou aplikací pro omezený účel a čas.
Other Status Codes	FaceErrorResponse	Neočekávaná chybová odpověď Hlavičky x-ms-error-code: string

Name

Typ

Description

200 OK

LivenessWithVerifySession

Úspěšné volání vytvoří relaci pro klientské zařízení a poskytne autorizační token pro použití klientskou aplikací pro omezený účel a čas.

Other Status Codes

FaceErrorResponse

Neočekávaná chybová odpověď

Hlavičky

x-ms-error-code: string

Zabezpečení

Ocp-Apim-Subscription-Key

Tajný klíč předplatného Azure AI Face.

Typ: apiKey
V: header

AADToken

Tok Azure Active Directory OAuth2

Typ: oauth2
Tok: accessCode
URL autorizace: https://api.example.com/oauth2/authorize
URL tokenu: https://api.example.com/oauth2/token

Rozsahy

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

Příklady

Create LivenessWithVerify Session

Ukázkový požadavek

HTTP

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

Ukázková odpověď

Stavový kód:: 200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": [],
    "verifyReferences": [
      {
        "referenceType": "image",
        "faceRectangle": {
          "top": 316,
          "left": 131,
          "width": 498,
          "height": 677
        },
        "qualityForRecognition": "high"
      }
    ]
  }
}

Definice

Name	Description
FaceError	Objekt chyby. Podrobné informace o kódech chyb a zprávách vrácených službou Rozpoznávání tváře najdete na následujícím odkazu: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Odpověď obsahující podrobnosti o chybě.
FaceRectangle	Obdélník, ve kterém lze najít tvář.
ImageType	Typ obrázku.
LivenessColorDecisionTarget	Cíl z barevného obrázku použitého pro klasifikaci živé aktivity.
LivenessDecision	Výsledek klasifikace aktivity.
LivenessDecisionTargets	Cíle používané pro klasifikaci aktivity.
LivenessError	Chyba klasifikace aktivity.
LivenessModel	Verze modelu používaná pro klasifikaci aktivity.
LivenessOperationMode	Režim operace liveness pro řízení prostředí koncového uživatele klienta.
LivenessWithVerifyOutputs	Výstup ověření tváře.
LivenessWithVerifyReference	Podrobnosti o tváři pro ověření.
LivenessWithVerifyResult	Výsledky živé aktivity s ověřením volání.
LivenessWithVerifySession	Výsledek relace detekce živé aktivity s ověřením
LivenessWithVerifySessionAttempt	Živost s pokusem o ověření relace.
LivenessWithVerifySessionResults	Výsledky živé relace s ověřením.
OperationState	Aktuální stav relace.
QualityForRecognition	Označuje kvalitu obrázku pro rozpoznávání.

FaceError

Objekt chyby. Podrobné informace o kódech chyb a zprávách vrácených službou Rozpoznávání tváře najdete na následujícím odkazu: https://aka.ms/face-error-codes-and-messages.

Name	Typ	Description
code	string	Jedna ze serverově definovaných kódů chyb.
message	string	Čitelné znázornění chyby člověkem.

FaceErrorResponse

Odpověď obsahující podrobnosti o chybě.

Name	Typ	Description
error	FaceError	Objekt chyby.

FaceRectangle

Obdélník, ve kterém lze najít tvář.

Name	Typ	Description
height	integer	Výška obdélníku v pixelech.
left	integer	Vzdálenost od levého okraje, pokud je obrázek na levém okraji obdélníku v pixelech.
top	integer	Vzdálenost od horního okraje, pokud je obrázek na horním okraji obdélníku v pixelech.
width	integer	Šířka obdélníku v pixelech.

ImageType

Typ obrázku.

Name	Typ	Description
Color	string	Barevný obrázek
Depth	string	Obrázek hloubky
Infrared	string	Infračervený obraz.

LivenessColorDecisionTarget

Cíl z barevného obrázku použitého pro klasifikaci živé aktivity.

Name	Typ	Description
faceRectangle	FaceRectangle	Oblast tváře, ve které byla klasifikace aktivity provedena.

LivenessDecision

Výsledek klasifikace aktivity.

Name	Typ	Description
realface	string	Algoritmus klasifikoval cílovou tvář jako skutečnou.
spoofface	string	Algoritmus klasifikoval cílovou tvář jako falšování identity.
uncertain	string	Algoritmus nemohl klasifikovat cílovou tvář jako skutečnou ani jako falšování identity.

LivenessDecisionTargets

Cíle používané pro klasifikaci aktivity.

Name	Typ	Description
color	LivenessColorDecisionTarget	Cíl z barevného obrázku použitého pro klasifikaci živé aktivity.

LivenessError

Chyba klasifikace aktivity.

Name	Typ	Description
code	string	Kód chyby.
message	string	Chybová zpráva.
targets	LivenessDecisionTargets	Cíle používané pro klasifikaci aktivity

LivenessModel

Verze modelu používaná pro klasifikaci aktivity.

Name	Typ	Description
2024-11-15	string

LivenessOperationMode

Režim operace liveness pro řízení prostředí koncového uživatele klienta.

Name	Typ	Description
Passive	string	Využívá pasivní techniku života, která nevyžaduje žádné další akce od uživatele. Vyžaduje normální vnitřní osvětlení a vysoký jas obrazovky pro optimální výkon. A proto má tento režim úzkou provozní obálku a nebude vhodný pro scénáře, které vyžadují, aby koncový uživatel byl v jasných světelných podmínkách. Poznámka: Toto je jediný podporovaný režim pro řešení Mobile (iOS a Android).
PassiveActive	string	Tento režim využívá hybridní pasivní nebo aktivní techniku života, která vyžaduje spolupráci uživatelů. Je optimalizovaná tak, aby vyžadovala aktivní pohyb pouze za neoptimálních světelných podmínek. Na rozdíl od pasivního režimu nemá tento režim žádná omezení osvětlení, a proto nabízí širší provozní obálku. Tento režim je vhodnější na webových řešeních kvůli nedostatku automatického ovládání jasu obrazovky dostupných v prohlížečích, které brání provozní obálce pasivního režimu na webových řešeních.

LivenessWithVerifyOutputs

Výstup ověření tváře.

Name	Typ	Description
isIdentical	boolean	Určuje, jestli cílová tvář naživotnost a porovnání odpovídá tváři obrázku.
matchConfidence	number	Míra spolehlivosti ověření tváře cílové tváře a porovnání obrázku ověření tváře.

LivenessWithVerifyReference

Podrobnosti o tváři pro ověření.

Name	Typ	Description
faceRectangle	FaceRectangle	Oblast tváře, ve které byla provedena klasifikace srovnávacího obrázku.
qualityForRecognition	QualityForRecognition	Kvalita obrázku tváře pro rozpoznávání.
referenceType	ImageType	Typ obrázku, který obsahuje obdélník tváře, na kterém byla provedena klasifikace aktivity.

LivenessWithVerifyResult

Výsledky živé aktivity s ověřením volání.

Name	Typ	Description
digest	string	Server vypočítal hodnotu hash pro tento požadavek. Pokud se hodnota hash hlášeného klientem liší od počítané hodnoty hash serveru, došlo k ohrožení integrity zpráv mezi klientem a službou a výsledek by neměl být důvěryhodný. Další informace najdete v průvodcích, jak tuto hodnotu využít k zabezpečení kompletního řešení.
livenessDecision	LivenessDecision	Klasifikace aktivity pro cílovou tvář.
sessionImageId	string	ID image žádosti o relaci.
targets	LivenessDecisionTargets	Cíle používané pro klasifikaci aktivity
verifyImageHash	string	Hodnota hash sha256 obrázku verify-image v požadavku.
verifyResult	LivenessWithVerifyOutputs	Výstup ověření tváře. K dispozici pouze v případech, kdy je žádost aktivní s ověřením.

LivenessWithVerifySession

Výsledek relace detekce živé aktivity s ověřením

Name	Typ	Description
authToken	string	Nosný token, který poskytuje ověřování pro sadu Vision SDK spuštěnou v klientské aplikaci. Tento nosný token má omezená oprávnění k provedení pouze požadované akce a vyprší po uplynutí doby TTL. Je také možné ji auditovat.
modelVersion	LivenessModel	Verze modelu používaná pro klasifikaci aktivity. Jedná se o volitelný parametr a pokud není zadaný, zvolí se nejnovější podporovaná verze modelu.
results	LivenessWithVerifySessionResults	Výsledky živé relace s ověřením.
sessionId	string	Jedinečné ID pro odkaz na tuto relaci.
status	OperationState	Aktuální stav relace.

LivenessWithVerifySessionAttempt

Živost s pokusem o ověření relace.

Name	Typ	Description
attemptId	integer	ID pokusu začíná od 1.
attemptStatus	OperationState	Stav pokusu.
error	LivenessError	Chyba živého volání s ověřením bude null, pokud dojde k výsledku.
result	LivenessWithVerifyResult	Výsledek živého volání s ověřením bude null, pokud dojde k chybě.

LivenessWithVerifySessionResults

Výsledky živé relace s ověřením.

Name	Typ	Description
attempts	LivenessWithVerifySessionAttempt[]	Pokusy o data základní živé aktivity s ověřením volání v relaci.
verifyReferences	LivenessWithVerifyReference[]	Odkazy použité k ověření tváře.

OperationState

Aktuální stav relace.

Name	Typ	Description
Canceled	string	Operace byla zrušena uživatelem.
Failed	string	Operace se nezdařila.
NotStarted	string	Operace nebyla spuštěna.
Running	string	Operace probíhá.
Succeeded	string	Operace byla úspěšně dokončena.

QualityForRecognition

Označuje kvalitu obrázku pro rozpoznávání.

Name	Typ	Description
high	string	Vysoce kvalitní.
low	string	Nízká kvalita.
medium	string	Střední kvalita.

Sdílet prostřednictvím

Liveness Session Operations - Create Liveness With Verify Session

Parametry identifikátoru URI

Odpovědi

Zabezpečení

Ocp-Apim-Subscription-Key

AADToken

Rozsahy

Příklady

Create LivenessWithVerify Session

Ukázkový požadavek

Ukázková odpověď

Definice

FaceError

FaceErrorResponse

FaceRectangle

ImageType

LivenessColorDecisionTarget

LivenessDecision

LivenessDecisionTargets

LivenessError

LivenessModel

LivenessOperationMode

LivenessWithVerifyOutputs

LivenessWithVerifyReference

LivenessWithVerifyResult

LivenessWithVerifySession

LivenessWithVerifySessionAttempt

LivenessWithVerifySessionResults

OperationState

QualityForRecognition

Další materiály