Tutorial: Erkennen von Face Liveness

Erfahren Sie, wie Sie die Gesichts-Liveness-Erkennung in Ihren Workflow integrieren, indem Sie serverseitige Logik und begleitende Frontend-Client-Anwendungen verwenden.

Tipp

Allgemeine Informationen zur Gesichtslebenserkennung finden Sie in der konzeptionellen Anleitung.

In diesem Tutorial erfahren Sie, wie Sie eine Frontend-App mit einem Applikationsserver ausführen, um die Lebendigkeitserkennung zu ermöglichen. Sie können die Gesichtsüberprüfung auch auf verschiedenen Plattformen und Sprachen hinzufügen.

Wichtig

Die Face-Client-SDKs für die Liveness sind ein eingeschränktes Feature. Sie müssen den Zugriff auf das Liveness-Feature anfordern, indem Sie das Aufnahmeformular für die Gesichtserkennung ausfüllen. Wenn Ihrem Azure-Abonnement Zugriff gewährt wird, können Sie das Face Liveness-SDK herunterladen.

Voraussetzungen

Azure-Abonnement – Erstellen eines kostenlosen Kontos
Damit Sie den entsprechenden Bedingungen für verantwortungsvolle KI zustimmen und eine Ressource erstellen können, muss Ihrem Azure-Konto die Rolle Cognitive Services-Mitwirkender zugewiesen sein. Um diese Rolle Ihrem Konto zuzuweisen, führen Sie die Schritte in der Dokumentation Zuweisen von Rollen aus, oder wenden Sie sich an Ihren Administrator.
Sobald Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Gesichtserkennungsressource erstellen, um Ihren Schlüssel und Endpunkt zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und den Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit dem Gesichtserkennungsdienst verbinden zu können.
Zugriff auf die für Azure Vision erforderlichen geschützten Artefakte im Foundry Tools Face Client SDK für Mobile (iOS und Android) und Web.
- Um zu beginnen, müssen Sie sich für die limitierten Zugangsfeatures der Gesichtserkennung bewerben, um Zugriff auf die geschützten Artefakte zu erhalten. Weitere Informationen finden Sie auf der Seite zum eingeschränkten Zugriff auf die Gesichtserkennung.
Vertrautheit mit der Liveness-Gesichtserkennungsfunktion. Sehen Sie sich den konzeptionellen Leitfaden an.

Tipp

Nach Abschluss der Voraussetzungen können Sie die Liveness-Erfahrung auf den folgenden Plattformen ausprobieren:

iOS: iOS App Store – tippen Sie 10 Mal nach der Installation auf den App-Bildschirm, um den Entwicklermodus zu aktivieren.
Android: Google Play Store – tippen Sie 10 Mal nach der Installation auf den App-Bildschirm, um den Entwicklermodus zu aktivieren.
Web: Probieren Sie es direkt in Vision Studio aus.

Sie können auch ein vollständiges Frontend-Beispiel (iOS, Android oder Web) aus dem Abschnitt "Beispiele " erstellen und ausführen.

Vorbereiten der Front-End-Anwendung

Wir stellen SDKs in mehreren Sprachen bereit, um die Integration in Ihre Frontend-Anwendung zu vereinfachen. Lesen Sie in den folgenden Abschnitten die README-Datei für das ausgewählte SDK, um sowohl die Benutzeroberfläche als auch den erforderlichen Code zu integrieren.

Wichtig

Jedes Frontend-SDK erfordert Zugriff auf eine gated-Ressource, um erfolgreich kompiliert zu werden. Lesen Sie die folgenden Anweisungen zum Einrichten dieses Zugriffs.

Für Swift iOS:

Artefakte: Azure AI Face UI SDK für iOS
API-Referenz: AzureAIVisionFaceUI-Referenz
Beispiel: iOS-Beispiel

Für Kotlin/Java Android:

Artefakte: Maven Central: com.azure:azure-ai-vision-face-ui
API-Referenz: Azure-ai-vision-face-ui-Referenz
Beispiel: Android-Beispiel

Für JavaScript-Web:

Artefakte: @azure/ai-vision-face-ui - npm
API-Referenz: AzureAIVisionFaceUI-Referenz
Beispiel: Webbeispiel
Framework-Unterstützung: Arbeitet mit gängigen Frameworks wie React (einschließlich Next.js), Vue.jsund Angular.

Sobald sie in Ihre Frontend-Anwendung integriert ist, startet das SDK die Kamera, leitet den Benutzer zum Anpassen seiner Position, verfasst die Liveness-Nutzlast und sendet sie zur Verarbeitung an den Azure AI Face-Dienst.

