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

# 列出集合中的人臉和關聯使用者
<a name="list-faces-in-collection-procedure"></a>

您可以使用 [ListFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListFaces.html) 操作來列出集合中的人臉。

如需詳細資訊，請參閱 [管理集合中的人臉](managing-face-collections.md#collections-index-faces)。



**若要列出集合中的臉部 (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. 使用下列範例來呼叫 `ListFaces` 操作。

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

   此範例顯示集合中的人臉的清單。

   將 `collectionId` 的值變更為所需的集合。

   ```
   //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.Face;
   import com.amazonaws.services.rekognition.model.ListFacesRequest;
   import com.amazonaws.services.rekognition.model.ListFacesResult;
   import java.util.List;
   import com.fasterxml.jackson.databind.ObjectMapper;
   
   
   
   public class ListFacesInCollection {
       public static final String collectionId = "MyCollection";
   
      public static void main(String[] args) throws Exception {
         
         AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient();
   
         ObjectMapper objectMapper = new ObjectMapper();
   
         ListFacesResult listFacesResult = null;
         System.out.println("Faces in collection " + collectionId);
   
         String paginationToken = null;
         do {
            if (listFacesResult != null) {
               paginationToken = listFacesResult.getNextToken();
            }
            
            ListFacesRequest listFacesRequest = new ListFacesRequest()
                    .withCollectionId(collectionId)
                    .withMaxResults(1)
                    .withNextToken(paginationToken);
           
            listFacesResult =  rekognitionClient.listFaces(listFacesRequest);
            List < Face > faces = listFacesResult.getFaces();
            for (Face face: faces) {
               System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
                  .writeValueAsString(face));
            }
         } while (listFacesResult != null && listFacesResult.getNextToken() !=
            null);
      }
   
   }
   ```

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

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

   ```
   // snippet-start:[rekognition.java2.list_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.Face;
   import software.amazon.awssdk.services.rekognition.model.ListFacesRequest;
   import software.amazon.awssdk.services.rekognition.model.ListFacesResponse;
   import software.amazon.awssdk.services.rekognition.model.RekognitionException;
   import java.util.List;
   // snippet-end:[rekognition.java2.list_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 ListFacesInCollection {
   
       public static void main(String[] args) {
   
           final String usage = "\n" +
               "Usage: " +
               "   <collectionId>\n\n" +
               "Where:\n" +
               "   collectionId - The name of the collection. \n\n";
   
           if (args.length < 1) {
               System.out.println(usage);
               System.exit(1);
           }
   
           String collectionId = args[0];
           Region region = Region.US_EAST_1;
           RekognitionClient rekClient = RekognitionClient.builder()
               .region(region)
               .credentialsProvider(ProfileCredentialsProvider.create("profile-name"))
               .build();
   
           System.out.println("Faces in collection " + collectionId);
           listFacesCollection(rekClient, collectionId) ;
           rekClient.close();
       }
   
       // snippet-start:[rekognition.java2.list_faces_collection.main]
       public static void listFacesCollection(RekognitionClient rekClient, String collectionId ) {
           try {
               ListFacesRequest facesRequest = ListFacesRequest.builder()
                   .collectionId(collectionId)
                   .maxResults(10)
                   .build();
   
               ListFacesResponse facesResponse = rekClient.listFaces(facesRequest);
               List<Face> faces = facesResponse.faces();
               for (Face face: faces) {
                   System.out.println("Confidence level there is a face: "+face.confidence());
                   System.out.println("The face Id value is "+face.faceId());
               }
   
           } catch (RekognitionException e) {
               System.out.println(e.getMessage());
               System.exit(1);
            }
         }
       // snippet-end:[rekognition.java2.list_faces_collection.main]
     }
   ```

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

   此 AWS CLI 命令會顯示 CLI 操作的 JSON `list-faces` 輸出。將 `collection-id` 的值取代為要列出的集合的名稱。將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。

   ```
   aws rekognition list-faces --collection-id "collection-id"  --profile profile-name
   ```

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

   此範例顯示集合中的人臉的清單。

   將建立 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 list_faces_in_collection(collection_id):
       maxResults = 2
       faces_count = 0
       tokens = True
   
       session = boto3.Session(profile_name='profile-name')
       client = session.client('rekognition')
       response = client.list_faces(CollectionId=collection_id,
                                    MaxResults=maxResults)
   
       print('Faces in collection ' + collection_id)
   
       while tokens:
   
           faces = response['Faces']
   
           for face in faces:
               print(face)
               faces_count += 1
           if 'NextToken' in response:
               nextToken = response['NextToken']
               response = client.list_faces(CollectionId=collection_id,
                                            NextToken=nextToken, MaxResults=maxResults)
           else:
               tokens = False
       return faces_count
   
   def main():
       collection_id = 'collection-id'
       faces_count = list_faces_in_collection(collection_id)
       print("faces count: " + str(faces_count))
   
   if __name__ == "__main__":
       main()
   ```

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

   此範例顯示集合中的人臉的清單。

   將 `collectionId` 的值變更為所需的集合。

   ```
   //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 ListFaces
   {
       public static void Example()
       {
           String collectionId = "MyCollection";
   
           AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient();
   
           ListFacesResponse listFacesResponse = null;
           Console.WriteLine("Faces in collection " + collectionId);
   
           String paginationToken = null;
           do
           {
               if (listFacesResponse != null)
                   paginationToken = listFacesResponse.NextToken;
   
               ListFacesRequest listFacesRequest = new ListFacesRequest()
               {
                   CollectionId = collectionId,
                   MaxResults = 1,
                   NextToken = paginationToken
               };
   
               listFacesResponse = rekognitionClient.ListFaces(listFacesRequest);
               foreach(Face face in listFacesResponse.Faces)
                   Console.WriteLine(face.FaceId);
           } while (listFacesResponse != null && !String.IsNullOrEmpty(listFacesResponse.NextToken));
       }
   }
   ```

------

## ListFaces 操作要求
<a name="listfaces-request"></a>

`ListFaces` 的輸入值是您要為其列出人臉的集合 ID。`MaxResults`​ 是要傳回之人臉的最大值。ListFaces Face 也會透過人臉識別碼清單來篩選結果，並提供使用者 ID 僅列出與指定使用者相關聯的人臉。

```
{
    "CollectionId": "MyCollection",
    "MaxResults": 1
}
```

如果回應的人臉多於 `MaxResults` 請求的人臉，則會傳回一個字符，您可以在後續的 `ListFaces` 呼叫中使用該字符獲取下一組結果。例如：

```
{
    "CollectionId": "MyCollection",
    "NextToken": "sm+5ythT3aeEVIR4WA....",
    "MaxResults": 1
}
```

## ListFaces 操作回應
<a name="listfaces-response"></a>

`ListFaces` 的回應是有關存放在指定集合中的臉部中繼資料的資訊。
+ **FaceModelVersion**：與集合相關聯的人臉模型版本。如需詳細資訊，請參閱 [了解模型版本控制](face-detection-model.md)。
+  **Faces**：有關集合中的人臉資訊。這包括有關 [BoundingBox](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_BoundingBox.html)、受信度、映像識別符，以及人臉 ID 的資訊。如需詳細資訊，請參閱[人臉](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_Face.html)。
+  **NextToken**：用於取得下一組結果的字符。

```
{
    "FaceModelVersion": "6.0", 
    "Faces": [  
        {
            "Confidence": 99.76940155029297, 
            "IndexFacesModelVersion": "6.0", 
            "UserId": "demoUser2", 
            "ImageId": "56a0ca74-1c83-39dd-b363-051a64168a65", 
            "BoundingBox": {
                "Width": 0.03177810087800026, 
                "Top": 0.36568498611450195, 
                "Left": 0.3453829884529114, 
                "Height": 0.056759100407361984
            }, 
            "FaceId": "c92265d4-5f9c-43af-a58e-12be0ce02bc3"
        },
        {
            "BoundingBox": {
                "Width": 0.03254450112581253, 
                "Top": 0.6080359816551208, 
                "Left": 0.5160620212554932, 
                "Height": 0.06347999721765518
            }, 
            "IndexFacesModelVersion": "6.0", 
            "FaceId": "851cb847-dccc-4fea-9309-9f4805967855", 
            "Confidence": 99.94369506835938, 
            "ImageId": "a8aed589-ceec-35f7-9c04-82e0b546b024"
        },
        {
            "BoundingBox": {
                "Width": 0.03094629943370819, 
                "Top": 0.4218429923057556, 
                "Left": 0.6513839960098267, 
                "Height": 0.05266290158033371
            }, 
            "IndexFacesModelVersion": "6.0", 
            "FaceId": "c0eb3b65-24a0-41e1-b23a-1908b1aaeac1", 
            "Confidence": 99.82969665527344, 
            "ImageId": "56a0ca74-1c83-39dd-b363-051a64168a65"
        }
    ]
}
```