本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用人脸 ID 搜索人脸
<a name="search-face-with-id-procedure"></a>

您可以使用该[SearchFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFaces.html)操作在集合中搜索与所提供图像中最大人脸相匹配的用户。

当检测到人脸并将人脸添加到集合时，[IndexFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html) 操作响应中将返回人脸 ID。有关更多信息，请参阅 [管理集合中的人脸](managing-face-collections.md#collections-index-faces)。



**使用人脸 ID 搜索集合中的相应人脸 (SDK)**

1. 如果您尚未执行以下操作，请：

   1. 使用 `AmazonRekognitionFullAccess` 权限创建或更新用户。有关更多信息，请参阅 [步骤 1：设置 AWS 账户并创建用户](setting-up.md#setting-up-iam)。

   1. 安装并配置 AWS CLI 和 AWS SDKs。有关更多信息，请参阅 [第 2 步：设置 AWS CLI 和 AWS SDKs](setup-awscli-sdk.md)。

1. 使用以下示例调用 `SearchFaces` 操作。

------
#### [ Java ]

   此示例显示与通过 ID 标识的人脸匹配的人脸的相关信息。

   将 `collectionID` 的值更改为包含所需人脸的集合。将 `faceId` 的值更改为您要查找的人脸的标识符。

   ```
   //Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
   //PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.)
   
   package aws.example.rekognition.image;
   import com.amazonaws.services.rekognition.AmazonRekognition;
   import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder;
   import com.fasterxml.jackson.databind.ObjectMapper;
   import com.amazonaws.services.rekognition.model.FaceMatch;
   import com.amazonaws.services.rekognition.model.SearchFacesRequest;
   import com.amazonaws.services.rekognition.model.SearchFacesResult;
   import java.util.List;
   
   
     public class SearchFaceMatchingIdCollection {
         public static final String collectionId = "MyCollection";
         public static final String faceId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
         
       public static void main(String[] args) throws Exception {
           
           AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient();
         
           ObjectMapper objectMapper = new ObjectMapper();
         // Search collection for faces matching the face id.
         
         SearchFacesRequest searchFacesRequest = new SearchFacesRequest()
                 .withCollectionId(collectionId)
                 .withFaceId(faceId)
                 .withFaceMatchThreshold(70F)
                 .withMaxFaces(2);
              
          SearchFacesResult searchFacesByIdResult = 
                  rekognitionClient.searchFaces(searchFacesRequest);
   
          System.out.println("Face matching faceId " + faceId);
         List < FaceMatch > faceImageMatches = searchFacesByIdResult.getFaceMatches();
         for (FaceMatch face: faceImageMatches) {
            System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
                    .writeValueAsString(face));
            
            System.out.println();
         }
       }
   
   }
   ```

   运行示例代码。将显示有关匹配的人脸的信息。

------
#### [ Java V2 ]

   此代码取自 AWS 文档 SDK 示例 GitHub 存储库。请在[此处](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/SearchFaceMatchingIdCollection.java)查看完整示例。

   ```
   // snippet-start:[rekognition.java2.match_faces_collection.import]
   import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider;
   import software.amazon.awssdk.regions.Region;
   import software.amazon.awssdk.services.rekognition.RekognitionClient;
   import software.amazon.awssdk.services.rekognition.model.SearchFacesRequest;
   import software.amazon.awssdk.services.rekognition.model.SearchFacesResponse;
   import software.amazon.awssdk.services.rekognition.model.FaceMatch;
   import software.amazon.awssdk.services.rekognition.model.RekognitionException;
   import java.util.List;
   // snippet-end:[rekognition.java2.match_faces_collection.import]
   
   /**
    * Before running this Java V2 code example, set up your development environment, including your credentials.
    *
    * For more information, see the following documentation topic:
    *
    * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
    */
   public class SearchFaceMatchingIdCollection {
   
       public static void main(String[] args) {
   
           final String usage = "\n" +
               "Usage: " +
               "   <collectionId> <sourceImage>\n\n" +
               "Where:\n" +
               "   collectionId - The id of the collection.  \n" +
               "   sourceImage - The path to the image (for example, C:\\AWS\\pic1.png). \n\n";
   
           if (args.length != 2) {
               System.out.println(usage);
               System.exit(1);
           }
   
           String collectionId = args[0];
           String faceId = args[1];
           Region region = Region.US_EAST_1;
           RekognitionClient rekClient = RekognitionClient.builder()
               .region(region)
               .credentialsProvider(ProfileCredentialsProvider.create("profile-name"))
               .build();
   
           System.out.println("Searching for a face in a collections");
           searchFacebyId(rekClient, collectionId, faceId ) ;
           rekClient.close();
       }
   
       // snippet-start:[rekognition.java2.match_faces_collection.main]
       public static void searchFacebyId(RekognitionClient rekClient,String collectionId, String faceId) {
   
           try {
               SearchFacesRequest searchFacesRequest = SearchFacesRequest.builder()
                   .collectionId(collectionId)
                   .faceId(faceId)
                   .faceMatchThreshold(70F)
                   .maxFaces(2)
                   .build();
   
               SearchFacesResponse imageResponse = rekClient.searchFaces(searchFacesRequest) ;
               System.out.println("Faces matching in the collection");
               List<FaceMatch> faceImageMatches = imageResponse.faceMatches();
               for (FaceMatch face: faceImageMatches) {
                   System.out.println("The similarity level is  "+face.similarity());
                   System.out.println();
               }
   
           } catch (RekognitionException e) {
               System.out.println(e.getMessage());
               System.exit(1);
           }
       }
       // snippet-end:[rekognition.java2.match_faces_collection.main]
   }
   ```

------
#### [ AWS CLI ]

   此 AWS CLI 命令显示 `search-faces` CLI 操作的 JSON 输出。将 `face-id` 的值替换为您要搜索的人脸标识符，并将 `collection-id` 的值替换为您要在其中执行搜索的集合。将创建 Rekognition 会话的行中的`profile_name`值替换为您的开发人员资料的名称。

   ```
   aws rekognition search-faces --face-id face-id --collection-id "collection-id" --profile profile-name
   ```

------
#### [ Python ]

   此示例显示与通过 ID 标识的人脸匹配的人脸的相关信息。

   将 `collectionID` 的值更改为包含所需人脸的集合。将 `faceId` 的值更改为您要查找的人脸的标识符。将创建 Rekognition 会话的行中的`profile_name`值替换为您的开发人员资料的名称。

   ```
   # Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
   # PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.)
   
   import boto3
   
   def search_face_in_collection(face_id, collection_id):
       threshold = 90
       max_faces = 2
   
       session = boto3.Session(profile_name='profile-name')
       client = session.client('rekognition')
   
       response = client.search_faces(CollectionId=collection_id,
                                      FaceId=face_id,
                                      FaceMatchThreshold=threshold,
                                      MaxFaces=max_faces)
   
       face_matches = response['FaceMatches']
       print('Matching faces')
       for match in face_matches:
           print('FaceId:' + match['Face']['FaceId'])
           print('Similarity: ' + "{:.2f}".format(match['Similarity']) + "%")
   
       return len(face_matches)
   
   def main():
       face_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
       collection_id = 'collection-id'
   
       faces = []
       faces.append(face_id)
   
       faces_count = search_face_in_collection(face_id, collection_id)
       print("faces found: " + str(faces_count))
   
   if __name__ == "__main__":
       main()
   ```

------
#### [ .NET ]

   此示例显示与通过 ID 标识的人脸匹配的人脸的相关信息。

   将 `collectionID` 的值更改为包含所需人脸的集合。将 `faceId` 的值更改为您要查找的人脸的标识符。

   ```
   //Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
   //PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.)
   
   using System;
   using Amazon.Rekognition;
   using Amazon.Rekognition.Model;
   
   public class SearchFacesMatchingId
   {
       public static void Example()
       {
           String collectionId = "MyCollection";
           String faceId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
   
           AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient();
   
           // Search collection for faces matching the face id.
   
           SearchFacesRequest searchFacesRequest = new SearchFacesRequest()
           {
               CollectionId = collectionId,
               FaceId = faceId,
               FaceMatchThreshold = 70F,
               MaxFaces = 2
           };
   
           SearchFacesResponse searchFacesResponse = rekognitionClient.SearchFaces(searchFacesRequest);
   
           Console.WriteLine("Face matching faceId " + faceId);
   
           Console.WriteLine("Matche(s): ");
           foreach (FaceMatch face in searchFacesResponse.FaceMatches)
               Console.WriteLine("FaceId: " + face.Face.FaceId + ", Similarity: " + face.Similarity);
       }
   }
   ```

   运行示例代码。将显示有关匹配的人脸的信息。

------

## SearchFaces 操作请求
<a name="searchfaces-operation-request"></a>

在给定人脸 ID（人脸集合中存储的每张人脸均有一个人脸 ID）的情况下，`SearchFaces` 将在指定人脸集合中搜索相似的人脸。该响应不包含您搜索的人脸。它仅包括相似的人脸。默认情况下，对于 `SearchFaces` 返回的人脸，算法检测到相似度得分高于 80%。相似度指示人脸与输入人脸的匹配程度。（可选）您可以使用 `FaceMatchThreshold` 指定不同的值。

```
{
    "CollectionId": "MyCollection",
    "FaceId": "0b683aed-a0f1-48b2-9b5e-139e9cc2a757",
    "MaxFaces": 2,
    "FaceMatchThreshold": 99
}
```

## SearchFaces 操作响应
<a name="searchfaces-operation-response"></a>

此操作将返回一组找到的匹配人脸以及您作为输入提供的人脸 ID。

```
{
    "SearchedFaceId": "7ecf8c19-5274-5917-9c91-1db9ae0449e2",
    "FaceMatches": [ list of face matches found ]
}
```

对于找到的每个匹配的人脸，此响应将包含相似度和人脸元数据，如以下示例响应所示：

```
{
   ...
    "FaceMatches": [
        {
            "Similarity": 100.0,
            "Face": {
                "BoundingBox": {
                    "Width": 0.6154,
                    "Top": 0.2442,
                    "Left": 0.1765,
                    "Height": 0.4692
                },
                "FaceId": "84de1c86-5059-53f2-a432-34ebb704615d",
                "Confidence": 99.9997,
                "ImageId": "d38ebf91-1a11-58fc-ba42-f978b3f32f60"
            }
        },
        {
            "Similarity": 84.6859,
            "Face": {
                "BoundingBox": {
                    "Width": 0.2044,
                    "Top": 0.2254,
                    "Left": 0.4622,
                    "Height": 0.3119
                },
                "FaceId": "6fc892c7-5739-50da-a0d7-80cc92c0ba54",
                "Confidence": 99.9981,
                "ImageId": "5d913eaf-cf7f-5e09-8c8f-cb1bdea8e6aa"
            }
        }
    ]
}
```