Liveness Session Operations - Create Liveness With Verify Session

サービス:

Azure AI Services

API バージョン:

v1.2-preview.1

検証を使用して新しいライブネス セッションを作成します。 クライアント デバイスは、/detectLivenessWithVerify/singleModal 呼び出し中に VerifyImage を送信します。
セッションは、開発者がリソースへのフル アクセスを許可せずにライブネス検出のみを実行するようにクライアント デバイスを承認するクライアント デバイス シナリオに最適です。 作成されたセッションの有効期間は限られており、アクセスが期限切れになる前にクライアントが目的のアクションを実行することを承認するだけです。

アクセス許可に含まれるもの...

• • 最大 3 回の再試行で /detectLivenessWithVerify/singleModal を呼び出す機能。
  • トークンの有効期間は 10 分です。

手記

• • クライアント アクセスは、セッションの検証を使用してライブネスの削除操作を使用してセッションを削除することで取り消すことができます。
  • 結果を取得するには、Get Liveness With Verify Session を使用します。
  • クライアントがリソースに対して行った個々の要求を監査するには、List Liveness With Verify Session Audit Entries を使用します。

代替オプション: クライアント デバイスは、/detectLivenessWithVerify/singleModal 呼び出し中に VerifyImage を送信します。

手記

クライアントが予想される VerifyImage を送信していることを検証するために、追加の対策を講じておく必要があります。

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

URI パラメーター

名前	/	必須	型	説明
apiVersion	path	True	string	API バージョン
endpoint	path	True	string uri	サポートされている Cognitive Services エンドポイント (プロトコルとホスト名。例: https://{resource-name}.cognitiveservices.azure.com)。

要求本文

名前	必須	型	説明
livenessOperationMode	True	LivenessOperationMode	クライアントが従う必要があるライブネス モードの種類。
authTokenTimeToLiveInSeconds		integer	セッションが続く秒数。 範囲は 60 ~ 86400 秒です。 既定値は 600 です。
deviceCorrelationId		string	各エンド ユーザー デバイスごとの一意の Guid。 これはレート制限と反ハンマーを提供するためです。 この要求で 'deviceCorrelationIdSetInClient' が true の場合、この 'deviceCorrelationId' は null である必要があります。
deviceCorrelationIdSetInClient		boolean	クライアントが Vision SDK を介して独自の 'deviceCorrelationId' を設定できるかどうかを指定します。 既定値は false で、この要求本文で 'deviceCorrelationId' を設定する必要があります。
enableSessionImage		boolean	セッション イメージを格納するかどうか。
livenessSingleModalModel		LivenessModel	ライブネス分類に使用されるモデル バージョン。 これは省略可能なパラメーターであり、これが指定されていない場合は、サポートされている最新のモデル バージョンが選択されます
returnVerifyImageHash		boolean	検証イメージ ハッシュを返すかどうか。
sendResultsToClient		boolean	"200 - 成功" 応答本文をクライアントに送信することを許可するかどうか。これは、セキュリティ上の理由から望ましくない可能性があります。 既定値は false で、クライアントは '204 - NoContent' の空の本文応答を受け取ります。 選択に関係なく、Session GetResult を呼び出すと、常に応答本文が含まれるので、ビジネス ロジックを実装できます。
verifyConfidenceThreshold		number	顔検証の信頼度のしきい値。

応答

名前	型	説明
200 OK	CreateLivenessWithVerifySessionResult	呼び出しが成功すると、クライアント デバイスのセッションが作成され、限られた目的と時間のためにクライアント アプリケーションで使用するための承認トークンが提供されます。
Other Status Codes	FaceErrorResponse	予期しないエラー応答。 ヘッダー x-ms-error-code: string

セキュリティ

Ocp-Apim-Subscription-Key

Azure AI Face サブスクリプションの秘密鍵。

型: apiKey
/: header

AADToken

Azure Active Directory OAuth2 フロー

型: oauth2
フロー: accessCode
Authorization URL (承認 URL): https://api.example.com/oauth2/authorize
Token URL (トークン URL): https://api.example.com/oauth2/token

スコープ

名前	説明
https://cognitiveservices.azure.com/.default

例

Create LivenessWithVerify Session

要求のサンプル

HTTP

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

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

応答のサンプル

状態コード:

200

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

定義

名前	説明
CreateLivenessWithVerifySessionJsonContent	検証セッションを使用してライブネスを作成するための要求。
CreateLivenessWithVerifySessionResult	検証イメージを指定して作成を検証するライブネス セッションの応答。
FaceError	エラー オブジェクト。 Face サービスによって返されるエラー コードとメッセージの詳細については、次のリンクを参照してください: https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	エラーの詳細を含む応答。
FaceRectangle	顔が見つかる四角形。
LivenessModel	ライブネス分類に使用されるモデル バージョン。
LivenessOperationMode	クライアントのエンド ユーザー エクスペリエンスを促進するライブネス操作モード。
LivenessWithVerifyImage	検証用の顔の詳細。
QualityForRecognition	認識用の画像の品質を示します。

CreateLivenessWithVerifySessionJsonContent

検証セッションを使用してライブネスを作成するための要求。

名前	型	規定値	説明
authTokenTimeToLiveInSeconds	integer	600	セッションが続く秒数。 範囲は 60 ~ 86400 秒です。 既定値は 600 です。
deviceCorrelationId	string		各エンド ユーザー デバイスごとの一意の Guid。 これはレート制限と反ハンマーを提供するためです。 この要求で 'deviceCorrelationIdSetInClient' が true の場合、この 'deviceCorrelationId' は null である必要があります。
deviceCorrelationIdSetInClient	boolean		クライアントが Vision SDK を介して独自の 'deviceCorrelationId' を設定できるかどうかを指定します。 既定値は false で、この要求本文で 'deviceCorrelationId' を設定する必要があります。
enableSessionImage	boolean		セッション イメージを格納するかどうか。
livenessOperationMode	LivenessOperationMode		クライアントが従う必要があるライブネス モードの種類。
livenessSingleModalModel	LivenessModel		ライブネス分類に使用されるモデル バージョン。 これは省略可能なパラメーターであり、これが指定されていない場合は、サポートされている最新のモデル バージョンが選択されます
returnVerifyImageHash	boolean		検証イメージ ハッシュを返すかどうか。
sendResultsToClient	boolean		"200 - 成功" 応答本文をクライアントに送信することを許可するかどうか。これは、セキュリティ上の理由から望ましくない可能性があります。 既定値は false で、クライアントは '204 - NoContent' の空の本文応答を受け取ります。 選択に関係なく、Session GetResult を呼び出すと、常に応答本文が含まれるので、ビジネス ロジックを実装できます。
verifyConfidenceThreshold	number		顔検証の信頼度のしきい値。

CreateLivenessWithVerifySessionResult

検証イメージを指定して作成を検証するライブネス セッションの応答。

名前	型	説明
authToken	string	クライアント アプリケーションで実行されている Vision SDK の認証を提供するベアラー トークン。 このベアラー トークンには、必要なアクションのみを実行するアクセス許可が制限されており、TTL 時間が経過すると有効期限が切れます。 監査も可能です。
sessionId	string	作成されたセッションの一意のセッション ID。 作成されてから 48 時間後に有効期限が切れるか、対応するセッション DELETE 操作を使用してすぐに削除される可能性があります。
verifyImage	LivenessWithVerifyImage	検証用の顔の詳細。

FaceError

エラー オブジェクト。 Face サービスによって返されるエラー コードとメッセージの詳細については、次のリンクを参照してください: https://aka.ms/face-error-codes-and-messages。

名前	型	説明
code	string	サーバー定義の一連のエラー コードの 1 つ。
message	string	エラーの人間が判読できる表現。

FaceErrorResponse

エラーの詳細を含む応答。

名前	型	説明
error	FaceError	エラー オブジェクト。

FaceRectangle

顔が見つかる四角形。

名前	型	説明
height	integer	四角形の高さ (ピクセル単位)。
left	integer	画像から四角形の左端までの距離 (ピクセル単位)。
top	integer	画像が四角形の上端までの場合の上端からの距離 (ピクセル単位)。
width	integer	四角形の幅 (ピクセル単位)。

LivenessModel

ライブネス分類に使用されるモデル バージョン。

名前	型	説明
2022-10-15-preview.04	string
2023-12-20-preview.06	string

LivenessOperationMode

クライアントのエンド ユーザー エクスペリエンスを促進するライブネス操作モード。

名前	型	説明
Passive	string	ユーザーからの追加のアクションを必要としないパッシブライブネス手法を利用します。 最適なパフォーマンスを得るには、通常の屋内照明と高い画面輝度が必要です。 したがって、このモードは運用エンベロープが狭く、エンドユーザーが明るい照明条件である必要があるシナリオには適していません。 注: これは Mobile (iOS および Android) ソリューションでサポートされている唯一のモードです。
PassiveActive	string	このモードでは、ユーザーの協力を必要とするハイブリッドパッシブまたはアクティブなライブネス手法を利用します。 これは、最適でない照明条件下でのみアクティブなモーションを必要とするように最適化されています。 パッシブ モードとは異なり、このモードには照明の制限がないため、より広範な運用エンベロープが提供されます。 このモードは、Web ベースのソリューションでパッシブ モードの運用エンベロープを妨げるブラウザーで使用できる自動画面の明るさ制御がないため、Web ベースのソリューションで推奨されます。

LivenessWithVerifyImage

検証用の顔の詳細。

名前	型	説明
faceRectangle	FaceRectangle	比較画像の分類が行われた顔領域。
qualityForRecognition	QualityForRecognition	認識のための顔画像の品質。

QualityForRecognition

認識用の画像の品質を示します。

名前	型	説明
high	string	高品質。
low	string	低品質。
medium	string	中品質。