Liveness Session Operations - Create Liveness With Verify Session

參考

服務:: Azure AI Services

API 版本:: v1.2-preview.1

使用驗證建立新的活躍度會話。用戶端裝置會在 /detectLivenessWithVerify/singleModal 呼叫期間提交 VerifyImage。
會話最適合用於用戶端裝置案例，開發人員想要授權用戶端裝置只執行即時偵測，而不授與其資源的完整存取權。建立的會話具有有限的存留期，而且只會授權用戶端在存取過期之前執行所需的動作。

權限包括...

- 能夠呼叫 /detectLivenessWithVerify/singleModal，最多 3 次重試。
- 令牌存留期為10分鐘。

注意

- 您可以使用刪除即時性與驗證工作階段作業來撤銷用戶端存取權。
- 若要擷取結果，請使用取得 Liveness With Verify Session。
- 若要稽核用戶端已對資源提出的個別要求，請使用清單即時性與驗證會話稽核專案。

替代選項：客戶端裝置在 /detectLivenessWithVerify/singleModal 呼叫期間提交 VerifyImage。

注意

應採取額外的措施來驗證用戶端是否正在傳送預期的 VerifyImage。

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

URI 參數

名稱	位於	必要	類型	Description
apiVersion	path	True	string	API 版本
endpoint	path	True	string uri	支持的認知服務端點（通訊協定和主機名，例如：https://{resource-name}.cognitiveservices.azure.com）。

要求本文

名稱	必要	類型	Description
livenessOperationMode	True	LivenessOperationMode	用戶端應遵循的活躍度模式類型。
authTokenTimeToLiveInSeconds		integer	會話應該持續到的秒數。範圍是 60 到 86400 秒。預設值為 600。
deviceCorrelationId		string	每個終端用戶裝置的唯一 Guid。這是提供速率限制和反錘擊。如果此要求中的 'deviceCorrelationIdSetInClient' 為 true，此 'deviceCorrelationId' 必須為 Null。
deviceCorrelationIdSetInClient		boolean	是否允許用戶端透過視覺 SDK 設定自己的『deviceCorrelationId』。默認值為 false，且 'deviceCorrelationId' 必須在此要求本文中設定。
enableSessionImage		boolean	是否儲存會話映像。
livenessSingleModalModel		LivenessModel	用於活躍度分類的模型版本。這是選擇性參數，如果未指定，則會選擇最新的支援模型版本
returnVerifyImageHash		boolean	是否傳回驗證影像哈希。
sendResultsToClient		boolean	是否允許將『200 - Success』回應本文傳送至客戶端，基於安全性考慮，這可能是不想要的。默認值為 false，用戶端會收到 '204 - NoContent' 空本文回應。不論選擇為何，呼叫 Session GetResult 一律會包含回應本文，以便實作商業規則。
verifyConfidenceThreshold		number	臉部驗證信賴閾值。

回應

名稱	類型	Description
200 OK	CreateLivenessWithVerifySessionResult	成功的呼叫會建立用戶端裝置的會話，並提供授權令牌供用戶端應用程式在有限的用途和時間使用。
Other Status Codes	FaceErrorResponse	未預期的錯誤回應。標題 x-ms-error-code: string

名稱

類型

Description

200 OK

CreateLivenessWithVerifySessionResult

成功的呼叫會建立用戶端裝置的會話，並提供授權令牌供用戶端應用程式在有限的用途和時間使用。

Other Status Codes

FaceErrorResponse

未預期的錯誤回應。

標題

x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

Azure AI 臉部訂用帳戶的秘密密鑰。

類型: apiKey
位於: header

AADToken

Azure Active Directory OAuth2 流程

類型: oauth2
Flow: accessCode
授權 URL: https://api.example.com/oauth2/authorize
權杖 URL: https://api.example.com/oauth2/token

範圍

名稱	Description
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"
}

定義

名稱	Description
CreateLivenessWithVerifySessionJsonContent	使用驗證會話建立活躍度的要求。
CreateLivenessWithVerifySessionResult	使用提供的驗證映像來驗證建立的即時性會話回應。
FaceError	error 物件。如需臉部服務所傳回錯誤碼和訊息的完整詳細數據，請參閱下列連結：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含錯誤詳細數據的回應。
FaceRectangle	可以在其中找到臉部的矩形。
LivenessModel	用於活躍度分類的模型版本。
LivenessOperationMode	可驅動客戶端用戶體驗的活躍度作業模式。
LivenessWithVerifyImage	驗證臉部的詳細數據。
QualityForRecognition	表示影像的辨識品質。

CreateLivenessWithVerifySessionJsonContent

使用驗證會話建立活躍度的要求。