Überwachen Sie den Abschnitt "Releases" des Repositorys auf neue SDK-Versionsupdates, und aktivieren Sie automatisierte Benachrichtigungen für Abhängigkeitsupdates, z. B. GitHub Dependabot (für GitHub-Repositorys) oder Renovieren (GitHub, GitLab, Bitbucket, Azure Repos).

Durchführen der Liveness-Erkennung

Die folgenden Schritte beschreiben den Liveness-Orchestrierungsprozess:

Die Front-End-Anwendung startet die Liveness-Überprüfung und benachrichtigt den App-Server.

Der App-Server erstellt eine neue Liveness-Sitzung mit dem Azure KI-Gesichtserkennungsdienst. Der Dienst erstellt eine Liveness-Sitzung und antwortet mit einem Sitzungs-Autorisierungstoken. Weitere Informationen zu jedem Anforderungsparameter, der an der Erstellung einer Liveness-Sitzung beteiligt ist, finden Sie unter Liveness Create Session Operation.

var endpoint = new Uri(System.Environment.GetEnvironmentVariable("FACE_ENDPOINT"));
var key = new AzureKeyCredential(System.Environment.GetEnvironmentVariable("FACE_APIKEY"));

var body = JsonSerializer.Serialize(new
{
    livenessOperationMode = "PassiveActive",
    deviceCorrelationId = "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    enableSessionImage = true
});

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

var response = await client.PostAsync(
    $"{endpoint}/face/v1.2/detectLiveness-sessions",
    new StringContent(body, Encoding.UTF8, "application/json"));

response.EnsureSuccessStatusCode();

using var doc  = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root       = doc.RootElement;

Console.WriteLine("Session created");
Console.WriteLine($"sessionId : {root.GetProperty("sessionId").GetString()}");
Console.WriteLine($"authToken : {root.GetProperty("authToken").GetString()}");

String endpoint = System.getenv("FACE_ENDPOINT");
String key = System.getenv("FACE_APIKEY");

String body = """
{
    "livenessOperationMode": "PassiveActive",
    "deviceCorrelationId": "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    "enableSessionImage": true,
}
""";

HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(endpoint + "/face/v1.2/detectLiveness-sessions"))
        .header("Content-Type", "application/json")
        .header("Ocp-Apim-Subscription-Key", key)
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();

HttpResponse<String> res = HttpClient.newHttpClient()
        .send(req, HttpResponse.BodyHandlers.ofString());

if (res.statusCode() != 200) throw new RuntimeException("HTTP error: " + res.statusCode());

JsonNode json = new ObjectMapper().readTree(res.body());
System.out.println("Session created");
System.out.println("sessionId : " + json.get("sessionId").asText());
System.out.println("authToken : " + json.get("authToken").asText());

endpoint = os.environ["FACE_ENDPOINT"]
key = os.environ["FACE_APIKEY"]

url  = f"{endpoint}/face/v1.2/detectLiveness-sessions"
body = {
    "livenessOperationMode": "PassiveActive",
    "deviceCorrelationId":  "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    "enableSessionImage":   True
}

headers = {
    "Ocp-Apim-Subscription-Key": key,
    "Content-Type": "application/json"
}

res = requests.post(url, headers=headers, data=json.dumps(body))
res.raise_for_status()

data = res.json()
print("Session created")
print("sessionId :", data["sessionId"])
print("authToken :", data["authToken"])

const endpoint = process.env['FACE_ENDPOINT'];
const apikey = process.env['FACE_APIKEY'];

const url  = `${endpoint}/face/v1.2/detectLiveness-sessions`;
const body = {
    livenessOperationMode: "PassiveActive",
    deviceCorrelationId:  "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    enableSessionImage:   true
};

const headers = {
    "Ocp-Apim-Subscription-Key": key,
    "Content-Type": "application/json"
};

async function createLivenessSession() {
    const res = await fetch(url, {
        method: "POST",
        headers,
        body: JSON.stringify(body)
    });

    if (!res.ok) {
        throw new Error(`${res.status} ${await res.text()}`);
    }

    const data = await res.json();
    console.log("Session created");
    console.log("sessionId :", data.sessionId);
    console.log("authToken :", data.authToken);
}

curl --request POST --location "%FACE_ENDPOINT%/face/v1.2/detectLiveness-sessions" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%" ^
--header "Content-Type: application/json" ^
--data ^
"{ ^
    ""livenessOperationMode"": ""passiveactive"", ^
    ""deviceCorrelationId"": ""723d6d03-ef33-40a8-9682-23a1feb7bccd"", ^
    ""enableSessionImage"": ""true"" ^
}"

curl --request POST --location "${FACE_ENDPOINT}/face/v1.2/detectLivenesswithVerify-sessions" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}" \
--header "Content-Type: application/json" \
--data \
'{
    "livenessOperationMode": "passiveactive",
    "deviceCorrelationId": "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    "enableSessionImage": "true"
}'

Ein Beispiel für den Antworttext:

{
    "sessionId": "a6e7193e-b638-42e9-903f-eaf60d2b40a5",
    "authToken": "<session-authorization-token>",
    "status": "NotStarted",
    "modelVersion": "2025-05-20",
    "results": {
        "attempts": []
    }
}

Der App-Server stellt das Sitzungsautorisierungstoken zurück zur Front-End-Anwendung bereit.

Die Front-End-Anwendung verwendet das Sitzungsautorisierungstoken, um die Gesichtslebendigkeitserkennung zu starten, die den Lebendigkeitsflow startet.

    FaceLivenessDetector(
        sessionAuthorizationToken = FaceSessionToken.sessionToken,
        verifyImageFileContent = FaceSessionToken.sessionSetInClientVerifyImage,
        deviceCorrelationId = "null",
        onSuccess = viewModel::onSuccess,
        onError = viewModel::onError
    )

struct HostView: View {
   @State var livenessDetectionResult: LivenessDetectionResult? = nil
   var token: String
   var body: some View {
       if livenessDetectionResult == nil {
           FaceLivenessDetectorView(result: $livenessDetectionResult,
                                    sessionAuthorizationToken: token)
       } else if let result = livenessDetectionResult {
           VStack {
               switch result { 
                   case .success(let success):
                   /// <#show success#>
                   case .failure(let error):
                   /// <#show failure#>
               }
           }
       }
   }
}

faceLivenessDetector = document.createElement("azure-ai-vision-face-ui");
document.getElementById("container").appendChild(faceLivenessDetector);
faceLivenessDetector.start(session.authToken)

Das SDK startet die Kamera, bringt die Person in die richtige Position und bereitet anschließend die Nutzdaten vor, um den Endpunkt für den Lebendigkeitserkennungsdienst aufzurufen.
Das SDK ruft den Azure Vision Face-Dienst auf, um die Lebendigkeitserkennung durchzuführen. Sobald der Dienst antwortet, benachrichtigt das SDK die Frontend-Anwendung, dass die Liveness-Überprüfung abgeschlossen ist. Hinweis: Die Dienstantwort enthält nicht das Ergebnis der Liveness-Prüfung. Sie müssen diese Informationen vom App-Server abfragen.
Die Front-End-Anwendung informiert den App-Server über den Abschluss der Liveness-Überprüfung.

Der App-Server fragt das Ergebnis der Lebendigkeitserkennung vom Azure Vision-Gesichtserkennungsdienst ab.

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

var response = await client.GetAsync(
    $"{endpoint}/face/v1.2/livenessSessions/{sessionId}/result");

response.EnsureSuccessStatusCode();

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = doc.RootElement;
var attempts = root.GetProperty("results").GetProperty("attempts");
var latestAttempt = attempts[attempts.GetArrayLength() - 1];
var attemptStatus = latestAttempt.GetProperty("attemptStatus").GetString();

Console.WriteLine($"Session id: {root.GetProperty("sessionId").GetString()}");
Console.WriteLine($"Session status: {root.GetProperty("status").GetString()}");
Console.WriteLine($"Latest attempt status: {attemptStatus}");

if (attemptStatus == "Succeeded")
    Console.WriteLine($"Liveness detection decision: {latestAttempt.GetProperty("result").GetProperty("livenessDecision").GetString()}");
else
{
    var error = latestAttempt.GetProperty("error");
    Console.WriteLine($"Error: {error.GetProperty("code").GetString()} - {error.GetProperty("message").GetString()}");
}

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/livenessSessions/" + sessionId + "/result"))
    .header("Ocp-Apim-Subscription-Key", key)
    .GET()
    .build();

HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());

if (res.statusCode() != 200) throw new RuntimeException("HTTP error: " + res.statusCode());

JsonNode root = new ObjectMapper().readTree(res.body());
JsonNode attempts = root.path("results").path("attempts");
JsonNode latestAttempt = attempts.get(attempts.size() - 1);

String attemptStatus = latestAttempt.path("attemptStatus").asText();

System.out.println("Session id: " + root.path("sessionId").asText());
System.out.println("Session status: " + root.path("status").asText());
System.out.println("Latest attempt status: " + attemptStatus);

if ("Succeeded".equals(attemptStatus)) {
    System.out.println("Liveness detection decision: " +
        latestAttempt.path("result").path("livenessDecision").asText());
} else {
    JsonNode error = latestAttempt.path("error");
    System.out.println("Error: " + error.path("code").asText() + " - " +
        error.path("message").asText());
}

