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

# 使用映像來搜尋人臉
<a name="search-face-with-image-procedure"></a>

您可以使用 [SearchFacesByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFacesByImage.html) 操作來搜尋集合中符合指定映像中最大人臉的人臉。

如需詳細資訊，請參閱 [在集合中搜尋人臉與使用者](collections-search-faces.md)。



**若要使用映像來搜尋集合中的人臉 (SDK)**

1. 如果您尚未執行：

   1. 建立或更新具有 `AmazonRekognitionFullAccess` 和 `AmazonS3ReadOnlyAccess` 許可的使用者。如需詳細資訊，請參閱[步驟 1：設定 AWS 帳戶並建立使用者](setting-up.md#setting-up-iam)。

   1. 安裝和設定 AWS CLI 和 AWS SDKs。如需詳細資訊，請參閱[步驟 2：設定 AWS CLI 和 AWS SDKs](setup-awscli-sdk.md)。

1. 將 (含有一或多個人臉) 的映像上傳至您的 S3 儲存貯體。

   如需指示說明，請參閱《Amazon Simple Storage Service 使用者指南》**中的[上傳物件至 Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UploadingObjectsintoAmazonS3.html)。

1. 使用下列範例來呼叫 `SearchFacesByImage` 操作。

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

   此範例顯示有關與映像中最大人臉符合的人臉資訊。程式碼範例指定 `FaceMatchThreshold` 和 `MaxFaces` 參數以限制回應中傳回的結果。

   在下列範例中，變更下列內容：將 `collectionId` 的值變更為要搜尋的集合，將 `bucket` 的值變更為包含輸入映像的儲存貯體，然後將 `photo` 的值變更為輸入映像。

   ```
   //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.amazonaws.services.rekognition.model.FaceMatch;
   import com.amazonaws.services.rekognition.model.Image;
   import com.amazonaws.services.rekognition.model.S3Object;
   import com.amazonaws.services.rekognition.model.SearchFacesByImageRequest;
   import com.amazonaws.services.rekognition.model.SearchFacesByImageResult;
   import java.util.List;
   import com.fasterxml.jackson.databind.ObjectMapper;
   
   
   public class SearchFaceMatchingImageCollection {
       public static final String collectionId = "MyCollection";
       public static final String bucket = "bucket";
       public static final String photo = "input.jpg";
         
       public static void main(String[] args) throws Exception {
   
          AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient();
           
         ObjectMapper objectMapper = new ObjectMapper();
         
          // Get an image object from S3 bucket.
         Image image=new Image()
                 .withS3Object(new S3Object()
                         .withBucket(bucket)
                         .withName(photo));
         
         // Search collection for faces similar to the largest face in the image.
         SearchFacesByImageRequest searchFacesByImageRequest = new SearchFacesByImageRequest()
                 .withCollectionId(collectionId)
                 .withImage(image)
                 .withFaceMatchThreshold(70F)
                 .withMaxFaces(2);
              
          SearchFacesByImageResult searchFacesByImageResult = 
                  rekognitionClient.searchFacesByImage(searchFacesByImageRequest);
   
          System.out.println("Faces matching largest face in image from" + photo);
         List < FaceMatch > faceImageMatches = searchFacesByImageResult.getFaceMatches();
         for (FaceMatch face: faceImageMatches) {
             System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
                     .writeValueAsString(face));
            System.out.println();
         }
      }
   }
   ```

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

   此程式碼取自 AWS 文件開發套件範例 GitHub 儲存庫。請參閱[此處](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/SearchFaceMatchingImageCollection.java)的完整範例。

   ```
   // snippet-start:[rekognition.java2.search_faces_collection.import]
   import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider;
   import software.amazon.awssdk.core.SdkBytes;
   import software.amazon.awssdk.regions.Region;
   import software.amazon.awssdk.services.rekognition.RekognitionClient;
   import software.amazon.awssdk.services.rekognition.model.RekognitionException;
   import software.amazon.awssdk.services.rekognition.model.SearchFacesByImageRequest;
   import software.amazon.awssdk.services.rekognition.model.Image;
   import software.amazon.awssdk.services.rekognition.model.SearchFacesByImageResponse;
   import software.amazon.awssdk.services.rekognition.model.FaceMatch;
   import java.io.File;
   import java.io.FileInputStream;
   import java.io.FileNotFoundException;
   import java.io.InputStream;
   import java.util.List;
   // snippet-end:[rekognition.java2.search_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 SearchFaceMatchingImageCollection {
   
       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 sourceImage = 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");
           searchFaceInCollection(rekClient, collectionId, sourceImage ) ;
           rekClient.close();
       }
   
       // snippet-start:[rekognition.java2.search_faces_collection.main]
       public static void searchFaceInCollection(RekognitionClient rekClient,String collectionId, String sourceImage) {
   
           try {
               InputStream sourceStream = new FileInputStream(new File(sourceImage));
               SdkBytes sourceBytes = SdkBytes.fromInputStream(sourceStream);
               Image souImage = Image.builder()
                   .bytes(sourceBytes)
                   .build();
   
               SearchFacesByImageRequest facesByImageRequest = SearchFacesByImageRequest.builder()
                   .image(souImage)
                   .maxFaces(10)
                   .faceMatchThreshold(70F)
                   .collectionId(collectionId)
                   .build();
   
               SearchFacesByImageResponse imageResponse = rekClient.searchFacesByImage(facesByImageRequest) ;
               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 | FileNotFoundException e) {
               System.out.println(e.getMessage());
               System.exit(1);
           }
       }
       // snippet-end:[rekognition.java2.search_faces_collection.main]
   }
   ```

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

   此 AWS CLI 命令會顯示 CLI 操作的 JSON `search-faces-by-image` 輸出。以您在步驟 2 中所使用的 S3 儲存貯體來取代 `Bucket` 的值。以您在步驟 2 中所使用的映像檔案名稱來取代 `Name` 的值。以您要搜尋的集合名稱取代 `collection-id` 的值。將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。

   ```
   aws rekognition search-faces-by-image --image '{"S3Object":{"Bucket":"bucket-name","Name":"image-name"}}' \
   --collection-id "collection-id" --profile profile-name
   ```

    如果您在 Windows 裝置上存取 CLI，請使用雙引號而非單引號，並以反斜線 (即\$1) 替代內部雙引號，以解決您可能遇到的任何剖析器錯誤。例如，請參閱下列內容：

   ```
   aws rekognition search-faces-by-image --image "{\"S3Object\":{\"Bucket\":\"bucket-name\",\"Name\":\"image-name\"}}" \
   --collection-id "collection-id" --profile profile-name
   ```

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

   此範例顯示有關與映像中最大人臉符合的人臉資訊。程式碼範例指定 `FaceMatchThreshold` 和 `MaxFaces` 參數以限制回應中傳回的結果。

   在下列範例中，變更下列內容：將 `collectionId` 的值變更為要搜尋的集合，並將 `bucket` 和 `photo` 的值取代為步驟 2 中使用的 Amazon S3 儲存貯體和映像的名稱。將建立 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
   
   if __name__ == "__main__":
   
       bucket='amzn-s3-demo-bucket'
       collectionId='MyCollection'
       fileName='input.jpg'
       threshold = 70
       maxFaces=2
   
       client=boto3.client('rekognition')
   
     
       response=client.search_faces_by_image(CollectionId=collectionId,
                                   Image={'S3Object':{'Bucket':bucket,'Name':fileName}},
                                   FaceMatchThreshold=threshold,
                                   MaxFaces=maxFaces)
   
                                   
       faceMatches=response['FaceMatches']
       print ('Matching faces')
       for match in faceMatches:
               print ('FaceId:' + match['Face']['FaceId'])
               print ('Similarity: ' + "{:.2f}".format(match['Similarity']) + "%")
               print
   ```

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

   此範例顯示有關與映像中最大人臉符合的人臉資訊。程式碼範例指定 `FaceMatchThreshold` 和 `MaxFaces` 參數以限制回應中傳回的結果。

   在下列範例中，變更下列內容：將 `collectionId` 的值變更為要搜尋的集合，並將 `bucket` 和 `photo` 的值取代為步驟 2 中使用的 Amazon S3 儲存貯體和映像的名稱。

   ```
   //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 SearchFacesMatchingImage
   {
       public static void Example()
       {
           String collectionId = "MyCollection";
           String bucket = "amzn-s3-demo-bucket";
           String photo = "input.jpg";
   
           AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient();
   
           // Get an image object from S3 bucket.
           Image image = new Image()
           {
               S3Object = new S3Object()
               {
                   Bucket = bucket,
                   Name = photo
               }
           };
   
           SearchFacesByImageRequest searchFacesByImageRequest = new SearchFacesByImageRequest()
           {
               CollectionId = collectionId,
               Image = image,
               FaceMatchThreshold = 70F,
               MaxFaces = 2
           };
   
           SearchFacesByImageResponse searchFacesByImageResponse = rekognitionClient.SearchFacesByImage(searchFacesByImageRequest);
   
           Console.WriteLine("Faces matching largest face in image from " + photo);
           foreach (FaceMatch face in searchFacesByImageResponse.FaceMatches)
               Console.WriteLine("FaceId: " + face.Face.FaceId + ", Similarity: " + face.Similarity);
       }
   }
   ```

------

## SearchFacesByImage 操作要求
<a name="searchfacesbyimage-operation-request"></a>

`SearchFacesImageByImage` 的輸入參數是要搜尋的集合和來源映像位置。在此範例中，來源映像儲存於 Amazon S3 儲存貯體 (`S3Object`)。另外指定要傳回的最大臉數 (`Maxfaces`) 以及必須與要傳回的人臉 (`FaceMatchThreshold`) 相符的最小可信度。

```
{
    "CollectionId": "MyCollection",
    "Image": {
        "S3Object": {
            "Bucket": "bucket",
            "Name": "input.jpg"
        }
    },
    "MaxFaces": 2,
    "FaceMatchThreshold": 99
}
```

## SearchFacesByImage 操作回應
<a name="searchfacesbyimage-operation-response"></a>

指定輸入映像 (.jpeg 或 .png) 時，操作首先將偵側輸入映像中的人臉，接著搜尋指定的人臉集合以尋找相似人臉。

**注意**  
如果服務在輸入映像中偵測到多個人臉，將使用偵測到的最大人臉來搜尋人臉集合。

此操作會傳回找到的相符人臉阵列以及有關輸入人臉的資訊。這包括邊框等資訊，以及表示邊框包含人臉的可信度水平的可信度值。

在預設情況下，`SearchFacesByImage` 傳回在使用演算法偵測後相似度超過 80% 的人臉。相似度代表偵測到的人臉與輸入人臉間符合的程度。或者，可以使用 `FaceMatchThreshold` 來指定不同的值。對於每個找到的臉部配對，回應將包含相似度以及臉部中繼資料，如下方範例回應所示：

```
{
    "FaceMatches": [
        {
            "Face": {
                "BoundingBox": {
                    "Height": 0.06333330273628235,
                    "Left": 0.1718519926071167,
                    "Top": 0.7366669774055481,
                    "Width": 0.11061699688434601
                },
                "Confidence": 100,
                "ExternalImageId": "input.jpg",
                "FaceId": "578e2e1b-d0b0-493c-aa39-ba476a421a34",
                "ImageId": "9ba38e68-35b6-5509-9d2e-fcffa75d1653"
            },
            "Similarity": 99.9764175415039
        }
    ],
    "FaceModelVersion": "3.0",
    "SearchedFaceBoundingBox": {
        "Height": 0.06333333253860474,
        "Left": 0.17185185849666595,
        "Top": 0.7366666793823242,
        "Width": 0.11061728745698929
    },
    "SearchedFaceConfidence": 99.99999237060547
}
```