名稱	類型	預設值	Description
authTokenTimeToLiveInSeconds	integer	600	會話應該持續到的秒數。範圍是 60 到 86400 秒。預設值為 600。
deviceCorrelationId	string		每個終端用戶裝置的唯一 Guid。這是提供速率限制和反錘擊。如果此要求中的 'deviceCorrelationIdSetInClient' 為 true，此 'deviceCorrelationId' 必須為 Null。
deviceCorrelationIdSetInClient	boolean		是否允許用戶端透過視覺 SDK 設定自己的『deviceCorrelationId』。默認值為 false，且 'deviceCorrelationId' 必須在此要求本文中設定。
enableSessionImage	boolean		是否儲存會話映像。
livenessOperationMode	LivenessOperationMode		用戶端應遵循的活躍度模式類型。
livenessSingleModalModel	LivenessModel		用於活躍度分類的模型版本。這是選擇性參數，如果未指定，則會選擇最新的支援模型版本
returnVerifyImageHash	boolean		是否傳回驗證影像哈希。
sendResultsToClient	boolean		是否允許將『200 - Success』回應本文傳送至客戶端，基於安全性考慮，這可能是不想要的。默認值為 false，用戶端會收到 '204 - NoContent' 空本文回應。不論選擇為何，呼叫 Session GetResult 一律會包含回應本文，以便實作商業規則。
verifyConfidenceThreshold	number		臉部驗證信賴閾值。

CreateLivenessWithVerifySessionResult

使用提供的驗證映像來驗證建立的即時性會話回應。

名稱	類型	Description
authToken	string	持有人令牌，可為在用戶端應用程式上執行的視覺 SDK 提供驗證。此持有人令牌的許可權有限，只能執行必要的動作，並在TTL時間之後到期。它也可稽核。
sessionId	string	所建立會話的唯一會話標識符。它會在建立后 48 小時到期，或使用對應的工作階段 DELETE 作業更快刪除。
verifyImage	LivenessWithVerifyImage	驗證臉部的詳細數據。

FaceError

error 物件。如需臉部服務所傳回錯誤碼和訊息的完整詳細數據，請參閱下列連結：https://aka.ms/face-error-codes-and-messages。

名稱	類型	Description
code	string	其中一組伺服器定義的錯誤碼。
message	string	錯誤的人類可讀取表示法。

FaceErrorResponse

包含錯誤詳細數據的回應。

名稱	類型	Description
error	FaceError	error 物件。

FaceRectangle

可以在其中找到臉部的矩形。

名稱	類型	Description
height	integer	矩形的高度，以像素為單位。
left	integer	如果影像到矩形左邊緣的距離，以像素為單位。
top	integer	影像到矩形上邊緣的距離，以像素為單位。
width	integer	矩形的寬度，以像素為單位。

LivenessModel

用於活躍度分類的模型版本。

名稱	類型	Description
2022-10-15-preview.04	string
2023-12-20-preview.06	string

LivenessOperationMode

可驅動客戶端用戶體驗的活躍度作業模式。

名稱	類型	Description
Passive	string	利用被動活躍技術，不需要用戶採取任何其他動作。需要一般室內光源和高螢幕亮度，以獲得最佳效能。因此，此模式具有狹窄的操作信封，不適用於需要終端用戶處於明亮光源條件的案例。注意：這是行動裝置（iOS 和 Android）解決方案唯一支援的模式。
PassiveActive	string	此模式會使用需要使用者合作的混合式被動或主動活躍技術。它已優化，只有在次佳的光源條件下才需要主動動作。不同於被動模式，此模式沒有照明限制，因此提供更廣泛的操作信封。由於瀏覽器上缺乏自動螢幕亮度控制，因而阻礙被動模式在 Web 解決方案上的操作信封，所以此模式較好。

LivenessWithVerifyImage

驗證臉部的詳細數據。

名稱	類型	Description
faceRectangle	FaceRectangle	建立比較影像分類的臉部區域。
qualityForRecognition	QualityForRecognition	用於辨識的臉部影像品質。

QualityForRecognition

表示影像的辨識品質。

名稱	類型	Description
high	string	高品質。
low	string	品質低。
medium	string	中等品質。

共用方式為

Liveness Session Operations - Create Liveness With Verify Session

URI 參數

要求本文

回應

安全性

Ocp-Apim-Subscription-Key

AADToken

範圍

範例

Create LivenessWithVerify Session

範例要求

範例回覆

定義

CreateLivenessWithVerifySessionJsonContent

CreateLivenessWithVerifySessionResult

FaceError

FaceErrorResponse

FaceRectangle

LivenessModel

LivenessOperationMode

LivenessWithVerifyImage

QualityForRecognition

其他資源