url = f"{endpoint}/face/v1.2/livenessSessions/{sessionId}/result"
headers = { "Ocp-Apim-Subscription-Key": key }

res = requests.get(url, headers=headers)
res.raise_for_status()

data = res.json()
attempts = data["results"]["attempts"]
latest_attempt = attempts[-1]
attempt_status = latest_attempt.get("attemptStatus")

print(f"Session id: {data['sessionId']}")
print(f"Session status: {data['status']}")
print(f"Latest attempt status: {attempt_status}")

if attempt_status == "Succeeded":
    print(f"Liveness detection decision: {latest_attempt['result']['livenessDecision']}")
else:
    err = latest_attempt.get("error", {})
    print(f"Error: {err.get('code')} - {err.get('message')}")

const url = `${endpoint}/face/v1.2/livenessSessions/${sessionId}/result`;
const headers = {
    "Ocp-Apim-Subscription-Key": apikey
};

async function getLivenessSessionResult() {
    const res = await fetch(url, { method: "GET", headers });
    if (!res.ok) {
        throw new Error(`${res.status} ${await res.text()}`);
    }

    const data = await res.json();
    const attempts = data.results.attempts;
    const latestAttempt = attempts[attempts.length - 1];
    const attemptStatus = latestAttempt.attemptStatus;

    console.log("Session id :", data.sessionId);
    console.log("Session status :", data.status);
    console.log("Latest attempt status :", attemptStatus);

    if (attemptStatus === "Succeeded") {
        console.log("Liveness detection decision :", latestAttempt.result.livenessDecision);
    } else {
            const err = latestAttempt.error || {};
            console.log(`Error: ${err.code} - ${err.message}`);
    }
}

curl --request GET --location "%FACE_ENDPOINT%/face/v1.2/detectLiveness-sessions/<session-id>" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%"

curl --request GET --location "${FACE_ENDPOINT}/face/v1.2/detectLiveness-sessions/<session-id>" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}"

Ein Beispiel für den Antworttext:

{
    "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
    "authToken": "eyJhbGciOiJFUzI1NiIsIm",
    "status": "NotStarted",
    "modelVersion": "2024-11-15",
    "results": {
        "attempts": [
            {
                "attemptId": 2,
                "attemptStatus": "Succeeded",
                "result": {
                "livenessDecision": "realface",
                "targets": {
                    "color": {
                    "faceRectangle": {
                            "top": 669,
                            "left": 203,
                            "width": 646,
                            "height": 724
                        }
                    }
                },
                "digest": "B0A803BB7B26F3C8F29CD36030F8E63ED3FAF955FEEF8E01C88AB8FD89CCF761",
                "sessionImageId": "Ae3PVWlXAmVAnXgkAFt1QSjGUWONKzWiSr2iPh9p9G4I"
                }
            },
            {
                "attemptId": 1,
                "attemptStatus": "Failed",
                "error": {
                "code": "FaceWithMaskDetected",
                "message": "Mask detected on face image.",
                "targets": {
                        "color": {
                        "faceRectangle": {
                            "top": 669,
                            "left": 203,
                            "width": 646,
                            "height": 724
                        }
                        }
                    }
                }
            }
        ]
    }
}

Der App-Server löscht die Sitzung, nachdem sie alle Sitzungsergebnisse abfragt.

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

await client.DeleteAsync($"{endpoint}/face/v1.2/livenessSessions/{sessionId}");
Console.WriteLine($"Session deleted: {sessionId}");

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/livenessSessions/" + sessionId))
    .header("Ocp-Apim-Subscription-Key", key)
    .DELETE()
    .build();

HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("Session deleted: " + sessionId);

headers = { "Ocp-Apim-Subscription-Key": key }
requests.delete(f"{endpoint}/face/v1.2/livenessSessions/{sessionId}", headers=headers)
print(f"Session deleted: {sessionId}")

const headers = { "Ocp-Apim-Subscription-Key": apikey };
await fetch(`${endpoint}/face/v1.2/livenessSessions/${sessionId}`, { method: "DELETE", headers });
console.log(`Session deleted: ${sessionId}`);

curl --request DELETE --location "%FACE_ENDPOINT%/face/v1.2/detectLiveness-sessions/<session-id>" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%"

curl --request DELETE --location "${FACE_ENDPOINT}/face/v1.2/detectLiveness-sessions/<session-id>" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}"

Durchführen der Liveness-Erkennung mit Gesichtsüberprüfung

Die Kombination aus Gesichtsüberprüfung und Liveness-Erkennung ermöglicht die biometrische Überprüfung einer bestimmten Person von Interesse mit der zusätzlichen Garantie, dass die Person physisch im System vorhanden ist.

