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

Face Recognition Operations - Identify From Person Directory

服务:

Azure AI Services

API 版本:

v1.2-preview.1

从人员目录 personIds 数组中查找特定查询人脸最接近的匹配项的 1 对多标识。
对于 faceIds 数组中的每个人脸，人脸识别将计算查询人脸与人员目录人员（由 personIds 给出）中所有人脸之间的相似性，并返回按相似性置信度排名的候选人人员。 使用包含一个元素“*”的数组传递 personId 可以在整个人员目录中执行该操作。

注意

• • 该算法允许在同一请求中独立识别多个人脸，但不超过 10 张人脸。
  • 每个人可以有多个人脸，但不超过 248 张人脸。
  • 更高的人脸图像质量意味着更好的识别精度。 请考虑高质量的人脸：正面、清晰和人脸大小为 200x200 像素（眼睛之间的 100 像素）或更大。
  • 返回的候选项数受 maxNumOfCandidatesReturned 和 confidenceThreshold 的限制。 如果未识别任何人员，则返回的候选项将为空数组。
  • 标识操作只能匹配与查询人脸关联的同一识别模型获取的人脸。

POST {endpoint}/face/{apiVersion}/identify

URI 参数

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

请求正文

名称	必需	类型	说明
faceIds	True	string[]	查询人脸 faceId 的数组，由“Detect”创建。 每个人脸都是独立识别的。 faceId 的有效数目介于 [1， 10] 之间。
personIds	True	string[]	在 Person Directory“创建人员”中创建的 personId 数组。 personId 的有效数量介于 [1,30] 之间。
confidenceThreshold		number	[0， 1] 范围内的自定义标识置信度阈值。 高级用户可以调整此值以替代默认内部阈值，以便更好地精确访问其方案数据。 请注意，无法保证此阈值适用于其他数据和算法更新之后。
maxNumOfCandidatesReturned		integer	maxNumOfCandidatesReturned 的范围介于 1 和 100 之间。 默认值为 10。

响应

名称	类型	说明
200 OK	IdentificationResult[]	成功的调用返回每个查询人脸的已识别候选人员。
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

示例

Identify from PersonDirectory

示例请求

HTTP

POST {endpoint}/face/v1.2-preview.1/identify

{
  "faceIds": [
    "c5c24a82-6845-4031-9d5d-978df9175426"
  ],
  "personIds": [
    "85c0c630-c9c9-40f8-8a4e-f9ae4f926ea5"
  ],
  "maxNumOfCandidatesReturned": 9,
  "confidenceThreshold": 0.7
}

示例响应

状态代码:

200

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "candidates": [
      {
        "personId": "85c0c630-c9c9-40f8-8a4e-f9ae4f926ea5",
        "confidence": 0.8
      }
    ]
  }
]

定义

名称	说明
FaceError	错误对象。 有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含错误详细信息的响应。
IdentificationCandidate	用于标识呼叫的候选项。
IdentificationResult	确定结果。

FaceError

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

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

FaceErrorResponse

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

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

IdentificationCandidate

用于标识呼叫的候选项。

名称	类型	说明
confidence	number	候选项的置信度值。 置信度越高，越相似。 介于 [0,1] 之间。
personId	string	候选人的 personId。

IdentificationResult

确定结果。

名称	类型	说明
candidates	IdentificationCandidate[]	确定该人脸的候选人（按信心排名）。 数组大小不应大于输入 maxNumOfCandidatesReturned。 如果未识别任何人员，则返回空数组。
faceId	string	查询人脸的 faceId。