Esercitazione: Rilevare l’attività nei visi

Scopri come integrare il rilevamento della vivacità del viso nel tuo flusso di lavoro utilizzando la logica lato server e le applicazioni client front-end associate.

Suggerimento

Per informazioni generali sul rilevamento liveness del viso, vedere la guida concettuale.

In questa esercitazione imparerai come eseguire un'applicazione frontend con un server di applicazioni per eseguire il rilevamento della presenza. È anche possibile aggiungere la verifica del viso in diverse piattaforme e linguaggi.

Importante

Gli SDK del client Viso per il rilevamento liveness sono una funzionalità gestita. È necessario richiedere l'accesso alla funzionalità di attività compilando il modulo di acquisizione del riconoscimento del volto. Quando alla sottoscrizione Azure viene concesso l'accesso, è possibile scaricare Face Liveness SDK.

Prerequisiti

sottoscrizione Azure - Crearne una gratuitamente
L'account Azure deve avere un ruolo Cognitive Services Contributor in modo da poter accettare le condizioni di intelligenza artificiale responsabili e creare una risorsa. Per assegnare questo ruolo all'account, seguire la procedura descritta nella documentazione Assegnare ruoli oppure contattare l'amministratore.
Dopo aver creato la sottoscrizione di Azure, Creare una risorsa Viso nel portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
- La chiave e l'endpoint della risorsa creata saranno necessari per connettere l'applicazione al servizio Viso.
Accedere agli artefatti riservati necessari per Visione di Azure nel componente SDK client di Viso in Foundry Tools per dispositivi mobili (iOS e Android) e Web.
- Per iniziare, è necessario richiedere le funzionalità di Riconoscimento volto ad accesso limitato per ottenere l'accesso agli artefatti gestiti. Per altre informazioni, vedere la pagina Accesso limitato a Viso.
Familiarità con la funzionalità di rilevamento della vitalità del volto. Vedere la guida concettuale.

Suggerimento

Dopo aver completato i prerequisiti, è possibile provare l'esperienza liveness sulle piattaforme seguenti:

iOS: App Store per iOS: tocca la schermata dell'app 10 volte dopo l'installazione per abilitare la modalità sviluppatore.
Android: Google Play Store : tocca la schermata dell'app 10 volte dopo l'installazione per abilitare la modalità sviluppatore.
Web: provarlo direttamente in Vision Studio.

È anche possibile compilare ed eseguire un esempio front-end completo (iOS, Android o Web) dalla sezione Samples.

Preparare l'applicazione front-end

Gli SDK vengono forniti in più linguaggi per semplificare l'integrazione con l'applicazione front-end in uso. Per integrare sia l'interfaccia utente che il codice necessario, vedere README per l'SDK scelto nelle sezioni seguenti.

Importante

Ogni SDK front-end richiede l'accesso a una risorsa gestita per garantire una compilazione corretta. Per configurare questo accesso, vedere le istruzioni seguenti.

Per Swift iOS:

Artefatti: Azure Face UI SDK per iOS
Riferimento API: Riferimento AzureAIVisionFaceUI
Esempio: esempio iOS

Per Kotlin/Java Android:

Artefatti: Maven Central: com.azure:azure-ai-vision-face-ui
Riferimento API: Riferimento azure-ai-vision-face-ui
Esempio: esempio Android

Per JavaScript Web:

Artefatti: @azure/ai-vision-face-ui - npm
Riferimento API: Riferimento AzureAIVisionFaceUI
Esempio: esempio Web
Supporto framework: funziona con i framework più diffusi, ad esempio React (incluso Next.js), Vue.jse Angular.

Dopo l'integrazione nell'applicazione front-end, l'SDK avvia la fotocamera, assiste l'utente nella regolazione della posizione, compone il payload di attività e lo invia al servizio Viso di Azure per l'elaborazione.

Monitorare la sezione Versioni del repository per gli aggiornamenti delle nuove versione SDK e abilitare gli avvisi di aggiornamento delle dipendenze automatizzati, ad esempio GitHub Dependabot (per repository GitHub) o Renovate (GitHub, GitLab, Bitbucket, Azure Repos).

Eseguire il rilevamento dell'autenticità

I passaggi seguenti descrivono il processo di orchestrazione liveness:

L'applicazione front-end avvia il controllo dell'attività e invia una notifica al server app.

Il server app crea una nuova sessione di rilevamento liveness con il servizio Viso di Azure. Il servizio crea una sessione liveness e risponde con un token di autorizzazione sessione. Per altre informazioni su ogni parametro di richiesta coinvolto nella creazione di una sessione relativa al rilevamento liveness, vedere Operazione della sessione di creazione liveness.

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"
}'

Un esempio del corpo della risposta:

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

Il server app fornisce il token di autorizzazione della sessione all'applicazione front-end.

L'applicazione front-end usa il token di autorizzazione sessione per avviare il rilevatore liveness del viso che avvia il flusso di liveness.

    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)

L'SDK avvia la fotocamera, guida l'utente a posizionarsi correttamente e quindi prepara il payload per chiamare l'endpoint del servizio di liveness detection.
L'SDK chiama il servizio Azure Vision Face per eseguire il rilevamento di vivacità. Una volta che il servizio risponde, l'SDK avvisa l'applicazione front-end che il controllo di liveness è stato completato. Nota: la risposta del servizio non contiene la decisione liveness. È necessario eseguire query su queste informazioni dal server app.
L'applicazione front-end inoltra il completamento del controllo dell'attività al server app.

Il server app esegue una query per il risultato del rilevamento liveness dal servizio Viso di Visione di Azure.

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}"

Un esempio del corpo della risposta:

{
    "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
                        }
                        }
                    }
                }
            }
        ]
    }
}

Il server app elimina la sessione dopo che esegue una query su tutti i risultati della sessione.

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}"

Eseguire il rilevamento liveness mediante la verifica del viso

La combinazione della verifica del viso con il rilevamento liveness consente la verifica biometrica di una particolare persona di interesse, con la garanzia aggiuntiva della presenza fisica della persona nel sistema.

L'integrazione del rilevamento del liveness con la verifica prevede due parti:

Passaggio 1- Selezionare un'immagine di riferimento

Per ottenere i risultati di riconoscimento più accurati, seguire i suggerimenti elencati nei requisiti di composizione per gli scenari di verifica ID.

Passaggio 2: Configurare l'orchestrazione dell'autenticità liveness

I passaggi generali seguenti illustrano come orchestrare la liveness con la verifica:

Fornire l'immagine di riferimento di verifica usando uno dei due metodi seguenti:

Il server app fornisce l'immagine di riferimento durante la creazione della sessione relativa al rilevamento dell’attività. Per ulteriori informazioni su ciascun parametro di richiesta coinvolto nella creazione di una sessione di liveness con verifica, vedere 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"'

Un esempio del corpo della risposta:

{
    "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"
        }
        ]
    }
}

L'applicazione front-end fornisce l'immagine di riferimento durante l'inizializzazione degli SDK per dispositivi mobili. Questo scenario non è supportato nella soluzione Web.

    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.

Il server app ora può eseguire una query per il risultato della verifica oltre al risultato del rilevamento liveness.

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}"

Un esempio del corpo della risposta:

{
    "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"
            }
        ]
        }
    }

Il server app può eliminare la sessione se il risultato non è più necessario.

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}"

Eseguire altre operazioni sul viso dopo il rilevamento liveness

Facoltativamente, è possibile eseguire operazioni aggiuntive sul viso dopo il test di vivacità, come l'analisi facciale (per ottenere attributi facciali) e le operazioni di identificazione facciale.

Impostare il parametro enableSessionImage su true durante il passaggio Session-Creation.
Estrarre il sessionImageId dal passaggio Session-Get-Result.
Scaricare l'immagine della sessione (a cui si fa riferimento nell'API operazione dell'immagine sessione Ottieni liveness) oppure specificare l'operazione sessionImageIdnell'API Rileva dall'ID immagine della sessione per continuare con altre operazioni di analisi del viso o identità del viso. Per altre informazioni su queste operazioni, vedere Concetti relativi al rilevamento dei visi e Concetti relativi al riconoscimento dei volti.

Opzioni di supporto

Oltre a usare le opzioni di supporto principali Foundry Tools, puoi anche pubblicare le tue domande nella sezione issues del repository SDK.

Per informazioni su come integrare la soluzione di liveness nell'applicazione esistente, consulta la documentazione di riferimento per Azure Vision SDK.

Per altre informazioni sulle funzionalità disponibili per orchestrare la soluzione di liveness, vedere le informazioni di riferimento sull'API REST della sessione.

Operazioni sessione di rilevamento attività

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-12

Condividi tramite

Esercitazione: Rilevare l’attività nei visi

Prerequisiti

Preparare l'applicazione front-end

Eseguire il rilevamento dell'autenticità

Eseguire il rilevamento liveness mediante la verifica del viso

Passaggio 1- Selezionare un'immagine di riferimento

Passaggio 2: Configurare l'orchestrazione dell'autenticità liveness

Eseguire altre operazioni sul viso dopo il rilevamento liveness

Opzioni di supporto

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive