Face - Identify 在一個人組中識別未知的面部 對于faceids數組中每一張人臉，人臉識別會計算這張查詢的臉和在人組中（personGroupId提供的）所有的臉之間的相似度，然后按照相似度等級排序返回一個候選的person(s)。人組應該是可以被鑒別的。更多知識請查看Person Group - Train Person Group. Remarks: * 該算法允許在相同的請求下獨立識別多個面部，但不超過10個面部。 * Person group中的每個person可以有不止一張臉，但不超過248張臉 * 識別適用于正面和近正面 * 返回的候選人數量受maxNumOfCandidatesReturned和confidenceThreshold限制。如果沒有人被識別，返回一個空數組 * 當需要從face list而不是person group中識別相似的臉部時，請嘗試 Face - Find Similar Http Method `POST` Request URL `https://api.cognitive.azure.cn/face/v1.0/identify` Request headers | 請求頭部 | 類型 | 描述 | | --- | --- | --- | | Content-Type(可選) | string | Media type of the body sent to the API. | | Ocp-Apim-Subscription-Key | string | Subscription key which provides access to this API. Found in your Cognitive Services accounts. | Request body JSON fields in request body | Fields | Type | Description | | --- | --- | --- | | faceIds | Array | 查詢面faceIds組成的數組，由Face - Detect創建。每個面都是獨立標識的。faceIds的有效數量在[1，10]之間| | personGroupId | String | 指定的persong group 的personGroupId 由 Person Group - Create a Person Group.創建 | | maxNumOfCandidatesReturned （可選） |Number | maxNumOfCandidatesReturned的范圍在1到5之間（默認為1） | | confidenceThreshold (可選) | Number | 可選參數。識別的置信度閾值，用于判斷這張臉是否屬于這個人。confidenceThreshold的范圍是[0，1]（默認由算法指定） | ~~~ { "personGroupId":"sample_group", "faceIds":[ "c5c24a82-6845-4031-9d5d-978df9175426", "65d083d4-9447-47d1-af30-b626144bf0fb" ], "maxNumOfCandidatesReturned":1, "confidenceThreshold": 0.5 } ~~~ Response 200 成功后，返回每個查詢返回標識的候選人員 JSON fields in response body | Fields | Type | Description | | --- | --- | --- | | faceId | String | 查詢面的faceId | | Candidates | Array | 符合請求的面部數據識別的person，根據相似度排序 | | personId | String | 獲選人的personId | |confidence | Number | 一個0.0-1.0之間的浮點數 | ~~~ { [ { "faceId":"c5c24a82-6845-4031-9d5d-978df9175426", "candidates":[ { "personId":"25985303-c537-4467-b41d-bdb45cd95ca1", "confidence":0.92 } ] }, { "faceId":"65d083d4-9447-47d1-af30-b626144bf0fb", "candidates":[ { "personId":"2ae4935b-9659-44c3-977f-61fac20d0538", "confidence":0.89 } ] } ] } ~~~ Response 400 Error code and message returned in JSON | Error Code | Error Message Description | | --- | --- | | BadArgument | 無效的請求正文 | | BadArgument | 參數maxNumOfCandidatesReturned無效。范圍是[1,5] | | BadArgument | 參數confidenceThreshold無效。范圍是[0，1] | | BadArgument |FaceID無效 | | BadArgument | Person group ID無效。有效格式應該是由數字組成的字符串，英文字母小寫，' - '，'_'，不超過64個字符。 | | PersonGroupNotFound | Person group未找到 | | FaceNotFound | Face未找到| | PersonGroupNotTrained | Person group 樣本點未trained| ~~~ { "error":{ "code":"BadArgument", "message":"Person group 'sample_group' is invalid." } } ~~~ 返回值401 Error code and message returned in JSON | Error Code| Error Message Description | | --- | --- | | Unspecified | 無效的subscription Key或用戶/計劃被凍結 | ~~~ { "error":{ "code": "Unspecified", "message": "Access denied due to invalid subscription key. Make sure you are subscribed to an API you are trying to call and provide the right key." } } ~~~ Response 403 ~~~ { "error":{ "statusCode": 403, "message": "Out of call volume quota. Quota will be replenished in 2.12 days." } } ~~~ Response 409 訓練過程與識別相沖突。訓練結束后再試一次 ~~~ { "error":{ "code":"PersonGroupTrainingNotFinished", "message":"Person group 'sample_group' is under training." } } ~~~ Response 415 不支持的媒體類型錯誤。只有“application / json”對這個API有效 ~~~ { "error":{ "code":"BadArgument", "message":"Invalid Media Type" } } ~~~ Response 429 ~~~ { "error":{ "statusCode": 429, "message": "Rate limit is exceeded. Try again in 26 seconds." } } ~~~