Compartilhar via

Tutorial: detectar atividade em rostos

Saiba como integrar a detecção de atividade facial ao fluxo de trabalho usando a lógica do lado do servidor e os aplicativos cliente de front-end complementares.

Dica

Para obter informações gerais sobre a detecção de vivacidade facial, consulte o guia conceitual.

Neste tutorial, você aprenderá a executar um aplicativo de front-end com um servidor de aplicação para realizar a detecção de vivacidade, opcionalmente adicionando verificação facial, em várias plataformas e idiomas.

Importante

Os SDKs do cliente de Detecção Facial para atividade são um recurso fechado. Solicite acesso ao recurso de atividade preenchendo o formulário de admissão de Reconhecimento Facial. Quando sua assinatura do Azure receber acesso, você poderá baixar o SDK da atividade de Detecção Facial.

Pré-requisitos

  • Assinatura do Azure – Criar uma gratuitamente
  • Sua conta do Azure deve ter a função Colaborador dos Serviços Cognitivos atribuída para que você concorde com os termos e condições da IA responsável e crie um recurso. Para que essa função seja atribuída à sua conta, siga as etapas descritas na documentação Atribuir funções ou entre em contato com o administrador.
  • Depois de obter sua assinatura do Azure, crie um recurso da Detecção Facial no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
    • Você precisa da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo ao serviço de Detecção Facial.
  • Acesso aos artefatos restritos necessários para o SDK do Cliente de Detecção Facial da Visão de IA do Azure para Dispositivo Móvel (IOS e Android) e Web.
  • Familiaridade com o recurso de atividade de Detecção Facial. Consulte o guia conceitual.

Dica

Depois de concluir os pré-requisitos, você pode experimentar a experiência de vivacidade do iOS na iOS App Store, a experiência de vivacidade do Android na Google Play e a experiência de vivacidade da Web do Vision Studio. Além disso, você também pode criar e executar um exemplo de front-end completo (no iOS, Android ou Web) na seção Exemplos .

Preparar o aplicativo de front-end

Fornecemos SDKs em vários idiomas para simplificar a integração com seu aplicativo de front-end. Consulte o README do SDK escolhido abaixo para integrar a interface do usuário e o código necessário.

Importante

Cada SDK de front-end requer acesso a um ativo fechado para compilar com êxito. As instruções sobre como configurar isso são mencionadas abaixo.

Para o Swift iOS:

Para Kotlin/Java Android:

Para JavaScript Web:

Depois de integrado ao seu aplicativo front-end, o SDK iniciará a câmera, guiará o usuário para ajustar a posição, comporá o payload de vivacidade e o enviará ao serviço de Face da IA do Azure para processamento.

Monitore a seção Versões do repositório para novas atualizações de versão do SDK e habilite alertas de atualização de dependência automatizados, por exemplo, GitHub Dependabot (para repositórios github) ou Renovar (GitHub, GitLab, Bitbucket, Azure Repos).

Executar a detecção de atividade

As etapas de alto nível envolvidas na orquestração da vivacidade são ilustradas abaixo:

Diagrama do fluxo de trabalho de atividade na Detecção Facial da IA do Azure.

  1. O aplicativo front-end inicia a verificação de atividade e notifica o servidor de aplicativos.

  2. O servidor de aplicativos cria uma nova sessão de atividade com o Serviço de Detecção Facial da IA do Azure. O serviço cria uma sessão ativa e responde com um token de autorização de sessão. Mais informações sobre cada parâmetro de solicitação envolvido na criação de uma sessão de atividade são referenciadas na Operação da Sessão de Criação de Atividade.

    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()}");

    Um exemplo do corpo da resposta:

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

  3. O servidor de aplicativos fornece o token de autorização de sessão para o aplicativo front-end.

  4. O aplicativo front-end usa o token de autorização de sessão para iniciar o detector de atividade facial, que iniciará o fluxo de atividade.

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

  5. O SDK então inicia a câmera, orienta o usuário a se posicionar corretamente e prepara a carga útil para chamar o ponto de extremidade do serviço de detecção de atividade.

  6. O SDK chama o serviço de Detecção Facial da Visão de IA do Azure para executar a detecção de atividade. Depois que o serviço responder, o SDK notificará o aplicativo front-end de que a verificação de atividade foi concluída. Observação: a resposta do serviço não conterá a decisão de vivacidade, e isso precisará ser consultado no servidor do aplicativo.

  7. O aplicativo front-end retransmite a conclusão da verificação de atividade para o servidor de aplicativos.

  8. O servidor de aplicativos agora pode consultar o resultado da detecção de atividade do serviço de Detecção Facial da Visão de IA do 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()}");
}

    Um exemplo do corpo da resposta:

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

  9. O servidor de aplicativos pode excluir a sessão depois que todos os resultados da sessão tiverem sido consultados.

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

Realizar detecção de atividade com verificação facial

A combinação da verificação facial com a detecção de atividade permite a verificação biométrica de uma determinada pessoa suspeita com uma garantia adicional de que ela está fisicamente presente no sistema.

Diagrama do fluxo de trabalho de verificação de atividade com a Detecção Facial da IA do Azure.

Há duas partes para integrar a vivacidade com a verificação:

Etapa 1 – Selecionar uma imagem de referência

Siga as dicas listadas nos requisitos de composição para cenários de verificação de ID para garantir que suas imagens de entrada forneçam os resultados de reconhecimento mais precisos.

Etapa 2 - Configure a orquestração da vivacidade com verificação.

As etapas de alto nível envolvidas na orquestração de verificação com atividade são ilustradas abaixo:

  1. Forneça a imagem de referência da verificação através de um dos dois métodos a seguir:

    • O servidor de aplicativos fornece a imagem de referência ao criar a sessão de atividade. Mais informações sobre cada parâmetro de solicitação envolvido na criação de uma sessão de atividade com verificação são referenciadas em Atividade com operação de criação de sessão de verificação.

      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()}");

      Um exemplo do corpo da resposta:

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

    • O aplicativo front-end fornece a imagem de referência ao inicializar os SDKs móveis. Não há suporte para esse cenário na solução web.

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

  2. O servidor de aplicativos agora pode consultar o resultado da verificação, além do resultado da atividade.

    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()}");
}

    Um exemplo do corpo da resposta:

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

  3. O servidor de aplicativos poderá excluir a sessão se você não precisar mais do resultado.

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

Executar outras operações faciais após a detecção de atividade

Opcionalmente, você pode fazer operações faciais posteriores após a verificação de vivacidade, como análise facial (para obter atributos faciais, por exemplo) e/ou operações de identidade facial.

  1. Para habilitar isso, você precisará definir o parâmetro "enableSessionImage" como "true" durante a etapaSession-Creation.
  2. Após a conclusão da sessão, você pode extrair o "sessionImageId" da etapa Session-Get-Result.
  3. Agora você pode baixar a imagem de sessão (referenciada na API de Operação de Imagem de Sessão da Atividade Get) ou fornecer a "sessionImageId" na operação Detectar da API de ID de Imagem de Sessão para continuar executando outras operações de análise facial ou de identidade facial. Para obter mais informações sobre essas operações, consulte conceitos de detecção facial e conceitos de Reconhecimento Facial.

Opções de suporte

Além de usar as principais opções de suporte dos serviços de IA do Azure, você também pode postar suas perguntas na seção de problemas do repositório do SDK.

Conteúdo relacionado

Para saber como integrar a solução de detecção de vivacidade ao aplicativo existente, consulte a referência do SDK do Azure AI Vision.

Para saber mais sobre os recursos disponíveis para orquestrar a solução de atividade, consulte a referência da API REST da sessão.

  • Last updated on