Die Integration der Lebendigkeitserkennung in die Überprüfung besteht aus zwei Teilen.

Schritt 1 : Auswählen eines Referenzbilds

Um die genauesten Erkennungsergebnisse zu erzielen, befolgen Sie die Tipps, die in den Kompositionsanforderungen für ID-Überprüfungsszenarien aufgeführt sind.

Schritt 2: Einrichtung der Orchestrierung von Lebendigkeit mit Überprüfung

Die folgenden allgemeinen Schritte zeigen, wie Sie die Lebendigkeit mit Überprüfung orchestrieren können:

Stellen Sie das Überprüfungsreferenzbild mithilfe einer der folgenden beiden Methoden bereit:

Der App-Server stellt das Referenzbild beim Erstellen der Liveness-Sitzung bereit. Weitere Informationen zu jedem Anforderungsparameter, der an der Erstellung einer Liveness-Sitzung mit Überprüfung beteiligt ist, finden Sie unter Liveness With Verify Create Session Operation.

var endpoint = new Uri(System.Environment.GetEnvironmentVariable("FACE_ENDPOINT"));
var key      = System.Environment.GetEnvironmentVariable("FACE_APIKEY");

// Create the JSON part
var jsonPart = new StringContent(
    JsonSerializer.Serialize(new
    {
        livenessOperationMode = "PassiveActive",
        deviceCorrelationId = "723d6d03-ef33-40a8-9682-23a1feb7bcc",
        enableSessionImage = true
    }),
    Encoding.UTF8,
    "application/json"
);
jsonPart.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
{
    Name = "CreateLivenessWithVerifySessionRequest"
};

// Create the file part
using var fileStream = File.OpenRead("test.png");
var filePart = new StreamContent(fileStream);
filePart.Headers.ContentType = new MediaTypeHeaderValue("image/png");
filePart.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
{
    Name = "VerifyImage",
    FileName = "test.png"
};

// Build multipart form data
using var formData = new MultipartFormDataContent();
formData.Add(jsonPart);
formData.Add(filePart);

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

var response = await client.PostAsync($"{endpoint}/face/v1.2/createLivenessWithVerifySession", formData);
response.EnsureSuccessStatusCode();

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = doc.RootElement;

Console.WriteLine("Session created.");
Console.WriteLine($"Session id: {root.GetProperty("sessionId").GetString()}");
Console.WriteLine($"Auth token: {root.GetProperty("authToken").GetString()}");

String endpoint = System.getenv("FACE_ENDPOINT");
String key      = System.getenv("FACE_APIKEY");

String json = """
{
"livenessOperationMode": "PassiveActive",
"deviceCorrelationId": "723d6d03-ef33-40a8-9682-23a1feb7bcc",
"enableSessionImage": true
}
""";

byte[] img = Files.readAllBytes(Path.of("test.png"));
String boundary = "----faceBoundary" + java.util.UUID.randomUUID();

var head =
    "--" + boundary + "\r\n" +
    "Content-Disposition: form-data; name=\"CreateLivenessWithVerifySessionRequest\"\r\n" +
    "Content-Type: application/json\r\n\r\n" +
    json + "\r\n" +
    "--" + boundary + "\r\n" +
    "Content-Disposition: form-data; name=\"VerifyImage\"; filename=\"test.png\"\r\n" +
    "Content-Type: image/png\r\n\r\n";

var tail = "\r\n--" + boundary + "--\r\n";

byte[] body = java.nio.ByteBuffer
    .allocate(head.getBytes(StandardCharsets.UTF_8).length + img.length + tail.getBytes(StandardCharsets.UTF_8).length)
    .put(head.getBytes(StandardCharsets.UTF_8))
    .put(img)
    .put(tail.getBytes(StandardCharsets.UTF_8))
    .array();

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/createLivenessWithVerifySession"))
    .header("Ocp-Apim-Subscription-Key", key)
    .header("Content-Type", "multipart/form-data; boundary=" + boundary)
    .POST(HttpRequest.BodyPublishers.ofByteArray(body))
    .build();

HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
if (res.statusCode() != 200) throw new RuntimeException("HTTP error: " + res.statusCode());

JsonNode root = new ObjectMapper().readTree(res.body());
System.out.println("Session created.");
System.out.println("Session id: " + root.get("sessionId").asText());
System.out.println("Auth token: " + root.get("authToken").asText());

endpoint = os.environ["FACE_ENDPOINT"]
key      = os.environ["FACE_APIKEY"]

url = f"{endpoint}/face/v1.2/createLivenessWithVerifySession"
files = {
    "CreateLivenessWithVerifySessionRequest": (
        "request.json",
        json.dumps({
            "livenessOperationMode": "PassiveActive",
            "deviceCorrelationId": "723d6d03-ef33-40a8-9682-23a1feb7bcc",
            "enableSessionImage": True
        }),
        "application/json"
    ),
    "VerifyImage": ("test.png", open("test.png", "rb"), "image/png")
}
headers = { "Ocp-Apim-Subscription-Key": key }

res = requests.post(url, headers=headers, files=files)
res.raise_for_status()

data = res.json()
print("Session created.")
print("Session id:", data["sessionId"])
print("Auth token:", data["authToken"])

const endpoint = process.env["FACE_ENDPOINT"];
const apikey   = process.env["FACE_APIKEY"];

const form = new FormData();
form.append(
    "CreateLivenessWithVerifySessionRequest",
    new Blob([JSON.stringify({
        livenessOperationMode: "PassiveActive",
        deviceCorrelationId: "723d6d03-ef33-40a8-9682-23a1feb7bcc",
        enableSessionImage: true
    })], { type: "application/json" }),
    "request.json"
);
// If your runtime doesn't support Blob here, you can use fs.createReadStream instead.
form.append("VerifyImage", new Blob([fs.readFileSync("test.png")], { type: "image/png" }), "test.png");

const res = await fetch(`${endpoint}/face/v1.2/createLivenessWithVerifySession`, {
    method: "POST",
    headers: { "Ocp-Apim-Subscription-Key": apikey },
    body: form
});
if (!res.ok) {
    throw new Error(`${res.status} ${await res.text()}`);
}

const data = await res.json();
console.log("Session created.");
console.log("Session id:", data.sessionId);
console.log("Auth token:", data.authToken);

curl --request POST --location "%FACE_ENDPOINT%/face/v1.2/detectLivenesswithVerify-sessions" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%" ^
--form "Parameters=""{\\\""livenessOperationMode\\\"": \\\""passiveactive\\\"", \\\""deviceCorrelationId\\\"": \\\""723d6d03-ef33-40a8-9682-23a1feb7bccd\\\"", ""enableSessionImage"": ""true""}""" ^
--form "VerifyImage=@""test.png"""

curl --request POST --location "${FACE_ENDPOINT}/face/v1.2/detectLivenesswithVerify-sessions" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}" \
--form 'Parameters="{
    \"livenessOperationMode\": \"passiveactive\",
    \"deviceCorrelationId\": \"723d6d03-ef33-40a8-9682-23a1feb7bccd\"
}"' \
--form 'VerifyImage=@"test.png"'

Ein Beispiel für den Antworttext:

{
    "sessionId": "3847ffd3-4657-4e6c-870c-8e20de52f567",
    "authToken": "<session-authorization-token>",
    "status": "NotStarted",
    "modelVersion": "2024-11-15",
    "results": {
        "attempts": [],
        "verifyReferences": [
        {
            "referenceType": "image",
            "faceRectangle": {
            "top": 98,
            "left": 131,
            "width": 233,
            "height": 300
            },
            "qualityForRecognition": "high"
        }
        ]
    }
}

Die Frontend-Anwendung stellt beim Initialisieren der mobilen SDKs das Referenzimage bereit. Dieses Szenario wird in der Weblösung nicht unterstützt.

    FaceLivenessDetector(
        sessionAuthorizationToken = FaceSessionToken.sessionToken,
        verifyImageFileContent = FaceSessionToken.sessionSetInClientVerifyImage,
        deviceCorrelationId = "null",
        onSuccess = viewModel::onSuccess,
        onError = viewModel::onError
    )

struct HostView: View {
    @State var livenessDetectionResult: LivenessDetectionResult? = nil
    var token: String
    var body: some View {
        if livenessDetectionResult == nil {
            FaceLivenessDetectorView(result: $livenessDetectionResult,
                                        sessionAuthorizationToken: token)
        } else if let result = livenessDetectionResult {
            VStack {
                switch result { 
                    case .success(let success):
                    /// <#show success#>
                    case .failure(let error):
                    /// <#show failure#>
                }
            }
        }
    }
}

Not supported.

Der App-Server kann nun neben dem Liveness-Ergebnis auch das Überprüfungsergebnis abfragen.

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

var response = await client.GetAsync($"{endpoint}/face/v1.2/livenessSessions/{sessionId}/result");
response.EnsureSuccessStatusCode();

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = doc.RootElement;

var attempts = root.GetProperty("results").GetProperty("attempts");
var latestAttempt = attempts[attempts.GetArrayLength() - 1];
var attemptStatus = latestAttempt.GetProperty("attemptStatus").GetString();

Console.WriteLine($"Session id: {root.GetProperty("sessionId").GetString()}");
Console.WriteLine($"Session status: {root.GetProperty("status").GetString()}");
Console.WriteLine($"Latest attempt status: {attemptStatus}");

if (attemptStatus == "Succeeded")
{
    var decision = latestAttempt.GetProperty("result").GetProperty("livenessDecision").GetString();
    var verify   = latestAttempt.GetProperty("verifyResult");
    Console.WriteLine($"Liveness detection decision: {decision}");
    Console.WriteLine($"Verify isIdentical: {verify.GetProperty("isIdentical").GetBoolean()}");
    Console.WriteLine($"Verify matchConfidence: {verify.GetProperty("matchConfidence").GetDouble()}");
}
else
{
    var err = latestAttempt.GetProperty("error");
    Console.WriteLine($"Error: {err.GetProperty("code").GetString()} - {err.GetProperty("message").GetString()}");
}

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/livenessSessions/" + sessionId + "/result"))
    .header("Ocp-Apim-Subscription-Key", key)
    .GET()
    .build();

HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
if (res.statusCode() != 200) throw new RuntimeException("HTTP error: " + res.statusCode());

ObjectMapper om = new ObjectMapper();
JsonNode root = om.readTree(res.body());

JsonNode attempts = root.path("results").path("attempts");
JsonNode latest   = attempts.get(attempts.size() - 1);
String attemptStatus = latest.path("attemptStatus").asText();

System.out.println("Session id: " + root.path("sessionId").asText());
System.out.println("Session status: " + root.path("status").asText());
System.out.println("Latest attempt status: " + attemptStatus);

if ("Succeeded".equals(attemptStatus)) {
    String decision = latest.path("result").path("livenessDecision").asText();
    JsonNode verify = latest.path("verifyResult");
    System.out.println("Liveness detection decision: " + decision);
    System.out.println("Verify isIdentical: " + verify.path("isIdentical").asBoolean());
    System.out.println("Verify matchConfidence: " + verify.path("matchConfidence").asDouble());
} else {
    JsonNode err = latest.path("error");
    System.out.println("Error: " + err.path("code").asText() + " - " + err.path("message").asText());
}

url = f"{endpoint}/face/v1.2/livenessSessions/{sessionId}/result"
headers = {"Ocp-Apim-Subscription-Key": key}

res = requests.get(url, headers=headers)
res.raise_for_status()

data = res.json()
attempts = data["results"]["attempts"]
latest = attempts[-1]
attempt_status = latest.get("attemptStatus")

print(f"Session id: {data['sessionId']}")
print(f"Session status: {data['status']}")
print(f"Latest attempt status: {attempt_status}")

if attempt_status == "Succeeded":
    decision = latest["result"]["livenessDecision"]
    verify   = latest.get("verifyResult", {})
    print(f"Liveness detection decision: {decision}")
    print(f"Verify isIdentical: {verify.get('isIdentical')}")
    print(f"Verify matchConfidence: {verify.get('matchConfidence')}")
else:
    err = latest.get("error", {})
    print(f"Error: {err.get('code')} - {err.get('message')}")

const url = `${endpoint}/face/v1.2/livenessSessions/${sessionId}/result`;
const headers = { "Ocp-Apim-Subscription-Key": apikey };

async function getLivenessWithVerifyResult() {
const res = await fetch(url, { method: "GET", headers });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const data = await res.json();
const attempts = data.results.attempts;
const latest = attempts[attempts.length - 1];
const attemptStatus = latest.attemptStatus;

console.log("Session id:", data.sessionId);
console.log("Session status:", data.status);
console.log("Latest attempt status:", attemptStatus);

if (attemptStatus === "Succeeded") {
    console.log("Liveness detection decision:", latest.result.livenessDecision);
    console.log("Verify isIdentical:", latest.verifyResult?.isIdentical);
    console.log("Verify matchConfidence:", latest.verifyResult?.matchConfidence);
} else {
    const err = latest.error || {};
    console.log(`Error: ${err.code} - ${err.message}`);
}
}

curl --request GET --location "%FACE_ENDPOINT%/face/v1.2/detectLivenesswithVerify-sessions/<session-id>" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%"

curl --request GET --location "${FACE_ENDPOINT}/face/v1.2/detectLivenesswithVerify-sessions/<session-id>" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}"

Ein Beispiel für den Antworttext:

{
    "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
    "authToken": "eyJhbGciOiJFUzI1NiIsIm",
    "status": "NotStarted",
    "modelVersion": "2024-11-15",
    "results": {
        "attempts": [
        {
            "attemptId": 2,
            "attemptStatus": "Succeeded",
            "result": {
            "livenessDecision": "realface",
            "targets": {
                "color": {
                "faceRectangle": {
                    "top": 669,
                    "left": 203,
                    "width": 646,
                    "height": 724
                }
                }
            },
            "verifyResult": {
                "matchConfidence": 0.08871888,
                "isIdentical": false
            },
            "digest": "B0A803BB7B26F3C8F29CD36030F8E63ED3FAF955FEEF8E01C88AB8FD89CCF761",
            "sessionImageId": "Ae3PVWlXAmVAnXgkAFt1QSjGUWONKzWiSr2iPh9p9G4I",
            "verifyImageHash": "43B7D8E8769533C3290DBD37A84D821B2C28CB4381DF9C6784DBC4AAF7E45018"
            }
        },
        {
            "attemptId": 1,
            "attemptStatus": "Failed",
            "error": {
                "code": "FaceWithMaskDetected",
                "message": "Mask detected on face image.",
                "targets": {
                    "color": {
                    "faceRectangle": {
                            "top": 669,
                            "left": 203,
                            "width": 646,
                            "height": 724
                        }
                    }
                }
            }
        }
        ],
        "verifyReferences": [
            {
                "referenceType": "image",
                "faceRectangle": {
                "top": 316,
                "left": 131,
                "width": 498,
                "height": 677
                },
                "qualityForRecognition": "high"
            }
        ]
        }
    }

Der App-Server kann die Sitzung löschen, wenn Sie das Ergebnis nicht mehr benötigen.

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

await client.DeleteAsync($"{endpoint}/face/v1.2/livenessWithVerifySessions/{sessionId}");
Console.WriteLine($"Liveness-with-Verify session deleted: {sessionId}");

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/livenessWithVerifySessions/" + sessionId))
    .header("Ocp-Apim-Subscription-Key", key)
    .DELETE()
    .build();

HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("Liveness-with-Verify session deleted: " + sessionId);

headers = { "Ocp-Apim-Subscription-Key": key }
requests.delete(f"{endpoint}/face/v1.2/livenessWithVerifySessions/{sessionId}", headers=headers)
print(f"Liveness-with-Verify session deleted: {sessionId}")

const headers = { "Ocp-Apim-Subscription-Key": apikey };
await fetch(`${endpoint}/face/v1.2/livenessWithVerifySessions/${sessionId}`, { method: "DELETE", headers });
console.log(`Liveness-with-Verify session deleted: ${sessionId}`);

curl --request DELETE --location "%FACE_ENDPOINT%/face/v1.2/detectLivenesswithVerify-sessions/<session-id>" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%"

curl --request DELETE --location "${FACE_ENDPOINT}/face/v1.2/detectLivenesswithVerify-sessions/<session-id>" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}"

Ausführen anderer Gesichtsvorgänge nach der Liveness-Erkennung

Optionalerweise können Sie nach der Überprüfung der Lebendigkeit zusätzliche Gesichtsvorgänge ausführen, z. B. eine Gesichtsanalyse (zum Abrufen von Gesichtsattributen) und Gesichtsidentitätsvorgänge.

Legen Sie den enableSessionImage Parameter auf true während des Schritts zur Sitzungserstellung fest.
Extrahieren Sie sessionImageId aus dem Schritt Session-Get-Result.
Laden Sie das Sitzungsbild (referenziert in Lebendigkeitssitzungsvorgänge – Abrufen des Sitzungsbilds) herunter, oder verwenden Sie sessionImageId im Vorgang Über Sitzungsimage-ID-API erkennen, um mit anderen Gesichtsanalyse- oder Gesichtserkennungsvorgängen fortzufahren. Weitere Informationen zu diesen Vorgängen finden Sie unter Gesichtserkennungskonzepte und Gesichtserkennungskonzepte.

Supportoptionen

Zusätzlich zur Verwendung der wichtigsten Supportoptionen für Foundry Tools können Sie Ihre Fragen auch im Abschnitt "Probleme " des SDK-Repositorys posten.

Informationen zum Integrieren der Liveness-Lösung in Ihre vorhandene Anwendung finden Sie in der Azure Vision SDK-Referenz.

Weitere Informationen zu den verfügbaren Funktionen zur Orchestrierung der Liveness-Lösung finden Sie in der REST-API-Referenz für die Sitzung.

Liveness-Sitzungsvorgänge

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-24

Freigeben über

Tutorial: Erkennen von Face Liveness

Voraussetzungen

Vorbereiten der Front-End-Anwendung

Durchführen der Liveness-Erkennung

Durchführen der Liveness-Erkennung mit Gesichtsüberprüfung

Schritt 1 : Auswählen eines Referenzbilds

Schritt 2: Einrichtung der Orchestrierung von Lebendigkeit mit Überprüfung

Ausführen anderer Gesichtsvorgänge nach der Liveness-Erkennung

Supportoptionen

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen