次の方法で共有

チュートリアル: 顔のライブネスを検出する

サーバー側ロジックとコンパニオン フロントエンド クライアント アプリケーションを使用して、顔のライブネス検出をワークフローに統合する方法について説明します。

ヒント

顔のライブネス検出に関する一般的な情報については、 概念ガイドを参照してください。

このチュートリアルでは、アプリ サーバーでフロントエンド アプリケーションを実行してライブネス検出を実行し、必要に応じてさまざまなプラットフォームと言語で 顔検証を追加する方法について説明します。

重要

ライブネス用の Face クライアント SDK は、限定的な機能です。 顔認識の取り込みフォームに入力して、ライブネス機能へのアクセスを要求する必要があります。 Azure サブスクリプションにアクセス権が付与されたら、Face ライブネスSDK をダウンロードできます。

前提条件

  • Azure サブスクリプション - 無料アカウントを作成します
  • 責任ある AI 用語に同意してリソースを作成するには、Azure アカウントに Cognitive Services 共同作成者 ロールが割り当てられている必要があります。 このロールをアカウントに割り当てるには、ロールの割り当てに関するドキュメントの手順に従うか、管理者にお問い合わせください。
  • Azure サブスクリプションを入手したら、Azure portal で Face リソースを作成し、キーとエンドポイントを取得します。 デプロイされたら、 [リソースに移動] を選択します。
    • アプリケーションを Face サービスに接続するには、作成したリソースのキーとエンドポイントが必要です。
  • Azure AI Vision Face Client SDK for Mobile (IOS および Android) と Web に必要なゲートアーティファクトへのアクセス。
  • 顔のライブネス検出機能を熟知していること。 概念ガイドを参照してください。

ヒント

前提条件を満たしたら、 iOS App Store の iOS Liveness エクスペリエンス、 Android Google Play ストア の Android Liveness エクスペリエンス、 Vision Studio の Web ライブネス エクスペリエンスを試すことができます。 さらに、[ サンプル ] セクションから完全なフロントエンド サンプル (iOS、Android、または Web) をビルドして実行することもできます。

フロントエンド アプリケーションを準備する

フロントエンド アプリケーションとの統合を簡略化するために、複数の言語で SDK を提供しています。 UI と必要なコードの両方を統合するには、以下の選択した SDK の README を参照してください。

重要

各フロントエンド SDK が正常にコンパイルするには、ゲートアセットへのアクセスが必要です。 これを設定する方法については、以下で説明します。

Swift iOS の場合:

Kotlin/Java Android の場合:

JavaScript Web の場合:

フロントエンド アプリケーションに統合されると、SDK はカメラを起動し、ユーザーの位置を調整し、ライブネス ペイロードを作成して、処理のために Azure AI Face サービスに送信するようにユーザーを誘導します。

リポジトリの リリース セクション で新しい SDK バージョンの更新を監視し、GitHub Dependabot (GitHub リポジトリの場合) やリフォーム (GitHub、GitLab、Bitbucket、Azure Repos) などの依存関係の自動更新アラートを有効にします。

ライブネス検出を実行する

ライブネス オーケストレーションに関連する大まかなステップを次に示します：

Azure AI Face のライブネス ワークフローの図。

  1. フロントエンド アプリケーションがライブネス チェックを開始し、アプリ サーバーに通知します。

  2. アプリ サーバーは、Azure AI Face Service との新しいライブネス セッションを作成します。 サービスは ライブネス-セッション を作成し、セッション-認可-トークン で応答します。 ライブネス セッションの作成に関連する各要求パラメーターの詳細については、ライブネス セッションの作成操作に関する情報を参照してください。

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

    応答の本文の例:

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

  3. アプリ サーバーは、フロントエンド アプリケーションに session-authorization-token を返します。

  4. フロントエンド アプリケーションは、セッション認証トークンを使用して、ライブネス フローを開始する顔のライブネス検出を開始します。

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

  5. その後、SDK はカメラを起動し、ユーザーが正しく配置するようにガイドした後、ライブネス検出サービス エンドポイントを呼び出すペイロードを準備します。

  6. SDK は、Azure AI Vision Face サービスを呼び出して、ライブネス検出を実行します。 サービスが応答すると、SDK は、ライブネス チェックが完了したことをフロントエンド アプリケーションに通知します。 注: サービス応答にはライブネスの決定が含まれていないので、これはアプリ サーバーからクエリを実行する必要があります。

  7. フロントエンド アプリケーションは、ライブネス チェックの完了をアプリ サーバーに中継します。

  8. アプリ サーバーは、Azure AI Vision Face サービスからのライブネス検出結果をクエリできるようになりました。

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

    応答の本文の例:

    {
    "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. すべてのセッション結果が照会されたら、アプリ サーバーはセッションを削除できます。

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

顔検証を使用してライブネス検出を実行する

顔検証とライブネス検出を組み合わせることで、特定の関心のあるユーザーの生体認証検証が可能になり、ユーザーがシステムに物理的に存在することが保証されます。

Azure AI Face の顔認証によるライブネス ワークフローの図。

ライブネスと検証の統合には、次の 2 つの部分があります：

手順 1 - 参照イメージを選択する

ID 検証シナリオの構成要件に記載されているヒントに従って、入力画像が最も正確な認識結果を得られるようにします。

手順 2 - 検証を使用して、ライブネスのオーケストレーションを設定します。

検証オーケストレーションでのライブネスに関連する大まかなステップを次に示します：

  1. 次の 2 つの方法のいずれかを使って、検証の参照画像を提供します。

    • アプリ サーバーは、ライブネス セッションの作成時に参照イメージを提供します。 検証を伴うライブネス セッションの作成に関連する各要求パラメーターの詳細については、検証を伴うライブネス セッションの作成操作に関する情報を参照してください。

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

      応答の本文の例:

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

    • フロントエンド アプリケーションは、モバイル SDK を初期化するときに参照イメージを提供します。 このシナリオは、Web ソリューションではサポートされていません。

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

  2. アプリ サーバーは、ライブネスの結果に加えて、検証結果のクエリを実行できるようになりました。

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

    応答の本文の例:

    {
    "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. 結果が不要な場合、アプリ サーバーはセッションを削除できます。

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

ライブネス検出後に顔に関連する他の操作を実行する

必要に応じて、顔分析 (顔属性を取得する場合など) や顔 ID 操作など、ライブネス チェック後にさらに顔操作を実行できます。

  1. これを有効にするには、 Session-Creation の手順で "enableSessionImage" パラメーターを "true" に設定する必要があります。
  2. セッションが完了したら、Session -Get-Result ステップから "sessionImageId" を抽出できます。
  3. セッション イメージをダウンロードするか ( Liveness Get Session Image Operation API で参照)、またはセッション イメージ ID の検出 API 操作で "sessionImageId" を指定して、他の顔分析または顔 ID 操作を引き続き実行できるようになりました。 これらの操作の詳細については、「 顔検出の概念 」と 「顔認識の概念」を参照してください。

サポート オプション

主要な Azure AI サービスサポート オプションを使用するだけでなく、SDK リポジトリの 問題 セクションに質問を投稿することもできます。

関連するコンテンツ

Liveness ソリューションを既存のアプリケーションに統合する方法については、Azure AI Vision SDK リファレンスを参照してください。

ライブネス ソリューションのオーケストレーションを行うために使用できる機能について詳しくは、Session REST API リファレンスを参照してください。