你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Liveness Session Operations - Create Liveness Session

参考

服务:: Azure AI Services

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

创建新的检测实时会话。
会话最适合客户端设备方案，开发人员希望授权客户端设备仅执行实时情况检测，而无需授予对其资源的完全访问权限。创建的会话的生存期有限，并且仅授权客户端在访问过期之前执行所需的操作。

权限包括...

- 能够调用 /detectLiveness/singleModal 进行最多 3 次重试。
- 令牌生存期为 10 分钟。

注意

可以通过使用“删除生存期会话”操作删除会话来撤销客户端访问权限。若要检索结果，请使用 Get Liveness 会话。若要审核客户端对资源发出的单个请求，请使用列表 Liveness 会话审核条目。

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

URI 参数

名称	在	必需	类型	说明
apiVersion	path	True	string	API 版本
endpoint	path	True	string uri	支持的认知服务终结点（协议和主机名，例如：https://{resource-name}.cognitiveservices.azure.com）。

请求正文

名称	必需	类型	说明
livenessOperationMode	True	LivenessOperationMode	客户端应遵循的生存模式类型。
authTokenTimeToLiveInSeconds		integer	会话应持续到的秒数。范围为 60 到 86400 秒。默认值为 600。
deviceCorrelationId		string	每个最终用户设备的唯一 Guid。这是提供速率限制和反锤击。如果此请求中为“deviceCorrelationIdSetInClient”，则此“deviceCorrelationId”必须为 null。
deviceCorrelationIdSetInClient		boolean	是否允许客户端通过 Vision SDK 设置自己的“deviceCorrelationId”。默认值为 false，并且必须在此请求正文中设置“deviceCorrelationId”。
enableSessionImage		boolean	是否存储会话映像。
livenessSingleModalModel		LivenessModel	用于实时分类的模型版本。这是一个可选参数，如果未指定此参数，则将选择最新的受支持的模型版本
sendResultsToClient		boolean	是否允许将“200 - Success”响应正文发送到客户端，这可能是出于安全原因而不需要的。默认值为 false，客户端将收到“204 - NoContent”空正文响应。无论选择什么，调用 Session GetResult 将始终包含一个响应正文，使业务逻辑得以实现。

响应

名称	类型	说明
200 OK	CreateLivenessSessionResult	成功的调用为客户端设备创建会话，并提供授权令牌供客户端应用程序用于有限目的和时间。
Other Status Codes	FaceErrorResponse	意外的错误响应。标头 x-ms-error-code: string

名称

类型

说明

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
流向: accessCode
授权 URL: https://api.example.com/oauth2/authorize
令牌 URL: https://api.example.com/oauth2/token

作用域

名称	说明
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"
}

定义

名称	说明
CreateLivenessSessionContent	用于创建实时会话的请求模型。
CreateLivenessSessionResult	实时会话创建响应。
FaceError	错误对象。有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含错误详细信息的响应。
LivenessModel	用于实时分类的模型版本。
LivenessOperationMode	用于驱动客户端最终用户体验的实时性操作模式。

CreateLivenessSessionContent

用于创建实时会话的请求模型。

名称	类型	默认值	说明
authTokenTimeToLiveInSeconds	integer	600	会话应持续到的秒数。范围为 60 到 86400 秒。默认值为 600。
deviceCorrelationId	string		每个最终用户设备的唯一 Guid。这是提供速率限制和反锤击。如果此请求中为“deviceCorrelationIdSetInClient”，则此“deviceCorrelationId”必须为 null。
deviceCorrelationIdSetInClient	boolean		是否允许客户端通过 Vision SDK 设置自己的“deviceCorrelationId”。默认值为 false，并且必须在此请求正文中设置“deviceCorrelationId”。
enableSessionImage	boolean		是否存储会话映像。
livenessOperationMode	LivenessOperationMode		客户端应遵循的生存模式类型。
livenessSingleModalModel	LivenessModel		用于实时分类的模型版本。这是一个可选参数，如果未指定此参数，则将选择最新的受支持的模型版本
sendResultsToClient	boolean		是否允许将“200 - Success”响应正文发送到客户端，这可能是出于安全原因而不需要的。默认值为 false，客户端将收到“204 - NoContent”空正文响应。无论选择什么，调用 Session GetResult 将始终包含一个响应正文，使业务逻辑得以实现。

CreateLivenessSessionResult

实时会话创建响应。

名称	类型	说明
authToken	string	持有者令牌，用于为客户端应用程序上运行的视觉 SDK 提供身份验证。此持有者令牌具有有限的权限，只能执行所需的操作，并在 TTL 时间后过期。它也是可审核的。
sessionId	string	创建会话的唯一会话 ID。它将在创建后 48 小时过期，或者使用相应的会话 DELETE 操作更快地删除。

FaceError

错误对象。有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。

名称	类型	说明
code	string	服务器定义的错误代码集之一。
message	string	错误的人工可读表示形式。

FaceErrorResponse

包含错误详细信息的响应。

名称	类型	说明
error	FaceError	错误对象。

LivenessModel

用于实时分类的模型版本。

名称	类型	说明
2022-10-15-preview.04	string
2023-12-20-preview.06	string

LivenessOperationMode

用于驱动客户端最终用户体验的实时性操作模式。

名称	类型	说明
Passive	string	利用被动实时技术，无需用户执行其他操作。需要正常的室内照明和高屏幕亮度，以获得最佳性能。因此，此模式具有较窄的操作信封，不适用于要求最终用户处于明亮照明条件的方案。注意：这是移动解决方案（iOS 和 Android）解决方案唯一受支持的模式。
PassiveActive	string	此模式利用需要用户合作的混合被动或主动实时技术。它经过优化，仅在欠佳的照明条件下需要主动运动。与被动模式不同，此模式没有照明限制，因此提供更广泛的操作信封。由于浏览器上缺少自动屏幕亮度控制，阻碍被动模式在基于 Web 的解决方案上的操作信封，此模式更可取于基于 Web 的解决方案。

通过

Liveness Session Operations - Create Liveness Session

URI 参数

请求正文

响应

安全性

Ocp-Apim-Subscription-Key

AADToken

作用域

示例

Create Liveness Session

示例请求

示例响应

定义

CreateLivenessSessionContent

CreateLivenessSessionResult

FaceError

FaceErrorResponse

LivenessModel

LivenessOperationMode

其他资源