搜索用户（图像）

SearchUsersByImage 在指定集合 ID 中搜索与所提供图像中检测到的最大人脸相匹配的用户。默认情况下， SearchUsersByImage 返回相似度分数大于 80% 的用户IDs 。相似度表示用户 ID 与所提供图像中检测到的最大面孔的匹配程度。如果返回多个用户IDs ，则按相似度分数最高到最低的顺序列出。或者，您可以使用 UserMatchThreshold 来指定不同的值。有关更多信息，请参阅 在集合中管理用户。

按图片搜索用户 (SDK)

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

   1. 使用 AmazonRekognitionFullAccess 权限创建或更新用户。有关更多信息，请参阅 步骤 1：设置 AWS 账户并创建用户。

   2. 安装并配置 AWS CLI 和 AWS SDKs。有关更多信息，请参阅 第 2 步：设置 AWS CLI 和 AWS SDKs。

2. 使用以下示例调用 SearchUsersByImage 操作。

   Java

   此 Java 示例使用 SearchUsersByImage 操作根据输入图像搜索集合中的用户。

   import com.amazonaws.services.rekognition.AmazonRekognition;
   import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder;
   import com.amazonaws.services.rekognition.model.Image;
   import com.amazonaws.services.rekognition.model.S3Object;
   import com.amazonaws.services.rekognition.model.SearchUsersByImageRequest;
   import com.amazonaws.services.rekognition.model.SearchUsersByImageResult;
   import com.amazonaws.services.rekognition.model.UserMatch;
   
   
   public class SearchUsersByImage {
       //Replace bucket, collectionId and photo with your values.
       public static final String collectionId = "MyCollection";
       public static final String s3Bucket = "bucket";
       public static final String s3PhotoFileKey = "input.jpg";
   
       public static void main(String[] args) throws Exception {
   
           AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient();
   
   
           // Get an image object from S3 bucket.
           Image image = new Image()
                   .withS3Object(new S3Object()
                           .withBucket(s3Bucket)
                           .withName(s3PhotoFileKey));
   
           // Search collection for users similar to the largest face in the image.
           SearchUsersByImageRequest request = new SearchUsersByImageRequest()
                   .withCollectionId(collectionId)
                   .withImage(image)
                   .withUserMatchThreshold(70F)
                   .withMaxUsers(2);
   
           SearchUsersByImageResult result =
                   rekognitionClient.searchUsersByImage(request);
   
           System.out.println("Printing search result with matched user and similarity score");
           for (UserMatch match: result.getUserMatches()) {
               System.out.println(match.getUser().getUserId() + " with similarity score " + match.getSimilarity());
           }
       }
   }

   AWS CLI

   此 AWS CLI 命令通过SearchUsersByImage操作根据输入图像在集合中搜索用户。

   aws rekognition search-users-by-image --image '{"S3Object":{"Bucket":"s3BucketName","Name":"file-name"}}' --collection-id MyCollectionId --region region-name

   Python

   以下示例使用 SearchUsersByImage 操作根据输入图像搜索集合中的用户。

   # 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
   from botocore.exceptions import ClientError
   import logging
   import os
   
   logger = logging.getLogger(__name__)
   session = boto3.Session(profile_name='profile-name')
   client = session.client('rekognition')
   
   def load_image(file_name):
       """
       helper function to load the image for indexFaces call from local disk
   
       :param image_file_name: The image file location that will be used by indexFaces call.
       :return: The Image in bytes
       """
       print(f'- loading image: {file_name}')
       with open(file_name, 'rb') as file:
           return {'Bytes': file.read()}
   
   def search_users_by_image(collection_id, image_file):
       """
       SearchUsersByImage operation with user ID provided as the search source
   
       :param collection_id: The ID of the collection where user and faces are stored.
       :param image_file: The image that contains the reference face to search for.
   
       :return: response of SearchUsersByImage API
       """
       logger.info(f'Searching for users using an image: {image_file}')
       try:
           response = client.search_users_by_image(
               CollectionId=collection_id,
               Image=load_image(image_file)
           )
           print(f'- found {len(response["UserMatches"])} matches')
           print([f'- {x["User"]["UserId"]} - {x["Similarity"]}%' for x in response["UserMatches"]])
       except ClientError:
           logger.exception(f'Failed to perform SearchUsersByImage with given image: {image_file}')
           raise
       else:
           print(response)
           return response
   
   def main():
       collection_id = "collection-id"
       IMAGE_SEARCH_SOURCE = os.getcwd() + '/image_path'
       search_users_by_image(collection_id, IMAGE_SEARCH_SOURCE)
   
   if __name__ == "__main__":
       main()

SearchUsersByImage 操作请求

对 SearchUsersByImage 的请求包括要在其中进行搜索的集合和源图像位置。在此示例中，源图像存储在 Amazon S3 存储桶（S3Object）中。另外还指定了要返回的用户最大数量（MaxUsers）和要与返回的用户匹配所必须达到的最低置信度（UserMatchThreshold）。

{
    "CollectionId": "MyCollection",
    "Image": {
        "S3Object": {
            "Bucket": "bucket",
            "Name": "input.jpg"
        }
    },
    "MaxUsers": 2,
    "UserMatchThreshold": 99
}
            

SearchUsersByImage 操作响应

的响应SearchUsersByImage包括一个对应的FaceDetail对象SearchedFace，以及每个对象 UserMatches 的列表，均UserStatus为UserIdSimilarity、和。如果输入图像包含多张脸，则还 UnsearchedFaces 会返回一个列表。

{
    "SearchedFace": {
        "FaceDetail": {
            "BoundingBox": {
                "Width": 0.23692893981933594, 
                "Top": 0.19235000014305115, 
                "Left": 0.39177176356315613, 
                "Height": 0.5437348484992981
            }
        }
    }, 
    "UserMatches": [
        {
            "User": {
                "UserId": "demoUser1", 
                "UserStatus": "ACTIVE"
            }, 
            "Similarity": 100.0
        }, 
        {
            "User": {
                "UserId": "demoUser2", 
                "UserStatus": "ACTIVE"
            }, 
            "Similarity": 99.97946166992188
        }
    ], 
    "FaceModelVersion": "6", 
    "UnsearchedFaces": [
        {
            "FaceDetails": {
                "BoundingBox": {
                    "Width": 0.031677018851041794, 
                    "Top": 0.5593535900115967, 
                    "Left": 0.6102562546730042, 
                    "Height": 0.0682177022099495
                }
            }, 
            "Reasons": [
                "FACE_NOT_LARGEST"
            ]
        }, 
        {
            "FaceDetails": {
                "BoundingBox": {
                    "Width": 0.03254449740052223, 
                    "Top": 0.6080358028411865, 
                    "Left": 0.516062319278717, 
                    "Height": 0.06347997486591339
                }
            }, 
            "Reasons": [
                "FACE_NOT_LARGEST"
            ]
        }
    ]
}