Liveness Session Operations - Create Liveness Session

サービス:: Azure AI Services

API バージョン:: v1.2

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

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

- トークンの有効期間は 10 分です。

Note

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

POST {endpoint}/face/{apiVersion}/detectLiveness-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 (int32) minimum: 60 maximum: 86400	セッションが続く秒数。範囲は 60 ~ 86400 秒です。既定値は 600 です。
deviceCorrelationId		string	各エンドユーザーデバイスごとの一意の Guid。これはレート制限と反ハンマーを提供するためです。この要求で 'deviceCorrelationIdSetInClient' が true の場合、この 'deviceCorrelationId' は null である必要があります。
deviceCorrelationIdSetInClient		boolean	クライアントが Vision SDK を介して独自の 'deviceCorrelationId' を設定できるかどうかを指定します。既定値は false で、この要求本文で 'deviceCorrelationId' を設定する必要があります。
enableSessionImage		boolean	セッションイメージを格納するかどうか。
livenessModelVersion		LivenessModel	ライブネス分類に使用されるモデルバージョン。これは省略可能なパラメーターであり、これが指定されていない場合は、サポートされている最新のモデルバージョンが選択されます

応答

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

名前

型

説明

200 OK

LivenessSession

呼び出しが成功すると、クライアントデバイスのセッションが作成され、限られた目的と時間のためにクライアントアプリケーションで使用するための承認トークンが提供されます。

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 Liveness Session

要求のサンプル

HTTP

POST {endpoint}/face/v1.2/detectLiveness-sessions

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

応答のサンプル

状態コード:: 200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": []
  }
}

定義

名前	説明
CreateLivenessSessionContent	ライブネスセッションを作成するための要求モデル。
FaceError	エラーオブジェクト。 Face サービスによって返されるエラーコードとメッセージの詳細については、次のリンクを参照してください: https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	エラーの詳細を含む応答。
FaceRectangle	顔が見つかる四角形。
LivenessColorDecisionTarget	ライブネス分類に使用されるカラー画像のターゲット。
LivenessDecision	ライブネス分類の結果。
LivenessDecisionTargets	ライブネス分類に使用されるターゲット。
LivenessError	ライブネス分類のエラー。
LivenessModel	ライブネス分類に使用されるモデルバージョン。
LivenessOperationMode	クライアントのエンドユーザーエクスペリエンスを促進するライブネス操作モード。
LivenessResult	ライブネス分類の結果。
LivenessSession	ライブネス検出のセッション結果。
LivenessSessionAttempt	ライブネスセッションの試行。
LivenessSessionResults	ライブネスセッションの結果。
OperationState	セッションの現在の状態。

CreateLivenessSessionContent

Object

ライブネスセッションを作成するための要求モデル。

名前	型	規定値	説明
authTokenTimeToLiveInSeconds	integer (int32) minimum: 60 maximum: 86400	600	セッションが続く秒数。範囲は 60 ~ 86400 秒です。既定値は 600 です。
deviceCorrelationId	string		各エンドユーザーデバイスごとの一意の Guid。これはレート制限と反ハンマーを提供するためです。この要求で 'deviceCorrelationIdSetInClient' が true の場合、この 'deviceCorrelationId' は null である必要があります。
deviceCorrelationIdSetInClient	boolean		クライアントが Vision SDK を介して独自の 'deviceCorrelationId' を設定できるかどうかを指定します。既定値は false で、この要求本文で 'deviceCorrelationId' を設定する必要があります。
enableSessionImage	boolean		セッションイメージを格納するかどうか。
livenessModelVersion	LivenessModel		ライブネス分類に使用されるモデルバージョン。これは省略可能なパラメーターであり、これが指定されていない場合は、サポートされている最新のモデルバージョンが選択されます
livenessOperationMode	LivenessOperationMode		クライアントが従う必要があるライブネスモードの種類。

FaceError

Object

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

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

FaceErrorResponse

Object

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

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

FaceRectangle

Object

顔が見つかる四角形。

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

LivenessColorDecisionTarget

Object

ライブネス分類に使用されるカラー画像のターゲット。

名前	型	説明
faceRectangle	FaceRectangle	ライブネス分類が行われた顔領域。

LivenessDecision

列挙

ライブネス分類の結果。

値	説明
uncertain	アルゴリズムでは、ターゲットの顔を実際の顔またはスプーフィングとして分類できませんでした。
realface	このアルゴリズムでは、ターゲットの顔が実際の顔として分類されています。
spoofface	このアルゴリズムでは、ターゲットの顔がスプーフィングとして分類されています。

LivenessDecisionTargets

Object

ライブネス分類に使用されるターゲット。

名前	型	説明
color	LivenessColorDecisionTarget	ライブネス分類に使用されるカラー画像のターゲット。

LivenessError

Object

ライブネス分類のエラー。

名前	型	説明
code	string	エラーコード。
message	string	エラーメッセージ。
targets	LivenessDecisionTargets	ライブネス分類に使用されるターゲット。

LivenessModel

列挙

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

値	説明
2024-11-15

LivenessOperationMode

列挙

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

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

値

説明

Passive

ユーザーからの追加のアクションを必要としないパッシブライブネス手法を利用します。最適なパフォーマンスを得るには、通常の屋内照明と高い画面輝度が必要です。したがって、このモードは運用エンベロープが狭く、エンドユーザーが明るい照明条件である必要があるシナリオには適していません。注: これは Mobile (iOS および Android) ソリューションでサポートされている唯一のモードです。

PassiveActive

このモードでは、ユーザーの協力を必要とするハイブリッドパッシブまたはアクティブなライブネス手法を利用します。これは、最適でない照明条件下でのみアクティブなモーションを必要とするように最適化されています。パッシブモードとは異なり、このモードには照明の制限がないため、より広範な運用エンベロープが提供されます。このモードは、Web ベースのソリューションでパッシブモードの運用エンベロープを妨げるブラウザーで使用できる自動画面の明るさ制御がないため、Web ベースのソリューションで推奨されます。

LivenessResult

Object

ライブネス分類の結果。

名前	型	説明
digest	string	この要求のサーバー計算ダイジェスト。クライアントから報告されたダイジェストがサーバー計算ダイジェストと異なる場合、クライアントとサービスの間のメッセージ整合性が損なわれ、結果は信頼されません。詳細については、この値を活用してエンドツーエンドソリューションをセキュリティで保護する方法に関するガイドを参照してください。
livenessDecision	LivenessDecision	ターゲット顔のライブネス分類。
sessionImageId	string	セッション要求のイメージ ID。
targets	LivenessDecisionTargets	ライブネス分類に使用されるターゲット。