Liveness Session Operations - Create Liveness With Verify Session

Usługa:

Azure AI Services

Wersja interfejsu API:

v1.2-preview.1

Utwórz nową sesję liveness z weryfikacją. Urządzenie klienckie przesyła element VerifyImage podczas wywołania /detectLivenessWithVerify/singleModal.
Sesja jest najlepsza w scenariuszach urządzeń klienckich, w których deweloperzy chcą autoryzować urządzenie klienckie tylko do wykrywania aktualności bez udzielania pełnego dostępu do swojego zasobu. Utworzone sesje mają ograniczony zakres życia i autoryzuje tylko klientów do wykonania żądanej akcji przed wygaśnięciem dostępu.

Uprawnienia obejmują...

• • Możliwość wywołania /detectLivenessWithVerify/singleModal dla maksymalnie 3 ponownych prób.
  • Okres istnienia tokenu to 10 minut.

Nuta

• • Dostęp klienta można odwołać, usuwając sesję przy użyciu operacji Usuń żywotność za pomocą weryfikacji sesji.
  • Aby pobrać wynik, użyj sesji Uzyskiwanie aktualności za pomocą weryfikacji.
  • Aby przeprowadzić inspekcję poszczególnych żądań wysyłanych przez klienta do zasobu, użyj pozycji Lista aktywności z weryfikacją wpisów inspekcji sesji.

Alternatywna opcja: urządzenie klienckie przesyła element VerifyImage podczas wywołania /detectLivenessWithVerify/singleModal.

Nuta

Należy podjąć dodatkowe środki w celu sprawdzenia, czy klient wysyła oczekiwany element VerifyImage.

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

Parametry identyfikatora URI

Nazwa	W	Wymagane	Typ	Opis
apiVersion	path	True	string	Wersja interfejsu API
endpoint	path	True	string uri	Obsługiwane punkty końcowe usług Cognitive Services (protokół i nazwa hosta, na przykład: https://{nazwa-zasobu}.cognitiveservices.azure.com).

Treść żądania

Nazwa	Wymagane	Typ	Opis
livenessOperationMode	True	LivenessOperationMode	Typ trybu liveness, który powinien być zgodny z klientem.
authTokenTimeToLiveInSeconds		integer	Sekundy sesji powinny trwać. Zakres wynosi od 60 do 86400 sekund. Wartość domyślna to 600.
deviceCorrelationId		string	Unikatowy identyfikator GUID dla każdego urządzenia użytkownika końcowego. Ma to zapewnić ograniczenie szybkości i anty-młotek. Jeśli parametr "deviceCorrelationIdSetInClient" ma wartość true w tym żądaniu, ten parametr "deviceCorrelationId" musi mieć wartość null.
deviceCorrelationIdSetInClient		boolean	Czy zezwolić klientowi na ustawienie własnego identyfikatora "deviceCorrelationId" za pomocą zestawu SDK usługi Vision. Wartość domyślna to false, a wartość "deviceCorrelationId" musi być ustawiona w tej treści żądania.
enableSessionImage		boolean	Bez względu na to, czy przechowujesz obraz sesji.
livenessSingleModalModel		LivenessModel	Wersja modelu używana do klasyfikacji aktualności. Jest to opcjonalny parametr i jeśli nie zostanie określony, zostanie wybrana najnowsza obsługiwana wersja modelu
returnVerifyImageHash		boolean	Określa, czy zwracany jest skrót obrazu weryfikacji.
sendResultsToClient		boolean	Czy zezwolić na wysyłanie treści odpowiedzi "200 — powodzenie" do klienta, co może być niepożądane ze względów bezpieczeństwa. Wartość domyślna to false, klienci otrzymają odpowiedź "204 — NoContent". Niezależnie od wyboru wywołanie metody GetResult sesji zawsze będzie zawierać treść odpowiedzi umożliwiającą zaimplementowanie logiki biznesowej.
verifyConfidenceThreshold		number	Próg ufności weryfikacji twarzy. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją. https://learn.microsoft.com/legal/cognitive-services/face/characteristics-and-limitations?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#recognition-confidence-score

Odpowiedzi

Nazwa	Typ	Opis
200 OK	CreateLivenessWithVerifySessionResult	Pomyślne wywołanie tworzy sesję dla urządzenia klienckiego i udostępnia token autoryzacji do użycia przez aplikację kliencką w ograniczonym celu i czasie.
Other Status Codes	FaceErrorResponse	Nieoczekiwana odpowiedź na błąd. Nagłówki x-ms-error-code: string

Zabezpieczenia

Ocp-Apim-Subscription-Key

Klucz tajny subskrypcji rozpoznawania twarzy w usłudze Azure AI.

Typ: apiKey
W: header

AADToken

Przepływ OAuth2 usługi Azure Active Directory

Typ: oauth2
Flow: accessCode
Adres URL autoryzacji: https://api.example.com/oauth2/authorize
Adres URL tokenu: https://api.example.com/oauth2/token

Zakresy

Nazwa	Opis
https://cognitiveservices.azure.com/.default

Przykłady

Create LivenessWithVerify Session

Przykładowe żądanie

HTTP

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

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

Przykładowa odpowiedź

Kod stanu:

200

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

Definicje

Nazwa	Opis
CreateLivenessWithVerifySessionJsonContent	Żądanie utworzenia liveness z weryfikacją sesji.
CreateLivenessWithVerifySessionResult	Odpowiedź na sesję liveness z weryfikacją utworzenia z podanym obrazem.
FaceError	Obiekt błędu. Aby uzyskać szczegółowe informacje na temat kodów błędów i komunikatów zwracanych przez usługę rozpoznawania twarzy, zapoznaj się z następującym linkiem: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Odpowiedź zawierająca szczegóły błędu.
FaceRectangle	Prostokąt, w którym można znaleźć twarz.
LivenessModel	Wersja modelu używana do klasyfikacji aktualności.
LivenessOperationMode	Tryb operacji liveness umożliwiający obsługę środowiska użytkownika końcowego klienta.
LivenessWithVerifyImage	Szczegóły twarzy na potrzeby weryfikacji.
QualityForRecognition	Wskazuje jakość obrazu do rozpoznawania.

CreateLivenessWithVerifySessionJsonContent

Żądanie utworzenia liveness z weryfikacją sesji.

Nazwa	Typ	Domyślna wartość	Opis
authTokenTimeToLiveInSeconds	integer	600	Sekundy sesji powinny trwać. Zakres wynosi od 60 do 86400 sekund. Wartość domyślna to 600.
deviceCorrelationId	string		Unikatowy identyfikator GUID dla każdego urządzenia użytkownika końcowego. Ma to zapewnić ograniczenie szybkości i anty-młotek. Jeśli parametr "deviceCorrelationIdSetInClient" ma wartość true w tym żądaniu, ten parametr "deviceCorrelationId" musi mieć wartość null.
deviceCorrelationIdSetInClient	boolean		Czy zezwolić klientowi na ustawienie własnego identyfikatora "deviceCorrelationId" za pomocą zestawu SDK usługi Vision. Wartość domyślna to false, a wartość "deviceCorrelationId" musi być ustawiona w tej treści żądania.
enableSessionImage	boolean		Bez względu na to, czy przechowujesz obraz sesji.
livenessOperationMode	LivenessOperationMode		Typ trybu liveness, który powinien być zgodny z klientem.
livenessSingleModalModel	LivenessModel		Wersja modelu używana do klasyfikacji aktualności. Jest to opcjonalny parametr i jeśli nie zostanie określony, zostanie wybrana najnowsza obsługiwana wersja modelu
returnVerifyImageHash	boolean		Określa, czy zwracany jest skrót obrazu weryfikacji.
sendResultsToClient	boolean		Czy zezwolić na wysyłanie treści odpowiedzi "200 — powodzenie" do klienta, co może być niepożądane ze względów bezpieczeństwa. Wartość domyślna to false, klienci otrzymają odpowiedź "204 — NoContent". Niezależnie od wyboru wywołanie metody GetResult sesji zawsze będzie zawierać treść odpowiedzi umożliwiającą zaimplementowanie logiki biznesowej.
verifyConfidenceThreshold	number		Próg ufności weryfikacji twarzy. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją. https://learn.microsoft.com/legal/cognitive-services/face/characteristics-and-limitations?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#recognition-confidence-score

CreateLivenessWithVerifySessionResult

Odpowiedź na sesję liveness z weryfikacją utworzenia z podanym obrazem.

Nazwa	Typ	Opis
authToken	string	Token elementu nośnego w celu zapewnienia uwierzytelniania zestawu SDK przetwarzania obrazów działającego w aplikacji klienckiej. Ten token elementu nośnego ma ograniczone uprawnienia do wykonywania tylko wymaganej akcji i wygasa po upływie czasu wygaśnięcia. Można go również przeprowadzić inspekcję.
sessionId	string	Unikatowy identyfikator sesji utworzonej sesji. Wygaśnie on 48 godzin po jego utworzeniu lub może zostać usunięty wcześniej przy użyciu odpowiedniej operacji DELETE sesji.
verifyImage	LivenessWithVerifyImage	Szczegóły twarzy na potrzeby weryfikacji.

FaceError

Obiekt błędu. Aby uzyskać szczegółowe informacje na temat kodów błędów i komunikatów zwracanych przez usługę rozpoznawania twarzy, zapoznaj się z następującym linkiem: https://aka.ms/face-error-codes-and-messages.

Nazwa	Typ	Opis
code	string	Jeden z zdefiniowanych przez serwer zestaw kodów błędów.
message	string	Czytelna dla człowieka reprezentacja błędu.

FaceErrorResponse

Odpowiedź zawierająca szczegóły błędu.

Nazwa	Typ	Opis
error	FaceError	Obiekt błędu.

FaceRectangle

Prostokąt, w którym można znaleźć twarz.

Nazwa	Typ	Opis
height	integer	Wysokość prostokąta w pikselach.
left	integer	Odległość od lewej krawędzi, jeśli obraz do lewej krawędzi prostokąta w pikselach.
top	integer	Odległość od górnej krawędzi, jeśli obraz do górnej krawędzi prostokąta w pikselach.
width	integer	Szerokość prostokąta w pikselach.

LivenessModel

Wersja modelu używana do klasyfikacji aktualności.

Nazwa	Typ	Opis
2022-10-15-preview.04	string
2023-12-20-preview.06	string

LivenessOperationMode

Tryb operacji liveness umożliwiający obsługę środowiska użytkownika końcowego klienta.

Nazwa	Typ	Opis
Passive	string	Wykorzystuje pasywną technikę utrzymania, która nie wymaga żadnych dodatkowych akcji od użytkownika. Wymaga normalnego oświetlenia wewnętrznego i wysokiej jasności ekranu w celu uzyskania optymalnej wydajności. W związku z tym ten tryb ma wąskią kopertę operacyjną i nie będzie odpowiedni dla scenariuszy, które wymagają, aby użytkownik końcowy był w jasnych warunkach oświetleniowych. Uwaga: jest to jedyny obsługiwany tryb rozwiązania Dla urządzeń przenośnych (iOS i Android).
PassiveActive	string	Ten tryb wykorzystuje hybrydową technikę pasywnej lub aktywnej aktywności, która wymaga współpracy użytkowników. Jest zoptymalizowany pod kątem wymagania aktywnego ruchu tylko w warunkach nieoptymalnych oświetlenia. W przeciwieństwie do trybu pasywnego ten tryb nie ma ograniczeń oświetlenia, a tym samym oferuje szerszą kopertę operacyjną. Ten tryb jest preferowany w przypadku rozwiązań opartych na sieci Web ze względu na brak automatycznej kontroli jasności ekranu dostępnej w przeglądarkach, co utrudnia działanie koperty trybu pasywnego w rozwiązaniach opartych na sieci Web.

LivenessWithVerifyImage

Szczegóły twarzy na potrzeby weryfikacji.

Nazwa	Typ	Opis
faceRectangle	FaceRectangle	Region twarzy, w którym utworzono klasyfikację obrazu porównania.
qualityForRecognition	QualityForRecognition	Jakość obrazu twarzy do rozpoznawania.

QualityForRecognition

Wskazuje jakość obrazu do rozpoznawania.

Nazwa	Typ	Opis
high	string	Wysoka jakość.
low	string	Niska jakość.
medium	string	Średnia jakość.