Liveness Session Operations - Create Liveness Session

參考

服務:: Azure AI Services

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

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

權限包括...

- 最多 3 次重試呼叫 /detectLiveness/singleModal 的能力。
- 令牌存留期為10分鐘。

注意

您可以使用刪除 Liveness 工作階段作業來刪除工作階段來撤銷用戶端存取權。若要擷取結果，請使用取得 Liveness 會話。若要稽核用戶端已對資源提出的個別要求，請使用列出 Liveness 會話稽核專案。

POST {endpoint}/face/{apiVersion}/detectLiveness/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	用於活躍度分類的模型版本。這是選擇性參數，如果未指定，則會選擇最新的支援模型版本
sendResultsToClient		boolean	是否允許將『200 - Success』回應本文傳送至客戶端，基於安全性考慮，這可能是不想要的。默認值為 false，用戶端會收到 '204 - NoContent' 空本文回應。不論選擇為何，呼叫 Session GetResult 一律會包含回應本文，以便實作商業規則。

回應

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

名稱

類型

Description

200 OK

CreateLivenessSessionResult

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

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

範例要求

HTTP

POST {endpoint}/face/v1.2-preview.1/detectLiveness/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
CreateLivenessSessionContent	建立即時會話的要求模型。
CreateLivenessSessionResult	即時會話建立的回應。
FaceError	error 物件。如需臉部服務所傳回錯誤碼和訊息的完整詳細數據，請參閱下列連結：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含錯誤詳細數據的回應。
LivenessModel	用於活躍度分類的模型版本。
LivenessOperationMode	可驅動客戶端用戶體驗的活躍度作業模式。

CreateLivenessSessionContent

建立即時會話的要求模型。

名稱	類型	預設值	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		用於活躍度分類的模型版本。這是選擇性參數，如果未指定，則會選擇最新的支援模型版本
sendResultsToClient	boolean		是否允許將『200 - Success』回應本文傳送至客戶端，基於安全性考慮，這可能是不想要的。默認值為 false，用戶端會收到 '204 - NoContent' 空本文回應。不論選擇為何，呼叫 Session GetResult 一律會包含回應本文，以便實作商業規則。

CreateLivenessSessionResult

即時會話建立的回應。

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

FaceError

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

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

FaceErrorResponse

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

名稱	類型	Description
error	FaceError	error 物件。

LivenessModel

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

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

LivenessOperationMode

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

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

共用方式為

Liveness Session Operations - Create Liveness Session

URI 參數

要求本文

回應

安全性

Ocp-Apim-Subscription-Key

AADToken

範圍

範例

Create Liveness Session

範例要求

範例回覆

定義

CreateLivenessSessionContent

CreateLivenessSessionResult

FaceError

FaceErrorResponse

LivenessModel

LivenessOperationMode

其他資源