本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 搜尋使用者 (人臉識別碼/使用者 ID)
<a name="search-users"></a>

您可以使用 [SearchUsers](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchUsers.html) 操作來搜尋集合中符合指定人臉 ID 的人臉。本操作會依據請求的 UserMatchThreshold 以上的最高相似性分數列出傳回的 `UserIds` 排名。使用者 ID 是在 CreateUsers 作業中建立的。如需詳細資訊，請參閱 [管理集合中的使用者](managing-face-collections.md#collections-manage-users)。

**若要搜尋使用者 (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. 使用下列範例來呼叫 `SearchUsers` 操作。

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

   此 Java 範例使用 `SearchUsers` 操作搜尋集合中的使用者。

   ```
   import com.amazonaws.services.rekognition.AmazonRekognition;
   import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder;
   import com.amazonaws.services.rekognition.model.UserMatch;
   import com.amazonaws.services.rekognition.model.SearchUsersRequest;
   import com.amazonaws.services.rekognition.model.SearchUsersResult;
   import com.amazonaws.services.rekognition.model.UserMatch;
   
   public class SearchUsers {
       //Replace collectionId and faceId with the values you want to use.
   
       public static final String collectionId = "MyCollection";
       public static final String faceId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
   
       public static final String userd = 'demo-user';
   
       public static void main(String[] args) throws Exception {
   
           AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient();
   
           // Search collection for faces matching the user id.
           SearchUsersRequest request = new SearchUsersRequest()
                   .withCollectionId(collectionId)
                   .withUserId(userId);
   
           SearchUsersResult result =
                   rekognitionClient.searchUsers(request);
   
           System.out.println("Printing first search result with matched user and similarity score");
           for (UserMatch match: result.getUserMatches()) {
               System.out.println(match.getUser().getUserId() + " with similarity score " + match.getSimilarity());
           }
   
           // Search collection for faces matching the face id.
           SearchUsersRequest request1 = new SearchUsersRequest()
                   .withCollectionId(collectionId)
                   .withFaceId(faceId);
   
           SearchUsersResult result1 =
                   rekognitionClient.searchUsers(request1);
   
           System.out.println("Printing second search result with matched user and similarity score");
           for (UserMatch match: result1.getUserMatches()) {
               System.out.println(match.getUser().getUserId() + " with similarity score " + match.getSimilarity());
           }
       }
   ```

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

   此 AWS CLI 命令會使用 `SearchUsers`操作搜尋集合中的使用者。

   ```
   aws rekognition search-users --face-id {{face-id}} --collection-id {{collection-id }}--region {{region-name}}
   ```

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

   下列範例會使用 `SearchUsers` 操作搜尋集合中的使用者。

   ```
   # 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
   
   logger = logging.getLogger(__name__)
   session = boto3.Session(profile_name='profile-name')
   client = session.client('rekognition')
   
   def search_users_by_face_id(collection_id, face_id):
       """
       SearchUsers operation with face ID provided as the search source
   
       :param collection_id: The ID of the collection where user and faces are stored.
       :param face_id: The ID of the face in the collection to search for.
   
       :return: response of SearchUsers API
       """
       logger.info(f'Searching for users using a face-id: {face_id}')
       try:
           response = client.search_users(
               CollectionId=collection_id,
               FaceId=face_id
           )
           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 SearchUsers with given face id: {face_id}')
           raise
       else:
           print(response)
           return response
   
   def search_users_by_user_id(collection_id, user_id):
       """
       SearchUsers operation with user ID provided as the search source
   
       :param collection_id: The ID of the collection where user and faces are stored.
       :param user_id: The ID of the user in the collection to search for.
   
       :return: response of SearchUsers API
       """
       logger.info(f'Searching for users using a user-id: {user_id}')
       try:
           response = client.search_users(
               CollectionId=collection_id,
               UserId=user_id
           )
           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 SearchUsers with given face id: {user_id}')
           raise
       else:
           print(response)
           return response
   
   def main():
       collection_id = "collection-id"
       user_id = "user-id"
       face_id = "face_id"
       search_users_by_face_id(collection_id, face_id)
       search_users_by_user_id(collection_id, user_id)
   
   if __name__ == "__main__":
       main()
   ```

------

## SearchUsers 操作請求
<a name="search-users-request"></a>

給定一個 FaceID 或 UserID，SearchUsers 會搜尋指定的 CollectionID 使用者匹配。依預設，SearchUsers 會傳回相似度分數大於 80% 的 UserID。相似性表明 UserID 與提供的 FaceID 或 UserID 匹配的程度。如果傳回多個 UserID，則會依相似度分數最高到最低的順序列出這些 UserID。或者，您可以使用 UserMatchThreshold 來指定不同的值。如需詳細資訊，請參閱 [管理集合中的使用者](managing-face-collections.md#collections-manage-users)。

以下是使用 `UserId` 的 SearchUsers 請求範例：

```
{
   "CollectionId": "MyCollection",
   "UserId": "demoUser1",
   "MaxUsers": 2,
   "UserMatchThreshold": 99
}
```

以下是使用 `FaceId` 的 SearchUsers 請求範例：

```
{
    "CollectionId": "MyCollection",
    "FaceId": "bff43c40-cfa7-4b94-bed8-8a08b2205107",
    "MaxUsers": 2,
    "UserMatchThreshold": 99
}
```

## SearchUsers 操作回應
<a name="search-users-response"></a>

如果使用 `FaceId` 進行搜尋，SearchUser 的回應包括適用於 `SearchedFace` 的 `FaceId`，以及每個使用者的 `UserMatches`、`UserId` 和 `UserStatus` 的清單。

```
{
    "SearchedFace": {
        "FaceId": "bff43c40-cfa7-4b94-bed8-8a08b2205107"
    }, 
    "UserMatches": [
        {
            "User": {
                "UserId": "demoUser1", 
                "UserStatus": "ACTIVE"
            }, 
            "Similarity": 100.0
        }, 
        {
            "User": {
                "UserId": "demoUser2", 
                "UserStatus": "ACTIVE"
            }, 
            "Similarity": 99.97946166992188
        }
    ], 
    "FaceModelVersion": "6"
}
```

如果搜尋使用 `UserId`，SearchUser 的回應除了其他回應單元之外，還包括適用於 `UserId` 的 `SearchedUser`。

```
{
    "SearchedUser": {
        "UserId": "demoUser1"
    }, 
    "UserMatches": [
        {
            "User": {
                "UserId": "demoUser2", 
                "UserStatus": "ACTIVE"
            }, 
            "Similarity": 99.97946166992188
        }
    ], 
    "FaceModelVersion": "6"
}
```