本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在集合中搜尋人臉 Amazon Rekognition 可讓您使用輸入人臉來搜尋已儲存人臉集合中的相符人臉。首先，將偵測到的人臉相關資訊儲存在伺服器端容器 (稱為「集合」) 中。集合同時存放個別人臉和使用者 （同一人的多個人臉）。將人臉會儲存為人臉向量，是人臉的數學表現法 (而非人臉的實際映像)。同一個人的不同影像可用於在同一個集合中建立和存放多個臉部向量。然後，您可以彙總同一個人的多個臉部向量來建立使用者向量。使用者矢量可以提供更高的人臉搜尋精度，並具有更強大的描述，包含不同程度的照明效果、銳利度、姿勢與外觀等。 建立集合後，您可以使用輸入人臉來搜尋集合中相符的使用者向量或人臉向量。與搜尋個別人臉向量相比，基於使用者向量進行搜尋可大幅提高準確度。您可以使用在映像、存放的影片和串流影片中偵測人臉，來搜尋已儲存的人臉向量。您可以使用在映像中偵測到的人臉來搜尋儲存的使用者向量。 若要存放人臉資訊，您需要執行以下操作： 1. 建立集合 - 若要儲存臉部資訊，您必須先在帳戶中的其中一個 AWS 區域中建立 ([CreateCollection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateCollection.html)) 臉部集合。當您呼叫 `IndexFaces` 操作時可指定此人臉集合。 1. 索引人臉：[IndexFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html) 操作會偵測映像中的人臉，擷取人臉向量，並將人臉向量儲存在集合中。您可以使用此操作來偵測映像中人臉，並將偵測到的人臉特徵的資訊儲存於集合中。此為*以儲存體為基礎*的 API 操作範例，因為該操作會在伺服器中儲存資訊。 若要建立使用者並將多個人臉向量與使用者建立關聯，您需要執行下列操作： 1. 建立使用者：您必須先使用 [CreateUser](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateUser.html) 建立使用者。您可以將同一人物的多個人臉向量彙總至使用者向量，藉此提高人臉配對的精確度。您最多可以將 100 個人臉向量與一個使用者向量建立關聯。 1. 關聯人臉：建立使用者之後，可以使用 [AssociateFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_AssociateFaces.html) 操作將現有的人臉向量新增至該使用者。人臉向量必須與使用者向量位於相同的集合中，才能與該使用者向量相關聯。 建立集合並儲存人臉和使用者向量之後，可以使用下列操作來搜尋人臉相符專案： + [SearchFacesByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFacesByImage.html)：用映像中的人臉搜尋儲存的單個人臉。 + [SearchFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFaces.html)：使用提供的人臉 ID 對儲存的人臉進行搜尋。 + [SearchUsers](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchUsers.html)：使用提供的人臉 ID 或使用者 ID 對儲存的使用者進行搜尋。 + [SearchUsersByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchUsersByImage.html)：用映像中的人臉搜尋儲存的使用者。 + [StartFaceSearch](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartFaceSearch.html)：在儲存的影片中搜尋人臉。 + [CreateStreamProcessor](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateStreamProcessor.html)：在串流影片中搜尋人臉。 **注意** 集合存放臉部向量，這是臉部的數學表示法。集合不會存放臉部影像。 下圖顯示根據您使用集合的目標，呼叫 操作的順序： **若要取得與使用者向量相符的最大準確度：** ![\[描述在集合中存放和搜尋使用者臉部向量的圖表，列出 CreateCollection、IndexFaces、CreateUser、AssociateFaces、SearchUsersByImage 和 SearchUsers 等操作。\]](http://docs.aws.amazon.com/zh_tw/rekognition/latest/dg/images/uservectorsCollection.png) **若要與個別臉部向量進行高準確度比對：** ![\[描述在集合中存放和搜尋臉部的圖表，列出 CreateCollection、IndexFaces、StartFaceSearch、CreateStreamProcessor、SearchFacesByImage 和 SearchFaces 等操作。\]](http://docs.aws.amazon.com/zh_tw/rekognition/latest/dg/images/facevectorsCollection.png) 您可以在各種不同情況中使用集合。例如，您可以建立人臉集合，該集合透過使用 `IndexFaces` 和 `AssociateFaces` 操作來儲存從掃描員工徽章映像和政府核發的 ID 中偵測到的人臉。當員工進入大樓時，將拍攝員工人臉的映像並傳送至 `SearchUsersByImage` 操作。如果臉部比對的相似性分數達到設定的目標 (例如 99%)，即可驗證該員工身分。 # 管理臉部集合、臉部和使用者 臉部集合是 Amazon Rekognition 用於包含臉部和使用者相關資訊的資源。您可以使用各種 Rekognition API 操作來管理集合本身，以及存放在集合中的任何臉部或臉部向量。 ## 管理集合 人臉集合是主要的 Amazon Rekognition 資源，每個您所建立的人臉集合都有一組專有的 Amazon Resource Name (ARN)。您可以在帳戶中的特定 AWS 區域中建立每個臉部集合。當建立集合時，將採用最新版的臉部偵測模型版本。如需詳細資訊，請參閱 [了解模型版本控制](face-detection-model.md)。 您可以對集合執行以下管理操作。 + 使用 [CreateCollection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateCollection.html) 建立集合。如需詳細資訊，請參閱 [建立集合](create-collection-procedure.md)。 + 使用 [ListCollections](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListCollections.html) 列出可用的集合。如需詳細資訊，請參閱 [列出集合](list-collection-procedure.md)。 + 使用 [DescribeCollection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DescribeCollection.html)，描述集合。如需詳細資訊，請參閱 [描述集合](describe-collection-procedure.md)。 + 使用 [DeleteCollection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DeleteCollection.html)，刪除集合。如需詳細資訊，請參閱 [刪除集合](delete-collection-procedure.md)。 ## 管理集合中的人臉 在您建立人臉集合後，可將人臉存入其中。Amazon Rekognition 將提供以下操作，供您管理集合中的人臉。 + [IndexFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html) 操作可偵測輸入映像 (JPEG 或 PNG) 中的人臉，並將這些人臉新增到指定的人臉集合。對於在映像中偵測到的每個人臉傳回唯一的人臉 ID。存入臉部之後，便可以搜尋臉部集合來比對臉部。如需詳細資訊，請參閱 [新增人臉到集合](add-faces-to-collection-procedure.md)。 + [ListFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListFaces.html) 操作可列出集合中的人臉。如需詳細資訊，請參閱 [新增人臉到集合](add-faces-to-collection-procedure.md)。 + [DeleteFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DeleteFaces.html) 操作可删除集合中的人臉。如需詳細資訊，請參閱 [删除集合中的人臉](delete-faces-procedure.md)。 ## 管理集合中的使用者 儲存來自同一個人的多個人臉向量後，您可以將所有這些人臉向量關聯到一個使用者向量來提高準確性。您可以使用下列操作來管理使用者： + [CreateUser](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateUser.html)：該操作使用提供的唯一使用者 ID，在集合中建立新使用者。 + [AssociateUsers](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_AssociateUsers.html)：將 1 至 100 個唯一人臉 ID 新增至使用者 ID。將至少一個人臉 ID 與使用者建立關聯後，可以搜尋收藏中的該使用者相符專案。 + [ListUsers](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListUsers.html)：列出集合中的使用者。 + [DeleteUsers](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DeleteUsers.html)：使用提供的使用者 ID 從集合中刪除使用者。 + [DisassociateFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DisassociateFaces.html)：移除使用者的一個或多個人臉 ID。 # 使用相似性閾值來關聯和比對臉部 相似性閾值用於關聯和比對臉部。以下是針對兩種使用案例使用相似性閾值的指引。 ## 使用相似性閾值來關聯人臉 使用 [AssociateFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_AssociateFaces.html) 操作關聯臉部時，請務必確保與使用者相關聯的臉部都來自同一個人。為提供協助，此 `UserMatchThreshold` 參數可指定與至少包含一個 `FaceID` 的 `UserID` 相關聯的新人人臉所需的最小使用者相符可信度。這有助於確保 `FaceIds` 與右側 `UserID` 相關聯。此值的範圍介於 0-100 之間，預設值為 75。 ## 使用相似性臨界值來比對人臉 我們允許您將相似性閾值作為輸入參數，以控制所有搜尋操作 ([CompareFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CompareFaces.html)、[SearchFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFaces.html)、[SearchFacesByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFacesByImage.html)、[SearchUsers](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchUsers.html)、[SearchUsersByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchUsersByImage.html)) 結果。 `FaceMatchThreshold` 作為 `SearchFaces`​ 與 `SearchFacesByImage` 的相似性閾值輸入屬性，會根據匹配的人臉相似度來控制傳回結果的數量。`UserMatchThreshold` 作為 `SearchUsers` 和 `SearchUsersByImage`​ 的相似性閾值屬性，會根據匹配的使用者向量相似度來控制的傳回結果數量。臨界值屬性適 `SimilarityThreshold` 用於 `CompareFaces`。 含低於臨界值之 `Similarity` 回應屬性值的回應不會傳回。請務必利用此閾值校正您的使用案例，因為其可決定您的相符結果包含多少錯誤肯定。這可控制您搜尋結果的回呼 (閾值越低，回呼越高)。 所有機器學習系統是機率性的。您應根據使用案例，在設定適當的相似性閾值時使用判斷。例如，如果您想要建立照片應用程式來辨識樣貌相似度家庭成員，您可以選擇較低的閾值 (例如 80%)。另一方面，對於許多強制執行法律使用案例，建議您使用 99% 或更高的臨界值，以降低意外辨識錯誤。 除 `FaceMatchThreshold` 與 `UserMatchThreshold` 外，您還可以使用 `Similarity` 回應屬性作為降低意外辨識錯誤的方法。例如，您可以選擇使用較低閾值 (例如 80%) 來傳回更多結果。接著您可以使用回應屬性相似性 (相似性百分比)，來縮小選擇範圍並篩選應用程式中適當的回應。同樣地，使用更高的相似度 (如 99% 或更高) 將會降低辨識錯誤的風險。 # 在常見案例中為臉部編製索引的指引 以下是在常見案例中使用 `IndexFaces` 的指導。 ## 關鍵或公共安全應用 + 呼叫具有多張映像的 [IndexFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html)，其中每一張映像只包含一個人臉，且會將傳回的人臉 ID 與映像主體的識別符建立關聯。 + 您可以在製作索引之前使用 [DetectFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DetectFaces.html)，以確認映像中只有一個人臉。如果偵測到多個人臉，請在檢閱只有一個人臉之後重新提交映像。這可防止不小心製作多個臉部的索引，以及將它們與同一個人建立關聯。 ## 照片共享和社交媒體應用程式 + 應該呼叫 `IndexFaces`，而不限制在使用案例中包含多個人臉的映像，例如家庭相冊。在這類情況下，您需要識別每張照片中的每一個人，並使用該資訊依其中呈現的人員將照片分組。 ## 一般用法 + 對同一個人之不同的映像 (尤其是具有不同人臉屬性 (人臉姿勢、人臉毛髮等等)) 進行索引，建立使用者，將不同人臉與使用者關聯，以改善比對品質。 + 包含檢閱程序，以便可以使用正確的臉部識別符來為失敗的比對製作索引，來提高後續的臉部比對能力。 + 如需映像品質的相關資訊，請參閱 [人臉比較輸入映像的建議](recommendations-facial-input-images.md)。 # 在集合中搜尋人臉與使用者 在建立人臉集合並儲存人臉向量和/或使用者向量後，即可搜尋人臉集合來比對人臉。使用 Amazon Rekognition，您可以在符合的集合中搜尋人臉： + 提供的人臉 ID ([SearchFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFaces.html)). 如需詳細資訊，請參閱 [搜尋具有人臉 ID 的人臉](search-face-with-id-procedure.md)。 + 在顯示映像 ([SearchFacesByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFacesByImage.html)) 中最大的人臉。如需詳細資訊，請參閱 [使用映像來搜尋人臉](search-face-with-image-procedure.md)。 + 已存放影片中的人臉。如需詳細資訊，請參閱 [在儲存的影片中搜尋人臉](procedure-person-search-videos.md)。 + 串流影片中的人臉。如需詳細資訊，請參閱 [處理串流影片事件](streaming-video.md)。 可使用 `CompareFaces` 操作將原始映像中的人臉與目標映像中的人臉進行比較。這項比對的範圍僅限於在目標映像中所偵測到的人臉。如需詳細資訊，請參閱[比較映像中的人臉](https://docs.aws.amazon.com/rekognition/latest/dg/faces-comparefaces.html)。 下列清單中看到的各種搜尋操作會將人臉 (通過 `FaceId` 或輸入映像進行識別) 與指定人臉集合中儲存的所有人臉進行比較： + [SearchFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFaces.html) + [SearchFacesByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFacesByImage.html) + [SearchUsers](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchUsers.html) + [SearchUsersByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchUsersByImage.html) # 涉及公共安全的使用案例 除 [感應器、輸入映像和影片的最佳實務](best-practices.md) 和 [在常見案例中為臉部編製索引的指引](guidance-index-faces.md) 中列出的建議外，在涉及公共安全的使用案例中部署人臉偵測和比較系統時，您應該使用以下最佳實務。首先，您應該使用 99% 或更高的可信度閾值，以降低錯誤和誤報。其次，您應該包含人工檢閱，以驗證從臉部偵測或比較系統收到的結果，而且若沒有額外的人工檢閱，您不應該根據系統輸出做出決策。人臉偵測和比較系統應做為工具，用於協助縮小範圍，支持人們迅速檢閱和考慮選項。第三，我們建議您在這些使用案例中使用臉部偵測或比較系統時應該透明，包括儘可能將使用這些系統的情形通知終端使用者和主體、獲得此類使用的同意，以及提供一個機制，讓最終使用者和主體可以提供意見回饋以改善系統。 如果您是執法部門，在進行刑事調查時需用到 Amazon Rekognition 人臉比較特徵，您必須遵守 [AWS 服務條款](https://aws.amazon.com/service-terms/)中列出的要求。這包含下列專案： + 由經過適當培訓的人員審查所有決定，採取可能影響公民自由或同等人權的行動。 + 培訓人員負責使用臉部辨識系統。 + 公開您使用臉部辨識系統的方式。 + 未經獨立審查或若非緊急情況，不得使用 Amazon Rekognition 持續監控一物件。 在所有情況下，應在具有其他強而有力的證據下檢視臉部比較配對，而不應將其做為採取行動的唯一決定因素。不過，如果將臉部比較用於非執法部門的案例 (例如，解除電話的鎖定或在進入安全、私有辦公室建築物時驗證員工的身分)，這些決策就不需要手動稽核，因為不會影響一個人的公民權利。 如果您打算針對涉及公共安全的使用案例使用臉部偵測或臉部比較系統，則應該採用先前提及的最佳實務。此外，您應該參考已發佈的資源，了解如何使用臉部比較。其中包括司法部司法援助局所提供的 [Face Recognition Policy Development Template For Use In Criminal Intelligence and Investigative Activities](https://www.bja.gov/Publications/Face-Recognition-Policy-Development-Template-508-compliant.pdf)。此範本提供多種臉部比較和生物相關資源，旨在提供執法和公共安全部門一個框架，以開發遵守適用法律、降低隱私風險，並建立實體責任和監督的臉部比較政策。其他資源包括美國國家電信暨資訊管理局提供的 [Best Privacy Practices for Commercial Use of Facial Recognition](https://www.ntia.doc.gov/files/ntia/publications/privacy_best_practices_recommendations_for_commercial_use_of_facial_recogntion.pdf)，以及美國聯邦貿易委員會全體提供的 [Best Practices for Common Uses of Facial Recognition](https://www.ftc.gov/sites/default/files/documents/reports/facing-facts-best-practices-common-uses-facial-recognition-technologies/121022facialtechrpt.pdf)。可能會在未來開發並發佈其他資源，而且您應該持續對此重要主題自我教育。 提醒您，您在使用 AWS 服務時必須遵守所有適用的法律，而且若使用的方式違反其他人的權利或可能有害其他人的話，您可能會無法使用任何 AWS 服務。這意味著您不得以非法歧視個人或侵犯個人正當程序、隱私或公民自由的方式將 AWS 服務用於公共安全使用案例。您應該視需要取得適當的法律建議，以查閱關於使用案例的任何法律要求或問題。 ## 使用 Amazon Rekognition 協助公眾安全 Amazon Rekognition 可協助公共安全與執法部門要求案例 (例如尋找失蹤兒童、打擊人口販賣或預防犯罪)。在公共安全與執法部門要求案例中，請考慮以下： + 使用 Amazon Rekognition 做為尋找可能配對的第一步。透過 Amazon Rekognition 人臉操作的回應可讓您快速地取得潛在配對，供您進一步考量。 + 請勿使用 Amazon Rekognition 回應在需要人類分析的情境中進行自主決策。如果您是執法部門，需使用 Amazon Rekognition 協助識別與刑事調查相關的物件，且所採取的身分類型行動可能影響該人的公民自由或同等人權，負責決定採取行動的人員必須接受過獨立驗證身分證明的相應培訓。 + 將 99% 相似度的臨界值用於需要高準確臉部相似度比對的案例。此類範例即是進入建築物時的存取驗證。 + 當有公民權利這方面的考量時，例如包含執法部門的使用案例，請使用 99% 或更高的臨界值，以及採用人工的方式檢閱臉部比較預測結果，以確保未侵犯人員的公民權利。 + 將低於 99% 相似度臨界值用於受益於大型潛在相符集合的案例中。此類範例其中之一便是尋找失蹤人口。如有需要，您可以使用相似度回應屬性，來判斷與您希望辨識之人員的潛在相符的相似程度。  + 擬訂計畫，來判斷 Amazon Rekognition 所傳回之相符人臉的對錯。例如，在您使用 [IndexFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html) 操作建置索引時，透過使用相同人員的多個映像來改善相符程度。如需詳細資訊，請參閱 [在常見案例中為臉部編製索引的指引](guidance-index-faces.md)。 在其他使用案例 (例如社交媒體)，我們建議您使用最佳判斷，以評估 Amazon Rekognition 結果是否需要人工檢閱。此外，根據應用程式的要求，相似度臨界值可能較低。 # 建立集合 您可以使用 [CreateCollection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateCollection.html) 操作來建立集合。 如需詳細資訊，請參閱 [管理集合](managing-face-collections.md#managing-collections)。 **若要建立集合 (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. 使用下列範例來呼叫 `CreateCollection` 操作。 ------ #### [ Java ] 以下範例建立集合和顯示其 Amazon Resource Name (ARN)。 將 `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.CreateCollectionRequest; import com.amazonaws.services.rekognition.model.CreateCollectionResult; public class CreateCollection { public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); String collectionId = "MyCollection"; System.out.println("Creating collection: " + collectionId ); CreateCollectionRequest request = new CreateCollectionRequest() .withCollectionId(collectionId); CreateCollectionResult createCollectionResult = rekognitionClient.createCollection(request); System.out.println("CollectionArn : " + createCollectionResult.getCollectionArn()); System.out.println("Status code : " + createCollectionResult.getStatusCode().toString()); } } ``` ------ #### [ Java V2 ] 此程式碼取自 AWS 文件開發套件範例 GitHub 儲存庫。請參閱[此處](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/CreateCollection.java)的完整範例。 將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。 ``` //snippet-start:[rekognition.java2.create_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.CreateCollectionResponse; import software.amazon.awssdk.services.rekognition.model.CreateCollectionRequest; import software.amazon.awssdk.services.rekognition.model.RekognitionException; //snippet-end:[rekognition.java2.create_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 CreateCollection { public static void main(String[] args) { final String usage = "\n" + "Usage: " + " \n\n" + "Where:\n" + " collectionName - 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("Creating collection: " +collectionId); createMyCollection(rekClient, collectionId ); rekClient.close(); } // snippet-start:[rekognition.java2.create_collection.main] public static void createMyCollection(RekognitionClient rekClient,String collectionId ) { try { CreateCollectionRequest collectionRequest = CreateCollectionRequest.builder() .collectionId(collectionId) .build(); CreateCollectionResponse collectionResponse = rekClient.createCollection(collectionRequest); System.out.println("CollectionArn: " + collectionResponse.collectionArn()); System.out.println("Status code: " + collectionResponse.statusCode().toString()); } catch(RekognitionException e) { System.out.println(e.getMessage()); System.exit(1); } } // snippet-end:[rekognition.java2.create_collection.main] ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會顯示 CLI 操作的 JSON `create-collection` 輸出。 將 `collection-id` 的值取代為您要建立集合的名稱。 使用您開發人員設定檔的名稱取代 `profile_name` 的值。 ``` aws rekognition create-collection --profile profile-name --collection-id "collection-name" ``` ------ #### [ Python ] 以下範例建立集合和顯示其 Amazon Resource Name (ARN)。 將 `collection_id` 的值變更為您要建立集合的名稱。將建立 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 create_collection(collection_id): session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') # Create a collection print('Creating collection:' + collection_id) response = client.create_collection(CollectionId=collection_id) print('Collection ARN: ' + response['CollectionArn']) print('Status code: ' + str(response['StatusCode'])) print('Done...') def main(): collection_id = "collection-id" create_collection(collection_id) if __name__ == "__main__": main() ``` ------ #### [ .NET ] 以下範例建立集合和顯示其 Amazon Resource Name (ARN)。 將 `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 CreateCollection { public static void Example() { AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); String collectionId = "MyCollection"; Console.WriteLine("Creating collection: " + collectionId); CreateCollectionRequest createCollectionRequest = new CreateCollectionRequest() { CollectionId = collectionId }; CreateCollectionResponse createCollectionResponse = rekognitionClient.CreateCollection(createCollectionRequest); Console.WriteLine("CollectionArn : " + createCollectionResponse.CollectionArn); Console.WriteLine("Status code : " + createCollectionResponse.StatusCode); } } ``` ------ #### [ Node.JS ] 在下列範例中，將 `region` 的值取代為與您帳戶相關聯的區域名稱，並將 `collectionName` 的值替代為您集合的所需名稱。 將建立 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 { CreateCollectionCommand} from "@aws-sdk/client-rekognition"; import { RekognitionClient } from "@aws-sdk/client-rekognition"; import {fromIni} from '@aws-sdk/credential-providers'; // Set the AWS Region. const REGION = "region-name"; //e.g. "us-east-1" // Set the profile name const profileName = "profile-name" // Name the collection const collectionName = "collection-name" const rekogClient = new RekognitionClient({region: REGION, credentials: fromIni({profile: profileName,}), }); const createCollection = async (collectionName) => { try { console.log(`Creating collection: ${collectionName}`) const data = await rekogClient.send(new CreateCollectionCommand({CollectionId: collectionName})); console.log("Collection ARN:") console.log(data.CollectionARN) console.log("Status Code:") console.log(String(data.StatusCode)) console.log("Success.", data); return data; } catch (err) { console.log("Error", err.stack); } }; createCollection(collectionName) ``` ------ ## CreateCollection 操作要求 `CreationCollection` 的輸入是您要建立的集合的名稱。 ``` { "CollectionId": "MyCollection" } ``` ## CreateCollection 操作回應 Amazon Rekognition 建立集合並傳回新建立的集合之 Amazon Resource Name (ARN)。 ``` { "CollectionArn": "aws:rekognition:us-east-1:acct-id:collection/examplecollection", "StatusCode": 200 } ``` # 標記集合 您可以使用標籤來識別、組織、搜尋和篩選 Amazon Rekognition 集合。每個標籤都是由使用者定義的金鑰和值組成的標籤。 您也能通過 Identity and Access Management (IAM) 使用標籤來管控集合的存取。如需詳細資訊，請參閱[使用 AWS 資源標籤控制對資源的存取](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html)。 **Topics** + [將標籤新增至新集合](#add-tag-new-collection) + [將標籤新增至現有集合](#add-tag-existing-collection) + [列出集合中的標籤](#list-tags-collection) + [刪除集合中的標籤](#delete-tag-collection) ## 將標籤新增至新集合 您可以在使用 `CreateCollection` 操作建立集合時，將標籤新增至集合。在 `Tags` 陣列輸入參數中指定一或多個標籤。 ------ #### [ AWS CLI ] 使用您開發人員設定檔的名稱取代 `profile_name` 的值。 ``` aws rekognition create-collection --collection-id "collection-name" --tags "{"key1":"value1","key2":"value2"}" --profile profile-name ``` 對於 Windows 裝置： ``` aws rekognition create-collection --collection-id "collection-name" --tags "{\"key1\":\"value1\",\"key2\":\"value2\"}" --profile profile-name ``` ------ #### [ Python ] 將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。 ``` import boto3 def create_collection(collection_id): client = boto3.client('rekognition') # Create a collection print('Creating collection:' + collection_id) response = client.create_collection(CollectionId=collection_id) print('Collection ARN: ' + response['CollectionArn']) print('Status code: ' + str(response['StatusCode'])) print('Done...') def main(): collection_id = 'NewCollectionName' create_collection(collection_id) if __name__ == "__main__": main() ``` ------ ## 將標籤新增至現有集合 若要將一或多個標籤新增至現有的線索，請使用 `TagResource` 操作。指定待新增的集合的 Amazon Resource Name (ARN) (`ResourceArn`) 和標籤 (`Tags`)。下列範例顯示如何結合標記。 ------ #### [ AWS CLI ] 使用您開發人員設定檔的名稱取代 `profile_name` 的值。 ``` aws rekognition tag-resource --resource-arn collection-arn --tags "{"key1":"value1","key2":"value2"}" --profile profile-name ``` 對於 Windows 裝置： ``` aws rekognition tag-resource --resource-arn collection-arn --tags "{\"key1\":\"value1\",\"key2\":\"value2\"}" --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 create_tag(collection_id): session = boto3.Session(profile_name='default') client = session.client('rekognition') response = client.tag_resource(ResourceArn=collection_id, Tags={ "KeyName": "ValueName" }) print(response) if "'HTTPStatusCode': 200" in str(response): print("Success!!") def main(): collection_arn = "collection-arn" create_tag(collection_arn) if __name__ == "__main__": main() ``` ------ **注意** 如果您不知道集合的 Amazon Resource Name，則可以使用該 `DescribeCollection` 操作。 ## 列出集合中的標籤 若要列出附加至集合的標籤，請使用 `ListTagsForResource` 操作並指定集合的 ARN (`ResourceArn`)。回應是連接到指定集合的標籤鍵和值的映射。 ------ #### [ AWS CLI ] 使用您開發人員設定檔的名稱取代 `profile_name` 的值。 ``` aws rekognition list-tags-for-resource --resource-arn resource-arn --profile profile-name ``` ------ #### [ Python ] 將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。 ``` import boto3 def list_tags(): client = boto3.client('rekognition') response = client.list_tags_for_resource(ResourceArn="arn:aws:rekognition:region-name:5498347593847598:collection/NewCollectionName") print(response) def main(): list_tags() if __name__ == "__main__": main() ``` ------ 輸出會顯示連接至集合的標籤清單： ``` { "Tags": { "Dept": "Engineering", "Name": "Ana Silva Carolina", "Role": "Developer" } } ``` ## 刪除集合中的標籤 若要移除集合中的一個或多個標籤，請使用此 `UntagResource` 操作。指定要移除的模型 (`ResourceArn`) 和標籤鍵 (`Tag-Keys`) 的 ARN。 ------ #### [ AWS CLI ] 使用您開發人員設定檔的名稱取代 `profile_name` 的值。 ``` aws rekognition untag-resource --resource-arn resource-arn --profile profile-name --tag-keys "key1" "key2" ``` 或者，您可以使用以下格式指定標籤鍵： ``` --tag-keys key1,key2 ``` ------ #### [ Python ] 將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。 ``` import boto3 def list_tags(): client = boto3.client('rekognition') response = client.untag_resource(ResourceArn="arn:aws:rekognition:region-name:5498347593847598:collection/NewCollectionName", TagKeys=['KeyName']) print(response) def main(): list_tags() if __name__ == "__main__": main() ``` ------ # 列出集合 您可以使用 [ListCollections](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListCollections.html) 操作列出正在使用區域中的集合。 如需詳細資訊，請參閱 [管理集合](managing-face-collections.md#managing-collections)。 **若要列出集合 (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. 使用下列範例來呼叫 `ListCollections` 操作。 ------ #### [ Java ] 以下範例列出目前區域中的集合。 ``` //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 java.util.List; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.ListCollectionsRequest; import com.amazonaws.services.rekognition.model.ListCollectionsResult; public class ListCollections { public static void main(String[] args) throws Exception { AmazonRekognition amazonRekognition = AmazonRekognitionClientBuilder.defaultClient(); System.out.println("Listing collections"); int limit = 10; ListCollectionsResult listCollectionsResult = null; String paginationToken = null; do { if (listCollectionsResult != null) { paginationToken = listCollectionsResult.getNextToken(); } ListCollectionsRequest listCollectionsRequest = new ListCollectionsRequest() .withMaxResults(limit) .withNextToken(paginationToken); listCollectionsResult=amazonRekognition.listCollections(listCollectionsRequest); List < String > collectionIds = listCollectionsResult.getCollectionIds(); for (String resultId: collectionIds) { System.out.println(resultId); } } while (listCollectionsResult != null && listCollectionsResult.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/ListCollections.java)的完整範例。 ``` //snippet-start:[rekognition.java2.list_collections.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.ListCollectionsRequest; import software.amazon.awssdk.services.rekognition.model.ListCollectionsResponse; import software.amazon.awssdk.services.rekognition.model.RekognitionException; import java.util.List; //snippet-end:[rekognition.java2.list_collections.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 ListCollections { public static void main(String[] args) { Region region = Region.US_EAST_1; RekognitionClient rekClient = RekognitionClient.builder() .region(region) .credentialsProvider(ProfileCredentialsProvider.create("profile-name")) .build(); System.out.println("Listing collections"); listAllCollections(rekClient); rekClient.close(); } // snippet-start:[rekognition.java2.list_collections.main] public static void listAllCollections(RekognitionClient rekClient) { try { ListCollectionsRequest listCollectionsRequest = ListCollectionsRequest.builder() .maxResults(10) .build(); ListCollectionsResponse response = rekClient.listCollections(listCollectionsRequest); List collectionIds = response.collectionIds(); for (String resultId : collectionIds) { System.out.println(resultId); } } catch (RekognitionException e) { System.out.println(e.getMessage()); System.exit(1); } } // snippet-end:[rekognition.java2.list_collections.main] } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會顯示 CLI 操作的 JSON `list-collections` 輸出。使用您開發人員設定檔的名稱取代 `profile_name` 的值。 ``` aws rekognition list-collections --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_collections(): max_results=2 client=boto3.client('rekognition') #Display all the collections print('Displaying collections...') response=client.list_collections(MaxResults=max_results) collection_count=0 done=False while done==False: collections=response['CollectionIds'] for collection in collections: print (collection) collection_count+=1 if 'NextToken' in response: nextToken=response['NextToken'] response=client.list_collections(NextToken=nextToken,MaxResults=max_results) else: done=True return collection_count def main(): collection_count=list_collections() print("collections: " + str(collection_count)) if __name__ == "__main__": main() ``` ------ #### [ .NET ] 以下範例列出目前區域中的集合。 ``` //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 ListCollections { public static void Example() { AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); Console.WriteLine("Listing collections"); int limit = 10; ListCollectionsResponse listCollectionsResponse = null; String paginationToken = null; do { if (listCollectionsResponse != null) paginationToken = listCollectionsResponse.NextToken; ListCollectionsRequest listCollectionsRequest = new ListCollectionsRequest() { MaxResults = limit, NextToken = paginationToken }; listCollectionsResponse = rekognitionClient.ListCollections(listCollectionsRequest); foreach (String resultId in listCollectionsResponse.CollectionIds) Console.WriteLine(resultId); } while (listCollectionsResponse != null && listCollectionsResponse.NextToken != null); } } ``` ------ #### [ Node.js ] 將建立 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 { ListCollectionsCommand } from "@aws-sdk/client-rekognition"; import { RekognitionClient } from "@aws-sdk/client-rekognition"; import {fromIni} from '@aws-sdk/credential-providers'; // Set the AWS Region. const REGION = "region-name"; //e.g. "us-east-1" // Set the profile name const profileName = "profile-name" // Name the collection const rekogClient = new RekognitionClient({region: REGION, credentials: fromIni({profile: profileName,}), }); const listCollection = async () => { var max_results = 10 console.log("Displaying collections:") var response = await rekogClient.send(new ListCollectionsCommand({MaxResults: max_results})) var collection_count = 0 var done = false while (done == false){ var collections = response.CollectionIds collections.forEach(collection => { console.log(collection) collection_count += 1 }); return collection_count } } var collect_list = await listCollection() console.log(collect_list) ``` ------ ## ListCollections 操作要求 `ListCollections` 的輸入是要傳回的最大集合數。 ``` { "MaxResults": 2 } ``` 如果回應的集合多於 `MaxResults` 請求，則會傳回一個字符，您可以在後續的 `ListCollections` 呼叫中使用該字符獲取下一組結果。例如： ``` { "NextToken": "MGYZLAHX1T5a....", "MaxResults": 2 } ``` ## ListCollections 操作回應 Amazon Rekognition 傳回集合陣列 (`CollectionIds`)。個別陣列 (`FaceModelVersions`) 提供用於分析每個集合中人臉的人臉模型的版本。例如，在下列 JSON 回應中，集合 `MyCollection` 使用臉部模型的 2.0 版分析臉部。集合 `AnotherCollection` 使用臉部模型的 3.0 版本。如需詳細資訊，請參閱 [了解模型版本控制](face-detection-model.md)。 `NextToken` 是在後續的 `ListCollections` 呼叫中用於取得下一組結果的字符。 ``` { "CollectionIds": [ "MyCollection", "AnotherCollection" ], "FaceModelVersions": [ "2.0", "3.0" ], "NextToken": "MGYZLAHX1T5a...." } ``` # 描述集合 您可以使用 [DescribeCollection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DescribeCollection.html) 操作，來取得下列集合的相關資訊： + 編制為集合索引的臉部數。 + 與集合搭配使用的模型版本。如需詳細資訊，請參閱 [了解模型版本控制](face-detection-model.md)。 + 集合的 Amazon Resource Name (ARN)。 + 集合的建立日期和時間。 **描述集合 (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. 使用下列範例來呼叫 `DescribeCollection` 操作。 ------ #### [ Java ] 此範例描述一個集合。 將 `collectionId` 的值變更為所需集合的 ID。 ``` //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 com.amazonaws.samples; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.DescribeCollectionRequest; import com.amazonaws.services.rekognition.model.DescribeCollectionResult; public class DescribeCollection { public static void main(String[] args) throws Exception { String collectionId = "CollectionID"; AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); System.out.println("Describing collection: " + collectionId ); DescribeCollectionRequest request = new DescribeCollectionRequest() .withCollectionId(collectionId); DescribeCollectionResult describeCollectionResult = rekognitionClient.describeCollection(request); System.out.println("Collection Arn : " + describeCollectionResult.getCollectionARN()); System.out.println("Face count : " + describeCollectionResult.getFaceCount().toString()); System.out.println("Face model version : " + describeCollectionResult.getFaceModelVersion()); System.out.println("Created : " + describeCollectionResult.getCreationTimestamp().toString()); } } ``` ------ #### [ Java V2 ] 此程式碼取自 AWS 文件開發套件範例 GitHub 儲存庫。請參閱[此處](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/DescribeCollection.java)的完整範例。 ``` 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.DescribeCollectionRequest; import software.amazon.awssdk.services.rekognition.model.DescribeCollectionResponse; import software.amazon.awssdk.services.rekognition.model.RekognitionException; //snippet-end:[rekognition.java2.describe_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 DescribeCollection { public static void main(String[] args) { final String usage = "\n" + "Usage: " + " \n\n" + "Where:\n" + " collectionName - The name of the Amazon Rekognition collection. \n\n"; if (args.length != 1) { System.out.println(usage); System.exit(1); } String collectionName = args[0]; Region region = Region.US_EAST_1; RekognitionClient rekClient = RekognitionClient.builder() .region(region) .credentialsProvider(ProfileCredentialsProvider.create("profile-name")) .build(); describeColl(rekClient, collectionName); rekClient.close(); } // snippet-start:[rekognition.java2.describe_collection.main] public static void describeColl(RekognitionClient rekClient, String collectionName) { try { DescribeCollectionRequest describeCollectionRequest = DescribeCollectionRequest.builder() .collectionId(collectionName) .build(); DescribeCollectionResponse describeCollectionResponse = rekClient.describeCollection(describeCollectionRequest); System.out.println("Collection Arn : " + describeCollectionResponse.collectionARN()); System.out.println("Created : " + describeCollectionResponse.creationTimestamp().toString()); } catch(RekognitionException e) { System.out.println(e.getMessage()); System.exit(1); } } // snippet-end:[rekognition.java2.describe_collection.main] } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會顯示 CLI 操作的 JSON `describe-collection` 輸出。將 `collection-id` 的值變更為所需集合的 ID。將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。 ``` aws rekognition describe-collection --collection-id collection-name --profile profile-name ``` ------ #### [ Python ] 此範例描述一個集合。 將 `collection_id` 的值變更為所需集合的 ID。將建立 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 from botocore.exceptions import ClientError def describe_collection(collection_id): print('Attempting to describe collection ' + collection_id) session = boto3.Session(profile_name='default') client = session.client('rekognition') try: response = client.describe_collection(CollectionId=collection_id) print("Collection Arn: " + response['CollectionARN']) print("Face Count: " + str(response['FaceCount'])) print("Face Model Version: " + response['FaceModelVersion']) print("Timestamp: " + str(response['CreationTimestamp'])) except ClientError as e: if e.response['Error']['Code'] == 'ResourceNotFoundException': print('The collection ' + collection_id + ' was not found ') else: print('Error other than Not Found occurred: ' + e.response['Error']['Message']) print('Done...') def main(): collection_id = 'collection-name' describe_collection(collection_id) if __name__ == "__main__": main() ``` ------ #### [ .NET ] 此範例描述一個集合。 將 `collectionId` 的值變更為所需集合的 ID。 ``` //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 DescribeCollection { public static void Example() { AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); String collectionId = "CollectionID"; Console.WriteLine("Describing collection: " + collectionId); DescribeCollectionRequest describeCollectionRequest = new DescribeCollectionRequest() { CollectionId = collectionId }; DescribeCollectionResponse describeCollectionResponse = rekognitionClient.DescribeCollection(describeCollectionRequest); Console.WriteLine("Collection ARN: " + describeCollectionResponse.CollectionARN); Console.WriteLine("Face count: " + describeCollectionResponse.FaceCount); Console.WriteLine("Face model version: " + describeCollectionResponse.FaceModelVersion); Console.WriteLine("Created: " + describeCollectionResponse.CreationTimestamp); } } ``` ------ #### [ Node.js ] ``` //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 { DescribeCollectionCommand } from "@aws-sdk/client-rekognition"; import { RekognitionClient } from "@aws-sdk/client-rekognition"; import {fromIni} from '@aws-sdk/credential-providers'; // Set the AWS Region. const REGION = "region-name"; //e.g. "us-east-1" // Set the profile name const profileName = "profile-name" // Name the collection const rekogClient = new RekognitionClient({region: REGION, credentials: fromIni({profile: profileName,}), }); // Name the collection const collection_name = "collection-name" const describeCollection = async (collectionName) => { try { console.log(`Attempting to describe collection named - ${collectionName}`) var response = await rekogClient.send(new DescribeCollectionCommand({CollectionId: collectionName})) console.log('Collection Arn:') console.log(response.CollectionARN) console.log('Face Count:') console.log(response.FaceCount) console.log('Face Model Version:') console.log(response.FaceModelVersion) console.log('Timestamp:') console.log(response.CreationTimestamp) return response; // For unit tests. } catch (err) { console.log("Error", err.stack); } }; describeCollection(collection_name) ``` ------ ## DescribeCollection 操作要求 `DescribeCollection` 的輸入是所需集合的 ID，如以下 JSON 範例所示。 ``` { "CollectionId": "MyCollection" } ``` ## DescribeCollection 操作回應 回應包括： + 編制為集合索引的臉部數，`FaceCount`。 + 與集合配合使用的面模型版本 `FaceModelVersion`。如需詳細資訊，請參閱 [了解模型版本控制](face-detection-model.md)。 + 集合 Amazon Resource Name，`CollectionARN`。 + 集合的建立日期和時間，`CreationTimestamp`。`CreationTimestamp` 的值是 Unix epoch 時間到集合建立時所經的毫秒數。Unix epoch 時間為 1970 年 1 月 1 日周四 00:00:00 國際標準時間 (UTC)。如需詳細資訊，請參閱 [Unix 時間](https://en.wikipedia.org/wiki/Unix_time)。 ``` { "CollectionARN": "arn:aws:rekognition:us-east-1:nnnnnnnnnnnn:collection/MyCollection", "CreationTimestamp": 1.533422155042E9, "FaceCount": 200, "UserCount" : 20, "FaceModelVersion": "1.0" } ``` # 刪除集合 您可以使用 [DeleteCollection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DeleteCollection.html) 操作來刪除集合。 如需詳細資訊，請參閱 [管理集合](managing-face-collections.md#managing-collections)。 **若要刪除集合 (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. 使用下列範例來呼叫 `DeleteCollection` 操作。 ------ #### [ 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.DeleteCollectionRequest; import com.amazonaws.services.rekognition.model.DeleteCollectionResult; public class DeleteCollection { public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); String collectionId = "MyCollection"; System.out.println("Deleting collections"); DeleteCollectionRequest request = new DeleteCollectionRequest() .withCollectionId(collectionId); DeleteCollectionResult deleteCollectionResult = rekognitionClient.deleteCollection(request); System.out.println(collectionId + ": " + deleteCollectionResult.getStatusCode() .toString()); } } ``` ------ #### [ Java V2 ] 此程式碼取自 AWS 文件開發套件範例 GitHub 儲存庫。請參閱[此處](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/DeleteCollection.java)的完整範例。 ``` // snippet-start:[rekognition.java2.delete_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.DeleteCollectionRequest; import software.amazon.awssdk.services.rekognition.model.DeleteCollectionResponse; import software.amazon.awssdk.services.rekognition.model.RekognitionException; // snippet-end:[rekognition.java2.delete_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 DeleteCollection { public static void main(String[] args) { final String usage = "\n" + "Usage: " + " \n\n" + "Where:\n" + " collectionId - The id of the collection to delete. \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("Deleting collection: " + collectionId); deleteMyCollection(rekClient, collectionId); rekClient.close(); } // snippet-start:[rekognition.java2.delete_collection.main] public static void deleteMyCollection(RekognitionClient rekClient,String collectionId ) { try { DeleteCollectionRequest deleteCollectionRequest = DeleteCollectionRequest.builder() .collectionId(collectionId) .build(); DeleteCollectionResponse deleteCollectionResponse = rekClient.deleteCollection(deleteCollectionRequest); System.out.println(collectionId + ": " + deleteCollectionResponse.statusCode().toString()); } catch(RekognitionException e) { System.out.println(e.getMessage()); System.exit(1); } } // snippet-end:[rekognition.java2.delete_collection.main] } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會顯示 CLI 操作的 JSON `delete-collection` 輸出。將 `collection-id` 的值取代為您要刪除的集合的名稱。將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。 ``` aws rekognition delete-collection --collection-id collection-name --profile profile-name ``` ------ #### [ Python ] 此範例刪除一個集合。 將值 `collection_id` 變更為您要刪除的集合。將建立 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 from botocore.exceptions import ClientError def delete_collection(collection_id): print('Attempting to delete collection ' + collection_id) session = boto3.Session(profile_name='default') client = session.client('rekognition') status_code = 0 try: response = client.delete_collection(CollectionId=collection_id) status_code = response['StatusCode'] except ClientError as e: if e.response['Error']['Code'] == 'ResourceNotFoundException': print('The collection ' + collection_id + ' was not found ') else: print('Error other than Not Found occurred: ' + e.response['Error']['Message']) status_code = e.response['ResponseMetadata']['HTTPStatusCode'] return (status_code) def main(): collection_id = 'collection-name' status_code = delete_collection(collection_id) print('Status code: ' + str(status_code)) 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 DeleteCollection { public static void Example() { AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); String collectionId = "MyCollection"; Console.WriteLine("Deleting collection: " + collectionId); DeleteCollectionRequest deleteCollectionRequest = new DeleteCollectionRequest() { CollectionId = collectionId }; DeleteCollectionResponse deleteCollectionResponse = rekognitionClient.DeleteCollection(deleteCollectionRequest); Console.WriteLine(collectionId + ": " + deleteCollectionResponse.StatusCode); } } ``` ------ #### [ Node.js ] 將建立 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 { DeleteCollectionCommand } from "@aws-sdk/client-rekognition"; import { RekognitionClient } from "@aws-sdk/client-rekognition"; import {fromIni} from '@aws-sdk/credential-providers'; // Set the AWS Region. const REGION = "region-name"; //e.g. "us-east-1" // Set the profile name const profileName = "profile-name" // Name the collection const rekogClient = new RekognitionClient({region: REGION, credentials: fromIni({profile: profileName,}), }); // Name the collection const collection_name = "collection-name" const deleteCollection = async (collectionName) => { try { console.log(`Attempting to delete collection named - ${collectionName}`) var response = await rekogClient.send(new DeleteCollectionCommand({CollectionId: collectionName})) var status_code = response.StatusCode if (status_code = 200){ console.log("Collection successfully deleted.") } return response; // For unit tests. } catch (err) { console.log("Error", err.stack); } }; deleteCollection(collection_name) ``` ------ ## DeleteCollection 操作要求 `DeleteCollection` 的輸入是要刪除的集合 ID，如以下 JSON 範例所示。 ``` { "CollectionId": "MyCollection" } ``` ## DeleteCollection 操作回應 `DeleteCollection` 回應包含指示操作成功或失敗的 HTTP 狀態碼的。若集合成功刪除則傳回 `200`。 ``` {"StatusCode":200} ``` # 新增人臉到集合 您可以使用 [IndexFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html) 操作來偵測映像中的人臉，並將其新增至集合。對於每個偵測到的人臉，Amazon Rekognition 將擷取人臉特徵並將特徵資訊存放於資料庫中。此外，該命令將為每個在指定人臉集合中偵測到的人臉儲存中繼資料。Amazon Rekognition 不會儲存實際的映像位元組。 如需為編制索引提供適合臉部的相關資訊，請參閱 [人臉比較輸入映像的建議](recommendations-facial-input-images.md)。 `IndexFaces` 操作將保留每個人臉的下列資訊： + **多維度人臉特徵**：`IndexFaces` 使用人臉分析來擷取人臉特徵的多維度資訊，並將資訊儲存於人臉集合中。您無法直接存取此資訊。不過，Amazon Rekognition 會在搜尋人臉集合並比對人臉時使用此資訊。   + **中繼資料**：每個人臉的中繼資料包括要求的週框方塊、可信度等級 (週框方塊標註的人臉)、由 Amazon Rekognition 指定的 ID (人臉 ID 與映像 ID)、以及請求中的外部映像 ID (若您提供此資訊)。此資訊會在對於 `IndexFaces` API 呼叫的回應中回傳給您。如需範例，請參閱下列範例回應中的 `face` 元素。 此服務會傳回此中繼資料，以回應下列 API 呼叫：   + `[ListFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListFaces.html)` + 搜尋人臉操作：對於 [SearchFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFaces.html) 與 [SearchFacesByImage](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFacesByImage.html) 的回應將傳回對每個相符人臉的配對可信度，同時提供相符人臉之中繼資料。 由 `IndexFaces` 索引的臉部數量取決於與輸入集合相關聯的臉部偵測模型的版本。如需詳細資訊，請參閱 [了解模型版本控制](face-detection-model.md)。 有索引之人臉的相關資訊會以 [FaceRecord](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_FaceRecord.html) 物件陣列傳回。 您可能想要將編入索引的人臉與偵測到這些人臉的映像連結。例如，您可能想要維護映像的使用者端索引以及映像中的人臉。若要將人臉與映像連結，請在 `ExternalImageId` 請求參數中指定一個映像 ID。映像 ID 可以是檔案名稱或建立的另一個 ID。 除了上述關於 API 保留於人臉集合中的資訊外，API 也會傳回未保留於集合中的人臉詳細資訊。(請參閱下列範例回應中的 `faceDetail` 元素)。 **注意** `DetectFaces` 將傳回相同的資訊，因此您不需要同時呼叫 `DetectFaces` 和 `IndexFaces`。 ## 篩選人臉 這個 IndexFaces 操作可讓您篩選根據映像建立索引的人臉。運用 `IndexFaces`，您可以指定索引建立時所要使用的最多人臉數目，或者選擇只對高品質偵測人臉建立索引。 使用 `MaxFaces` 輸入參數，您可以指定 `IndexFaces` 在建立索引時所用的最多人臉數目。若您在建立索引時想要運用映像中尺寸最大的人臉，而不要使用尺寸最小的人臉時，例如，背景中站立人群的人臉，就能使用這項參數。 在預設情況下，`IndexFaces` 選擇用於篩選出臉部的品質列。您可以使用 `QualityFilter` 輸入參數，以明確設定品質列。這些值為： + `AUTO`：Amazon Rekognition 選擇並不用於篩選出人臉的品質列 (預設值)。 + `LOW`：除了品質最低的人臉之外，所有人臉都會加以索引。 + `MEDIUM` + `HIGH`：僅對品質最高的人臉行索引。 + `NONE`：不會根據品質來篩選掉任何人臉。 `IndexFaces` 篩選人臉的原因如下： + 相較於映像尺寸，人臉過小。 + 臉部過於模糊。 + 映像過暗。 + 臉部表情過於誇張。 + 臉部沒有足夠的細節，不適合臉部搜尋。 **注意** 若要使用品質篩選，您必須使用臉部模型第 3 版或更高版本的相關聯集合。若要取得與集合有關聯之人臉模型的版本，請呼叫 [DescribeCollection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DescribeCollection.html)。 未經 `IndexFaces` 建立索引之人臉的相關資訊，將透過 [UnindexedFace](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_UnindexedFace.html) 物件陣列傳回。`Reasons` 陣列包含為何無法為人臉建立索引的原因清單。例如，當值為 `EXCEEDS_MAX_FACES` 時，表示因為已偵測到透過 `MaxFaces` 指定的人臉數目，所以無法為人臉建立索引。 如需詳細資訊，請參閱 [管理集合中的人臉](managing-face-collections.md#collections-index-faces)。 **若要新增臉部到集合 (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. 將映像 (含有一個或多個人臉) 上傳至您的 Amazon S3 儲存貯體。 如需指示說明，請參閱《Amazon Simple Storage Service 使用者指南》**中的[上傳物件至 Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UploadingObjectsintoAmazonS3.html)。 1. 使用下列範例來呼叫 `IndexFaces` 操作。 ------ #### [ Java ] 此範例顯示新增到集合的人臉的人臉識別符。 將 `collectionId` 的值變更為要新增到人臉的集合的名稱。將 `bucket` 與 `photo` 的數值取代為您在步驟 2 中所使用的 Amazon S3 儲存貯體名稱與映像名稱。`.withMaxFaces(1)` 參數會將用於建立索引的人臉數目限制為 1。移除或變更其值以符合您的需求。 ``` //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.FaceRecord; import com.amazonaws.services.rekognition.model.Image; import com.amazonaws.services.rekognition.model.IndexFacesRequest; import com.amazonaws.services.rekognition.model.IndexFacesResult; import com.amazonaws.services.rekognition.model.QualityFilter; import com.amazonaws.services.rekognition.model.S3Object; import com.amazonaws.services.rekognition.model.UnindexedFace; import java.util.List; public class AddFacesToCollection { 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(); Image image = new Image() .withS3Object(new S3Object() .withBucket(bucket) .withName(photo)); IndexFacesRequest indexFacesRequest = new IndexFacesRequest() .withImage(image) .withQualityFilter(QualityFilter.AUTO) .withMaxFaces(1) .withCollectionId(collectionId) .withExternalImageId(photo) .withDetectionAttributes("DEFAULT"); IndexFacesResult indexFacesResult = rekognitionClient.indexFaces(indexFacesRequest); System.out.println("Results for " + photo); System.out.println("Faces indexed:"); List faceRecords = indexFacesResult.getFaceRecords(); for (FaceRecord faceRecord : faceRecords) { System.out.println(" Face ID: " + faceRecord.getFace().getFaceId()); System.out.println(" Location:" + faceRecord.getFaceDetail().getBoundingBox().toString()); } List unindexedFaces = indexFacesResult.getUnindexedFaces(); System.out.println("Faces not indexed:"); for (UnindexedFace unindexedFace : unindexedFaces) { System.out.println(" Location:" + unindexedFace.getFaceDetail().getBoundingBox().toString()); System.out.println(" Reasons:"); for (String reason : unindexedFace.getReasons()) { System.out.println(" " + reason); } } } } ``` ------ #### [ Java V2 ] 此程式碼取自 AWS 文件開發套件範例 GitHub 儲存庫。請參閱[此處](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/AddFacesToCollection.java)的完整範例。 ``` //snippet-start:[rekognition.java2.add_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.IndexFacesResponse; import software.amazon.awssdk.services.rekognition.model.IndexFacesRequest; import software.amazon.awssdk.services.rekognition.model.Image; import software.amazon.awssdk.services.rekognition.model.QualityFilter; import software.amazon.awssdk.services.rekognition.model.Attribute; import software.amazon.awssdk.services.rekognition.model.FaceRecord; import software.amazon.awssdk.services.rekognition.model.UnindexedFace; import software.amazon.awssdk.services.rekognition.model.RekognitionException; import software.amazon.awssdk.services.rekognition.model.Reason; import java.io.FileInputStream; import java.io.FileNotFoundException; import java.io.InputStream; import java.util.List; //snippet-end:[rekognition.java2.add_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 AddFacesToCollection { public static void main(String[] args) { final String usage = "\n" + "Usage: " + " \n\n" + "Where:\n" + " collectionName - The name 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(); addToCollection(rekClient, collectionId, sourceImage); rekClient.close(); } // snippet-start:[rekognition.java2.add_faces_collection.main] public static void addToCollection(RekognitionClient rekClient, String collectionId, String sourceImage) { try { InputStream sourceStream = new FileInputStream(sourceImage); SdkBytes sourceBytes = SdkBytes.fromInputStream(sourceStream); Image souImage = Image.builder() .bytes(sourceBytes) .build(); IndexFacesRequest facesRequest = IndexFacesRequest.builder() .collectionId(collectionId) .image(souImage) .maxFaces(1) .qualityFilter(QualityFilter.AUTO) .detectionAttributes(Attribute.DEFAULT) .build(); IndexFacesResponse facesResponse = rekClient.indexFaces(facesRequest); System.out.println("Results for the image"); System.out.println("\n Faces indexed:"); List faceRecords = facesResponse.faceRecords(); for (FaceRecord faceRecord : faceRecords) { System.out.println(" Face ID: " + faceRecord.face().faceId()); System.out.println(" Location:" + faceRecord.faceDetail().boundingBox().toString()); } List unindexedFaces = facesResponse.unindexedFaces(); System.out.println("Faces not indexed:"); for (UnindexedFace unindexedFace : unindexedFaces) { System.out.println(" Location:" + unindexedFace.faceDetail().boundingBox().toString()); System.out.println(" Reasons:"); for (Reason reason : unindexedFace.reasons()) { System.out.println("Reason: " + reason); } } } catch (RekognitionException | FileNotFoundException e) { System.out.println(e.getMessage()); System.exit(1); } } // snippet-end:[rekognition.java2.add_faces_collection.main] } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會顯示 CLI 操作的 JSON `index-faces` 輸出。 以您要儲存臉部的集合之名稱取代 `collection-id` 的值。將 `Bucket` 與 `Name` 的值取代為您在步驟 2 中所使用的 Amazon S3 儲存貯體名稱與映像檔案名稱。`max-faces` 參數會將用於建立索引的人臉數目限制為 1。移除或變更其值以符合您的需求。將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。 ``` aws rekognition index-faces --image '{"S3Object":{"Bucket":"bucket-name","Name":"file-name"}}' --collection-id "collection-id" \ --max-faces 1 --quality-filter "AUTO" --detection-attributes "ALL" \ --external-image-id "example-image.jpg" --profile profile-name ``` 如果您在 Windows 裝置上存取 CLI，請使用雙引號而非單引號，並以反斜線 (即\$1) 替代內部雙引號，以解決您可能遇到的任何剖析器錯誤。例如，請參閱下列內容： ``` aws rekognition index-faces --image "{\"S3Object\":{\"Bucket\":\"bucket-name\",\"Name\":\"image-name\"}}" \ --collection-id "collection-id" --max-faces 1 --quality-filter "AUTO" --detection-attributes "ALL" \ --external-image-id "example-image.jpg" --profile profile-name ``` ------ #### [ Python ] 此範例顯示新增到集合的人臉的人臉識別符。 將 `collectionId` 的值變更為要新增到人臉的集合的名稱。將 `bucket` 與 `photo` 的數值取代為您在步驟 2 中所使用的 Amazon S3 儲存貯體名稱與映像名稱。`MaxFaces` 輸入參數會將用於建立索引的人臉數目限制為 1。移除或變更其值以符合您的需求。將建立 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 add_faces_to_collection(bucket, photo, collection_id): session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') response = client.index_faces(CollectionId=collection_id, Image={'S3Object': {'Bucket': bucket, 'Name': photo}}, ExternalImageId=photo, MaxFaces=1, QualityFilter="AUTO", DetectionAttributes=['ALL']) print('Results for ' + photo) print('Faces indexed:') for faceRecord in response['FaceRecords']: print(' Face ID: ' + faceRecord['Face']['FaceId']) print(' Location: {}'.format(faceRecord['Face']['BoundingBox'])) print('Faces not indexed:') for unindexedFace in response['UnindexedFaces']: print(' Location: {}'.format(unindexedFace['FaceDetail']['BoundingBox'])) print(' Reasons:') for reason in unindexedFace['Reasons']: print(' ' + reason) return len(response['FaceRecords']) def main(): bucket = 'amzn-s3-demo-bucket' collection_id = 'collection-id' photo = 'photo-name' indexed_faces_count = add_faces_to_collection(bucket, photo, collection_id) print("Faces indexed count: " + str(indexed_faces_count)) if __name__ == "__main__": main() ``` ------ #### [ .NET ] 此範例顯示新增到集合的人臉的人臉識別符。 將 `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 System.Collections.Generic; using Amazon.Rekognition; using Amazon.Rekognition.Model; public class AddFaces { public static void Example() { String collectionId = "MyCollection"; String bucket = "amzn-s3-demo-bucket"; String photo = "input.jpg"; AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); Image image = new Image() { S3Object = new S3Object() { Bucket = bucket, Name = photo } }; IndexFacesRequest indexFacesRequest = new IndexFacesRequest() { Image = image, CollectionId = collectionId, ExternalImageId = photo, DetectionAttributes = new List(){ "ALL" } }; IndexFacesResponse indexFacesResponse = rekognitionClient.IndexFaces(indexFacesRequest); Console.WriteLine(photo + " added"); foreach (FaceRecord faceRecord in indexFacesResponse.FaceRecords) Console.WriteLine("Face detected: Faceid is " + faceRecord.Face.FaceId); } } ``` ------ ## IndexFaces 操作要求 `IndexFaces` 的輸入是要索引的映像和新增人臉或人臉的集合。 ``` { "CollectionId": "MyCollection", "Image": { "S3Object": { "Bucket": "bucket", "Name": "input.jpg" } }, "ExternalImageId": "input.jpg", "DetectionAttributes": [ "DEFAULT" ], "MaxFaces": 1, "QualityFilter": "AUTO" } ``` ## IndexFaces 操作回應 `IndexFaces` 傳回有關在映像中偵測到的人臉的資訊。例如，以下 JSON 回應包含輸入映像中偵測到的人臉的預設偵測屬性。範例當中還會示範已經超過 `MaxFaces` 輸入參數的值 ( `Reasons` 陣列包含 * EXCEEDS\$1MAX\$1FACES*)，導致無法為人臉建立索引。當 `Reasons` 包含像是 *LOW\$1SHARPNESS* 或 *LOW\$1BRIGHTNESS* 等品質原因時，導致無法為人臉建立索引。如需詳細資訊，請參閱 [UnindexedFace](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_UnindexedFace.html)。 ``` { "FaceModelVersion": "3.0", "FaceRecords": [ { "Face": { "BoundingBox": { "Height": 0.3247932195663452, "Left": 0.5055555701255798, "Top": 0.2743072211742401, "Width": 0.21444444358348846 }, "Confidence": 99.99998474121094, "ExternalImageId": "input.jpg", "FaceId": "b86e2392-9da1-459b-af68-49118dc16f87", "ImageId": "09f43d92-02b6-5cea-8fbd-9f187db2050d" }, "FaceDetail": { "BoundingBox": { "Height": 0.3247932195663452, "Left": 0.5055555701255798, "Top": 0.2743072211742401, "Width": 0.21444444358348846 }, "Confidence": 99.99998474121094, "Landmarks": [ { "Type": "eyeLeft", "X": 0.5751981735229492, "Y": 0.4010535478591919 }, { "Type": "eyeRight", "X": 0.6511467099189758, "Y": 0.4017036259174347 }, { "Type": "nose", "X": 0.6314528584480286, "Y": 0.4710812568664551 }, { "Type": "mouthLeft", "X": 0.5879443287849426, "Y": 0.5171778798103333 }, { "Type": "mouthRight", "X": 0.6444502472877502, "Y": 0.5164633989334106 } ], "Pose": { "Pitch": -10.313642501831055, "Roll": -1.0316886901855469, "Yaw": 18.079818725585938 }, "Quality": { "Brightness": 71.2919921875, "Sharpness": 78.74752044677734 } } } ], "OrientationCorrection": "", "UnindexedFaces": [ { "FaceDetail": { "BoundingBox": { "Height": 0.1329464465379715, "Left": 0.5611110925674438, "Top": 0.6832437515258789, "Width": 0.08777777850627899 }, "Confidence": 92.37225341796875, "Landmarks": [ { "Type": "eyeLeft", "X": 0.5796897411346436, "Y": 0.7452847957611084 }, { "Type": "eyeRight", "X": 0.6078574657440186, "Y": 0.742687463760376 }, { "Type": "nose", "X": 0.597953200340271, "Y": 0.7620673179626465 }, { "Type": "mouthLeft", "X": 0.5884202122688293, "Y": 0.7920381426811218 }, { "Type": "mouthRight", "X": 0.60627681016922, "Y": 0.7919750809669495 } ], "Pose": { "Pitch": 15.658954620361328, "Roll": -4.583454608917236, "Yaw": 10.558992385864258 }, "Quality": { "Brightness": 42.54612350463867, "Sharpness": 86.93206024169922 } }, "Reasons": [ "EXCEEDS_MAX_FACES" ] } ] } ``` 若要取得所有臉部資訊，請指定 `DetectionAttributes` 請求參數為『ALL』。例如，在以下範例回應中可找到 `faceDetail` 元素中的其它資訊，而這些資訊不會儲存在伺服器上： + 25 個臉部特徵點 (相較於上述範例中只有 5 個特徵點) + 十個面部屬性 (眼鏡、鬍鬚、人臉遮挡、眼睛凝視方向等) + 表情 (請參閱 `emotion` 元素) `face` 元素提供保留在伺服器上的中繼資料。 `FaceModelVersion` 是與集合相關聯的臉部模型版本。如需詳細資訊，請參閱 [了解模型版本控制](face-detection-model.md)。 `OrientationCorrection` 是映像的估計方向。如果您使用的臉部偵測模型版本大於第 3 版，則不會傳回方向更正資訊。如需詳細資訊，請參閱 [取得映像方向與週框方塊座標](images-orientation.md)。 下列範例回應顯示指定 ["ALL"] 時傳回的 JSON： ``` { "FaceModelVersion": "3.0", "FaceRecords": [ { "Face": { "BoundingBox": { "Height": 0.06333333253860474, "Left": 0.17185185849666595, "Top": 0.7366666793823242, "Width": 0.11061728745698929 }, "Confidence": 99.99999237060547, "ExternalImageId": "input.jpg", "FaceId": "578e2e1b-d0b0-493c-aa39-ba476a421a34", "ImageId": "9ba38e68-35b6-5509-9d2e-fcffa75d1653" }, "FaceDetail": { "AgeRange": { "High": 25, "Low": 15 }, "Beard": { "Confidence": 99.98077392578125, "Value": false }, "BoundingBox": { "Height": 0.06333333253860474, "Left": 0.17185185849666595, "Top": 0.7366666793823242, "Width": 0.11061728745698929 }, "Confidence": 99.99999237060547, "Emotions": [ { "Confidence": 95.40877532958984, "Type": "HAPPY" }, { "Confidence": 6.6088080406188965, "Type": "CALM" }, { "Confidence": 0.7385611534118652, "Type": "SAD" } ], "EyeDirection": { "yaw": 16.299732, "pitch": -6.407457, "confidence": 99.968704 } "Eyeglasses": { "Confidence": 99.96795654296875, "Value": false }, "EyesOpen": { "Confidence": 64.0671157836914, "Value": true }, "Gender": { "Confidence": 100, "Value": "Female" }, "Landmarks": [ { "Type": "eyeLeft", "X": 0.21361233294010162, "Y": 0.757106363773346 }, { "Type": "eyeRight", "X": 0.2518567442893982, "Y": 0.7599404454231262 }, { "Type": "nose", "X": 0.2262365221977234, "Y": 0.7711842060089111 }, { "Type": "mouthLeft", "X": 0.2050037682056427, "Y": 0.7801263332366943 }, { "Type": "mouthRight", "X": 0.2430567592382431, "Y": 0.7836716771125793 }, { "Type": "leftPupil", "X": 0.2161938101053238, "Y": 0.756662905216217 }, { "Type": "rightPupil", "X": 0.2523181438446045, "Y": 0.7603650689125061 }, { "Type": "leftEyeBrowLeft", "X": 0.20066319406032562, "Y": 0.7501518130302429 }, { "Type": "leftEyeBrowUp", "X": 0.2130996286869049, "Y": 0.7480520606040955 }, { "Type": "leftEyeBrowRight", "X": 0.22584207355976105, "Y": 0.7504606246948242 }, { "Type": "rightEyeBrowLeft", "X": 0.24509544670581818, "Y": 0.7526801824569702 }, { "Type": "rightEyeBrowUp", "X": 0.2582615911960602, "Y": 0.7516844868659973 }, { "Type": "rightEyeBrowRight", "X": 0.26881539821624756, "Y": 0.7554477453231812 }, { "Type": "leftEyeLeft", "X": 0.20624476671218872, "Y": 0.7568746209144592 }, { "Type": "leftEyeRight", "X": 0.22105035185813904, "Y": 0.7582521438598633 }, { "Type": "leftEyeUp", "X": 0.21401576697826385, "Y": 0.7553104162216187 }, { "Type": "leftEyeDown", "X": 0.21317370235919952, "Y": 0.7584449648857117 }, { "Type": "rightEyeLeft", "X": 0.24393919110298157, "Y": 0.7600628137588501 }, { "Type": "rightEyeRight", "X": 0.2598416209220886, "Y": 0.7605880498886108 }, { "Type": "rightEyeUp", "X": 0.2519053518772125, "Y": 0.7582084536552429 }, { "Type": "rightEyeDown", "X": 0.25177454948425293, "Y": 0.7612871527671814 }, { "Type": "noseLeft", "X": 0.2185886949300766, "Y": 0.774715781211853 }, { "Type": "noseRight", "X": 0.23328955471515656, "Y": 0.7759330868721008 }, { "Type": "mouthUp", "X": 0.22446128726005554, "Y": 0.7805567383766174 }, { "Type": "mouthDown", "X": 0.22087252140045166, "Y": 0.7891407608985901 } ], "MouthOpen": { "Confidence": 95.87068939208984, "Value": false }, "Mustache": { "Confidence": 99.9828109741211, "Value": false }, "Pose": { "Pitch": -0.9409101605415344, "Roll": 7.233824253082275, "Yaw": -2.3602254390716553 }, "Quality": { "Brightness": 32.01998519897461, "Sharpness": 93.67259216308594 }, "Smile": { "Confidence": 86.7142105102539, "Value": true }, "Sunglasses": { "Confidence": 97.38925170898438, "Value": false } } } ], "OrientationCorrection": "ROTATE_0" "UnindexedFaces": [] } ``` # 列出集合中的人臉和關聯使用者 您可以使用 [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: " + " \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 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 操作要求 `ListFaces` 的輸入值是您要為其列出人臉的集合 ID。`MaxResults`​ 是要傳回之人臉的最大值。ListFaces Face 也會透過人臉識別碼清單來篩選結果，並提供使用者 ID 僅列出與指定使用者相關聯的人臉。 ``` { "CollectionId": "MyCollection", "MaxResults": 1 } ``` 如果回應的人臉多於 `MaxResults` 請求的人臉，則會傳回一個字符，您可以在後續的 `ListFaces` 呼叫中使用該字符獲取下一組結果。例如： ``` { "CollectionId": "MyCollection", "NextToken": "sm+5ythT3aeEVIR4WA....", "MaxResults": 1 } ``` ## ListFaces 操作回應 `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" } ] } ``` # 删除集合中的人臉 您可以使用 [DeleteFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DeleteFaces.html) 操作删除集合中的人臉。如需詳細資訊，請參閱 [管理集合中的人臉](managing-face-collections.md#collections-index-faces)。 **從集合中刪除人臉** 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. 使用下列範例來呼叫 `DeleteFaces` 操作。 ------ #### [ Java ] 此範例删除集合中的單一人臉。 將 `collectionId` 的值變更為包含要刪除的人臉的集合。將 `faces` 的值變更為要刪除的人臉 ID。如果要刪除多個人臉相符，可新增人臉 ID 至 `faces` 陣列。 ``` //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.DeleteFacesRequest; import com.amazonaws.services.rekognition.model.DeleteFacesResult; import java.util.List; public class DeleteFacesFromCollection { public static final String collectionId = "MyCollection"; public static final String faces[] = {"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}; public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); DeleteFacesRequest deleteFacesRequest = new DeleteFacesRequest() .withCollectionId(collectionId) .withFaceIds(faces); DeleteFacesResult deleteFacesResult=rekognitionClient.deleteFaces(deleteFacesRequest); List < String > faceRecords = deleteFacesResult.getDeletedFaces(); System.out.println(Integer.toString(faceRecords.size()) + " face(s) deleted:"); for (String face: faceRecords) { System.out.println("FaceID: " + face); } } } ``` ------ #### [ Java V2 ] 此程式碼取自 AWS 文件開發套件範例 GitHub 儲存庫。請參閱[此處](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/DeleteFacesFromCollection.java)的完整範例。 ``` 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.DeleteFacesRequest; import software.amazon.awssdk.services.rekognition.model.RekognitionException; // snippet-end:[rekognition.java2.delete_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 DeleteFacesFromCollection { public static void main(String[] args) { final String usage = "\n" + "Usage: " + " \n\n" + "Where:\n" + " collectionId - The id of the collection from which faces are deleted. \n\n" + " faceId - The id of the face to delete. \n\n"; if (args.length != 1) { 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("Deleting collection: " + collectionId); deleteFacesCollection(rekClient, collectionId, faceId); rekClient.close(); } // snippet-start:[rekognition.java2.delete_faces_collection.main] public static void deleteFacesCollection(RekognitionClient rekClient, String collectionId, String faceId) { try { DeleteFacesRequest deleteFacesRequest = DeleteFacesRequest.builder() .collectionId(collectionId) .faceIds(faceId) .build(); rekClient.deleteFaces(deleteFacesRequest); System.out.println("The face was deleted from the collection."); } catch(RekognitionException e) { System.out.println(e.getMessage()); System.exit(1); } } // snippet-end:[rekognition.java2.delete_faces_collection.main] } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會顯示 CLI 操作的 JSON `delete-faces` 輸出。將 `collection-id` 的值取代為包含要刪除的臉部的集合的名稱。將 `face-ids` 的值取代為要刪除的臉部 ID 陣列。將建立 Rekognition 工作階段的行中 `profile_name` 值取代為您開發人員設定檔的名稱。 ``` aws rekognition delete-faces --collection-id "collection-id" --face-ids "faceid" --profile profile-name ``` ------ #### [ Python ] 此範例删除集合中的單一人臉。 將 `collectionId` 的值變更為包含要刪除的人臉的集合。將 `faces` 的值變更為要刪除的人臉 ID。如果要刪除多個人臉相符，可新增人臉 ID 至 `faces` 陣列。將建立 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 delete_faces_from_collection(collection_id, faces): session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') response = client.delete_faces(CollectionId=collection_id, FaceIds=faces) print(str(len(response['DeletedFaces'])) + ' faces deleted:') for faceId in response['DeletedFaces']: print(faceId) return len(response['DeletedFaces']) def main(): collection_id = 'collection-id' faces = [] faces.append("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") faces_count = delete_faces_from_collection(collection_id, faces) print("deleted faces count: " + str(faces_count)) if __name__ == "__main__": main() ``` ------ #### [ .NET ] 此範例删除集合中的單一人臉。 將 `collectionId` 的值變更為包含要刪除的人臉的集合。將 `faces` 的值變更為要刪除的人臉 ID。如果要刪除多個臉部相符，可新增臉部 ID 至 `faces` 清單。 ``` //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 System.Collections.Generic; using Amazon.Rekognition; using Amazon.Rekognition.Model; public class DeleteFaces { public static void Example() { String collectionId = "MyCollection"; List faces = new List() { "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }; AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); DeleteFacesRequest deleteFacesRequest = new DeleteFacesRequest() { CollectionId = collectionId, FaceIds = faces }; DeleteFacesResponse deleteFacesResponse = rekognitionClient.DeleteFaces(deleteFacesRequest); foreach (String face in deleteFacesResponse.DeletedFaces) Console.WriteLine("FaceID: " + face); } } ``` ------ ## DeleteFaces 操作要求 `DeleteFaces` 的輸入值是包含人臉的集合 ID，以及要刪除的人臉的人臉 ID 陣列。 ``` { "CollectionId": "MyCollection", "FaceIds": [ "daf29cac-f910-41e9-851f-6eeb0e08f973" ] } ``` ## DeleteFaces 操作回應 `DeleteFaces` 回應包含已刪除臉部的臉部 ID 陣列。 ``` { "DeletedFaces": [ "daf29cac-f910-41e9-851f-6eeb0e08f973" ] } ``` 如果輸入中提供的人臉 ID 目前與使用者相關聯，則會將其存在充分的 UnsuccessfulFaceDeletions 的一部分傳回。 ``` { "DeletedFaces": [ "daf29cac-f910-41e9-851f-6eeb0e08f973" ], "UnsuccessfulFaceDeletions" : [ { "FaceId" : "0b683aed-a0f1-48b2-9b5e-139e9cc2a757", "UserId" : "demoUser1", "Reason" : ["ASSOCIATED_TO_AN_EXISTING_USER"] } ] } ``` # 建立使用者 您可以使用 [CreateUser](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateUser.html) 操作，使用提供的唯一使用者 ID 在集合中建立新使用者。然後，您可以將多個人臉與新建立的使用者相關聯。 **建立使用者 (SDK)** 1. 如果您尚未執行： 1. 建立或更新具有 `AmazonRekognitionFullAccess` 權限的 IAM 使用者賬戶。如需詳細資訊，請參閱[步驟 1：設定 AWS 帳戶並建立使用者](setting-up.md#setting-up-iam)。 1. 安裝和設定 AWS CLI 和 AWS SDKs。如需詳細資訊，請參閱[步驟 2：設定 AWS CLI 和 AWS SDKs](setup-awscli-sdk.md)。 1. 使用下列範例來呼叫 `CreateUser` 操作。 ------ #### [ Java ] 此 Java 程式碼範例建立一個使用者。 ``` import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.CreateUserRequest; import com.amazonaws.services.rekognition.model.CreateUserResult; public class CreateUser { public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); //Replace collectionId and userId with the name of the user that you want to create in that target collection. String collectionId = "MyCollection"; String userId = "demoUser"; System.out.println("Creating new user: " + userId); CreateUserRequest request = new CreateUserRequest() .withCollectionId(collectionId) .withUserId(userId); rekognitionClient.createUser(request); } } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會使用 CLI `create-user` 操作建立使用者。 ``` aws rekognition create-user --user-id user-id --collection-id collection-name --region region-name --client-request-token request-token ``` ------ #### [ Python ] 此 Python 程式碼範例建立使用者。 ``` # 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 create_user(collection_id, user_id): """ Creates a new User within a collection specified by CollectionId. Takes UserId as a parameter, which is a user provided ID which should be unique within the collection. :param collection_id: The ID of the collection where the indexed faces will be stored at. :param user_id: ID for the UserID to be created. This ID needs to be unique within the collection. :return: The indexFaces response """ try: logger.info(f'Creating user: {collection_id}, {user_id}') client.create_user( CollectionId=collection_id, UserId=user_id ) except ClientError: logger.exception(f'Failed to create user with given user id: {user_id}') raise def main(): collection_id = "collection-id" user_id = "user-id" create_user(collection_id, user_id) if __name__ == "__main__": main() ``` ------ #### [ Go ] 此 Go 程式碼範例使用 AWS Go SDK V2，並建立使用者。 ``` package main import ( "context" "fmt" "log" "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/config" "github.com/aws/aws-sdk-go-v2/service/rekognition" ) func main() { // Load the AWS SDK configuration cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2")) if err != nil { log.Fatalf("Failed to load configuration: %v", err) } // Create a Rekognition client client := rekognition.NewFromConfig(cfg) // Set up the input parameters input := &rekognition.CreateUserInput{ CollectionId: aws.String("my-new-collection"), // Replace with your collection ID UserId: aws.String("user12345678910"), // Replace with desired user ID } // Call the CreateUser operation result, err := client.CreateUser(context.TODO(), input) if err != nil { log.Fatalf("Failed to create user: %v", err) } // Print out the results fmt.Printf("User created successfully:\n") } ``` ------ # 刪除使用者 可以使用 [DeleteUser](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DeleteUser.html) 操作，以根據提供的 UserID 從集合中刪除使用者。請注意，在刪除指定的 UserID 之前，與 UserID 相關聯的任何人臉都會與 UserID 斷開關聯。 **刪除使用者 (SDK)** 1. 如果您尚未執行： 1. 建立或更新具有 `AmazonRekognitionFullAccess` 權限的 IAM 使用者賬戶。如需詳細資訊，請參閱[步驟 1：設定 AWS 帳戶並建立使用者](setting-up.md#setting-up-iam)。 1. 安裝和設定 AWS CLI 和 AWS SDKs。如需詳細資訊，請參閱[步驟 2：設定 AWS CLI 和 AWS SDKs](setup-awscli-sdk.md)。 1. 使用下列範例來呼叫 `DeleteUser` 操作。 ------ #### [ Java ] 此 Java 程式碼範例會刪除使用者。 ``` import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.DeleteUserRequest; import com.amazonaws.services.rekognition.model.DeleteUserResult; public class DeleteUser { public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); //Replace collectionId and userId with the name of the user that you want to delete from that target collection. String collectionId = "MyCollection"; String userId = "demoUser"; System.out.println("Deleting existing user: " + userId); DeleteUserRequest request = new DeleteUserRequest() .withCollectionId(collectionId) .withUserId(userId); rekognitionClient.deleteUser(request); } } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會使用 CLI `create-user` 操作刪除使用者。 ``` aws rekognition delete-user --collection-id MyCollection --user-id user-id --collection-id collection-name --region region-name ``` ------ #### [ Python ] 此 Python 程式碼範例會刪除使用者。 ``` # 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 delete_user(collection_id, user_id): """ Delete the user from the given collection :param collection_id: The ID of the collection where user is stored. :param user_id: The ID of the user in the collection to delete. """ logger.info(f'Deleting user: {collection_id}, {user_id}') try: client.delete_user( CollectionId=collection_id, UserId=user_id ) except ClientError: logger.exception(f'Failed to delete user with given user id: {user_id}') raise def main(): collection_id = "collection-id" user_id = "user-id" delete_user(collection_id, user_id) if __name__ == "__main__": main() ``` ------ # 將人臉與使用者產生關聯 您可以使用 [AssociateFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_AssociatingFaces.html) 操作來將多個人臉與單一使用者關聯。若要將人臉與使用者建立關聯，必須先建立集合和使用者。請注意，人臉向量必須位於使用者向量所在的同一個集合中。 **若要關聯人臉 (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. 使用下列範例來呼叫 `AssociateFaces` 操作。 ------ #### [ Java ] 此 Java 程式碼範例將一個人臉與使用者相關聯。 ``` import java.util.Arrays; import java.util.List; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.AssociateFacesRequest; import com.amazonaws.services.rekognition.model.AssociateFacesResult; public class AssociateFaces { public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); /* Replace the below configurations to allow you successfully run the example @collectionId: The collection where user and faces are stored @userId: The user which faces will get associated to @faceIds: The list of face IDs that will get associated to the given user @userMatchThreshold: Minimum User match confidence required for the face to be associated with a User that has at least one faceID already associated */ String collectionId = "MyCollection"; String userId = "demoUser"; String faceId1 = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; String faceId2 = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; List faceIds = Arrays.asList(faceid1,faceid2); float userMatchThreshold = 0f; System.out.println("Associating faces to the existing user: " + userId); AssociateFacesRequest request = new AssociateFacesRequest() .withCollectionId(collectionId) .withUserId(userId) .withFaceIds(faceIds) .withUserMatchThreshold(userMatchThreshold); AssociateFacesResult result = rekognitionClient.associateFaces(request); System.out.println("Successful face associations: " + result.getAssociatedFaces().size()); System.out.println("Unsuccessful face associations: " + result.getUnsuccessfulFaceAssociations().size()); } } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會使用 CLI `associate-faces` 操作，將臉部與使用者建立關聯。 ``` aws rekognition associate-faces --user-id user-id --face-ids face-id-1 face-id-2 --collection-id collection-name --region region-name ``` ------ #### [ Python ] 這個 Python 程式碼範例將一個人臉與使用者相關聯。 ``` from botocore.exceptions import ClientError import boto3 import logging logger = logging.getLogger(__name__) session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') def associate_faces(collection_id, user_id, face_ids): """ Associate stored faces within collection to the given user :param collection_id: The ID of the collection where user and faces are stored. :param user_id: The ID of the user that we want to associate faces to :param face_ids: The list of face IDs to be associated to the given user :return: response of AssociateFaces API """ logger.info(f'Associating faces to user: {user_id}, {face_ids}') try: response = client.associate_faces( CollectionId=collection_id, UserId=user_id, FaceIds=face_ids ) print(f'- associated {len(response["AssociatedFaces"])} faces') except ClientError: logger.exception("Failed to associate faces to the given user") raise else: print(response) return response def main(): face_ids = ["faceId1", "faceId2"] collection_id = "collection-id" user_id = "user-id" associate_faces(collection_id, user_id, face_ids) if __name__ == "__main__": main() ``` ------ ## AssociateFaces 操作回應 `AssociateFaces` 的回應包括 `UserStatus`，也就是解除關聯要求的狀態，以及要關聯的 `FaceIds` 清單。也會傳回 `UnsuccessfulFaceAssociations` 的清單。將請求提交給 `AssociateFaces` 之後，操作可能需要一分鐘左右的時間才能完成。 基於這個原因，UserStatus 會傳回，取值如下： + 已建立：表示「使用者」已成功建立，且目前沒有與其相關聯的任何人臉。在「AssociateFaces」的任何成功呼叫之前，「使用者」將處於此狀態。 + 更新：表示「使用者」正在更新以反映新關聯/取消關聯的人臉，並在幾秒鐘內變為作用中狀態。此狀態下的搜尋結果可能包含「使用者」，客戶可以選擇從傳回的結果中忽略這些結果。 + 作用中：表示****「使用者」****已更新，以反映所有關聯/已取消關聯的人臉，且處於可搜尋狀態。 ``` { "UnsuccessfulFaceAssociations": [ { "Reasons": [ "LOW_MATCH_CONFIDENCE" ], "FaceId": "f5817d37-94f6-0000-bfee-1a2b3c4d5e6f", "Confidence": 0.9375374913215637 }, { "Reasons": [ "ASSOCIATED_TO_A_DIFFERENT_IDENTITY" ], "FaceId": "851cb847-dccc-1111-bfee-1a2b3c4d5e6f", "UserId": "demoUser2" } ], "UserStatus": "UPDATING", "AssociatedFaces": [ { "FaceId": "35ebbb41-7f67-2222-bfee-1a2b3c4d5e6f" } ] } ``` # 取消使用者人臉的關聯 您可以使用 [DisassociateFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DisassociateFaces.html) 操作來移除使用者 ID 與人臉 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. 使用下列範例來呼叫 `DisassociateFaces` 操作。 ------ #### [ Java ] 此 Java 範例會移除 FaceID 和 UserID 與 `DisassociateFaces` 操作之間的關聯。 ``` import java.util.Arrays; import java.util.List; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.DisassociateFacesRequest; import com.amazonaws.services.rekognition.model.DisassociateFacesResult; public class DisassociateFaces { public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); /* Replace the below configurations to allow you successfully run the example @collectionId: The collection where user and faces are stored @userId: The user which faces will get disassociated from @faceIds: The list of face IDs that will get disassociated from the given user */ String collectionId = "MyCollection"; String userId = "demoUser"; String faceId1 = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; String faceId2 = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; List faceIds = Arrays.asList(faceid1,faceid2); System.out.println("Disassociating faces from existing user: " + userId); DisassociateFacesRequest request = new DisassociateFacesRequest() .withCollectionId(collectionId) .withUserId(userId) .withFaceIds(faceIds) DisassociateFacesResult result = rekognitionClient.disassociateFaces(request); System.out.println("Successful face disassociations: " + result.getDisassociatedFaces().size()); System.out.println("Unsuccessful face disassociations: " + result.getUnsuccessfulFaceDisassociations().size()); } } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會移除 FaceID 與 UserID 與 `DisassociateFaces`操作之間的關聯。 ``` aws rekognition disassociate-faces --face-ids list-of-face-ids --user-id user-id --collection-id collection-name --region region-name ``` ------ #### [ Python ] 下列範例會移除 FaceID 和 UserID 與 `DisassociateFaces` 操作之間的關聯。 ``` from botocore.exceptions import ClientError import boto3 import logging logger = logging.getLogger(__name__) session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') def disassociate_faces(collection_id, user_id, face_ids): """ Disassociate stored faces within collection to the given user :param collection_id: The ID of the collection where user and faces are stored. :param user_id: The ID of the user that we want to disassociate faces from :param face_ids: The list of face IDs to be disassociated from the given user :return: response of AssociateFaces API """ logger.info(f'Disssociating faces from user: {user_id}, {face_ids}') try: response = client.disassociate_faces( CollectionId=collection_id, UserId=user_id, FaceIds=face_ids ) print(f'- disassociated {len(response["DisassociatedFaces"])} faces') except ClientError: logger.exception("Failed to disassociate faces from the given user") raise else: print(response) return response def main(): face_ids = ["faceId1", "faceId2"] collection_id = "collection-id" user_id = "user-id" disassociate_faces(collection_id, user_id, face_ids) if __name__ == "__main__": main() ``` ------ ## DisassociateFaces 操作回應 `DisassociateFaces` 的回應包括 `UserStatus`，也就是解除關聯要求的狀態，以及要取消關聯 `FaceIds` 的清單。也會傳回 `UnsuccessfulFaceDisassociations` 的清單。提交 DisassociateFaces 請求後，該操作可能需要一分鐘左右的時間才能完成。基於這個原因，UserStatus 會傳回，取值如下： + 已建立：表示「使用者」已成功建立，且目前沒有與其相關聯的任何人臉。在「AssociateFaces」的任何成功呼叫之前，「使用者」將處於此狀態。 + 更新：表示「使用者」正在更新以反映新關聯/取消關聯的人臉，並在幾秒鐘內變為作用中狀態。此狀態下的搜尋結果可能包含「使用者」，客戶可以選擇從傳回的結果中忽略這些結果。 + 作用中：表示****「使用者」****已更新，以反映所有關聯/已取消關聯的人臉，且處於可搜尋狀態。 ``` { "UserStatus": "UPDATING", "DisassociatedFaces": [ { "FaceId": "c92265d4-5f9c-43af-a58e-12be0ce02bc3" } ], "UnsuccessfulFaceDisassociations": [ { "Reasons": [ "ASSOCIATED_TO_A_DIFFERENT_IDENTITY" ], "FaceId": "f5817d37-94f6-4335-bfee-6cf79a3d806e", "UserId": "demoUser1" } ] } ``` # 在集合中列出人臉 可以使用 [ListUsers](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListUsers.html) 操作來列出 UserId 和 UserStatus。若要查看與 UserID 相關聯的 FaceID，請使用 [ListFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListFaces.html) 操作。 **若要列出使用者 (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. 使用下列範例來呼叫 `ListUsers` 操作。 ------ #### [ Java ] 此 Java 範例列出了使用 `ListUsers` 操作的集合中的使用者。 ``` import java.util.List; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.ListUsersRequest; import com.amazonaws.services.rekognition.model.ListUsersResult; import com.amazonaws.services.rekognition.model.User; public class ListUsers { public static void main(String[] args) throws Exception { AmazonRekognition amazonRekognition = AmazonRekognitionClientBuilder.defaultClient(); System.out.println("Listing users"); int limit = 10; ListUsersResult listUsersResult = null; String paginationToken = null; do { if (listUsersResult != null) { paginationToken = listUsersResult.getNextToken(); } ListUsersRequest request = new ListUsersRequest() .withCollectionId(collectionId) .withMaxResults(limit) .withNextToken(paginationToken); listUsersResult = amazonRekognition.listUsers(request); List users = listUsersResult.getUsers(); for (User currentUser: users) { System.out.println(currentUser.getUserId() + " : " + currentUser.getUserStatus()); } } while (listUsersResult.getNextToken() != null); } } ``` ------ #### [ AWS CLI ] 此 AWS CLI 命令會列出具有 `ListUsers`操作的集合中的使用者。 ``` aws rekognition list-users --collection-id collection-id --max-results number-of-max-results ``` ------ #### [ Python ] 下列範例會列出具有 `ListUsers` 操作的集合中的使用者。 ``` # 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 from pprint import pprint logger = logging.getLogger(__name__) session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') def list_users(collection_id): """ List all users from the given collection :param collection_id: The ID of the collection where user is stored. :return: response that contains list of Users found within given collection """ logger.info(f'Listing the users in collection: {collection_id}') try: response = client.list_users( CollectionId=collection_id ) pprint(response["Users"]) except ClientError: logger.exception(f'Failed to list all user from given collection: {collection_id}') raise else: return response def main(): collection_id = "collection-id" list_users(collection_id) if __name__ == "__main__": main() ``` ------ ## ListUsers 操作回應 對 ListUsers 請求的回應包含集合中的 `Users` 清單，以及使用者的 `UsedId` 和 `UserStatus`。 ``` { "NextToken": "B1asJT3bAb/ttuGgPFV8BZoBZyGQzlUHXbuTNLh48a6enU7kXKw43hpOwizW7LOk/Gk7Em09lznoq6+FcDCcSq2olrn7A98BLkt5keu+ZRVRUTyrXtT6J7Hmp+ieQ2an6Zu0qzPfcdPeaJ9eAxG2d0WNrzJgi5hvmjoiSTTfKX3MQz1sduWQkvAAs4hZfhZoKFahFlqWofshCXa/FHAAY3PL1PjxXbkNeSSMq8V7i1MlKCdrPVykCv9MokpPt7jtNvKPEZGUhxgBTFMxNWLEcFnzAiCWDg91dFy/LalshPjXA9UVc5Gx9vIJNQ/eO3cQRghAkCT3FOAiXsLAnA015ODTomZpWWVpqB21wKpI3LYmfAVFrDPGzpbTVlRmLsJm41bkmnBBBw9+DHz1Jn7zW+qc5Fs3yaHu0f51Xg==", "Users": [ { "UserId": "demoUser4", "UserStatus": "CREATED" }, { "UserId": "demoUser2", "UserStatus": "CREATED" } ] } ``` # 搜尋具有人臉 ID 的人臉 可以使用 [SearchFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_SearchFaces.html) 操作來搜尋集合中符合指定映像中最大人臉的人臉。 當偵測到人臉並加入至集合時，人臉 ID 將隨 [IndexFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html) 操作的回應一同回傳。如需詳細資訊，請參閱 [管理集合中的人臉](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 文件開發套件範例 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: " + " \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 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 命令會顯示 CLI 操作的 JSON `search-faces` 輸出。以您想要搜尋的臉部識別碼來取代`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 操作要求 `SearchFaces` 將根據人臉 ID (每個儲存在人臉集合中的人臉都有人臉 ID) 在指定的人臉集合中搜尋相似的人臉。回應不包含您要搜尋的臉部。它只包含類似的臉部。在預設情況下，`SearchFaces` 傳回在使用演算法偵測後相似度超過 80% 的人臉。相似度代表偵測到的人臉與輸入人臉間符合的程度。或者，可以使用 `FaceMatchThreshold` 來指定不同的值。 ``` { "CollectionId": "MyCollection", "FaceId": "0b683aed-a0f1-48b2-9b5e-139e9cc2a757", "MaxFaces": 2, "FaceMatchThreshold": 99 } ``` ## SearchFaces 操作回應 此操作會傳回一系列找到的人臉配對以及您提供的人臉 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" } } ] } ``` # 使用映像來搜尋人臉 您可以使用 [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: " + " \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 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 操作要求 `SearchFacesImageByImage` 的輸入參數是要搜尋的集合和來源映像位置。在此範例中，來源映像儲存於 Amazon S3 儲存貯體 (`S3Object`)。另外指定要傳回的最大臉數 (`Maxfaces`) 以及必須與要傳回的人臉 (`FaceMatchThreshold`) 相符的最小可信度。 ``` { "CollectionId": "MyCollection", "Image": { "S3Object": { "Bucket": "bucket", "Name": "input.jpg" } }, "MaxFaces": 2, "FaceMatchThreshold": 99 } ``` ## SearchFacesByImage 操作回應 指定輸入映像 (.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 } ``` # 搜尋使用者 (人臉識別碼/使用者 ID) 您可以使用 [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 操作請求 給定一個 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 操作回應 如果使用 `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" } ``` # 搜尋使用者 (映像) 針對與所提供映像中偵測到的最大人臉相符的集合使用者，`SearchUsersByImage` 會搜尋指定的 CollectionID。預設情況下，SearchUsersByImage 傳回相似度分數大於 80% 的 UserID。相似性表示 UserID 與提供的映像中偵測到的最大人臉相符的程度。如果傳回多個 UserID，則會依相似度分數最高到最低的順序列出這些 UserID。或者，您可以使用 UserMatchThreshold 來指定不同的值。如需詳細資訊，請參閱[管理集合中的使用者](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. 使用下列範例來呼叫 `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` 的回應包括適用於 `SearchedFace` 的物件 `FaceDetail`，以及適用於每個物件的 `UserId`、`Similarity` 和 `UserStatus` 的 UserMatches 清單。如果輸入映像包含多個人臉，則還將傳回 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" ] } ] } ``` # 在儲存的影片中搜尋人臉 您可以在集合搜尋與儲存的影片或串流影片中偵測到的人物相符的人臉。此區段涵蓋在儲存的影片中搜尋人臉的操作。如需在串流影片搜尋人臉的相關資訊，請參閱 [處理串流影片事件](streaming-video.md)。 必須使用 [IndexFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html) 先在集合中為要搜尋的人臉編制索引。如需詳細資訊，請參閱 [新增人臉到集合](add-faces-to-collection-procedure.md)。 Amazon Rekognition Video 人臉搜尋與分析儲存於 Amazon S3 儲存貯體中的影片的其它 Amazon Rekognition Video 操作一樣，採用相同的非同步工作流程。若要開始搜尋已儲存的影片，請呼叫 [StartFaceSearch](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartFaceSearch.html) 並提供您希望搜尋的集合 ID。Amazon Rekognition Video 會將影片分析的完成状态发布至 Amazon Simple Notification Service (Amazon SNS) 主题。如果影片分析成功，請呼叫 [GetFaceSearch](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_GeFaceSearch.html) 以取得搜尋結果。如需開始影片分析並取得結果的詳細資訊，請參閱 [呼叫 Amazon Rekognition Video 操作](api-video.md)。 下列程序說明如何在集合中搜尋與影片中偵測到的人物相符之人臉。程序也將說明如何取得影片中相符人物的追蹤資料。此程序會展開 [使用 Java 或 Python (SDK) 分析儲存於 Amazon S3 儲存貯體中的影片](video-analyzing-with-sqs.md) 中的程式碼，該操作使用 Amazon Simple Queue Service (Amazon SQS) 佇列來取得影片分析要求的完成狀態。 **搜尋與臉部相符的影片 (開發套件)** 1. [建立集合](create-collection-procedure.md)。 1. [將臉部編入集合索引](add-faces-to-collection-procedure.md)。 1. 執行 [使用 Java 或 Python (SDK) 分析儲存於 Amazon S3 儲存貯體中的影片](video-analyzing-with-sqs.md)。 1. 將下列程式碼新增至您在步驟 3 中建立的類別 `VideoDetect`。 ------ #### [ Java ] ``` //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.) //Face collection search in video ================================================================== private static void StartFaceSearchCollection(String bucket, String video, String collection) throws Exception{ NotificationChannel channel= new NotificationChannel() .withSNSTopicArn(snsTopicArn) .withRoleArn(roleArn); StartFaceSearchRequest req = new StartFaceSearchRequest() .withCollectionId(collection) .withVideo(new Video() .withS3Object(new S3Object() .withBucket(bucket) .withName(video))) .withNotificationChannel(channel); StartFaceSearchResult startPersonCollectionSearchResult = rek.startFaceSearch(req); startJobId=startPersonCollectionSearchResult.getJobId(); } //Face collection search in video ================================================================== private static void GetFaceSearchCollectionResults() throws Exception{ GetFaceSearchResult faceSearchResult=null; int maxResults=10; String paginationToken=null; do { if (faceSearchResult !=null){ paginationToken = faceSearchResult.getNextToken(); } faceSearchResult = rek.getFaceSearch( new GetFaceSearchRequest() .withJobId(startJobId) .withMaxResults(maxResults) .withNextToken(paginationToken) .withSortBy(FaceSearchSortBy.TIMESTAMP) ); VideoMetadata videoMetaData=faceSearchResult.getVideoMetadata(); System.out.println("Format: " + videoMetaData.getFormat()); System.out.println("Codec: " + videoMetaData.getCodec()); System.out.println("Duration: " + videoMetaData.getDurationMillis()); System.out.println("FrameRate: " + videoMetaData.getFrameRate()); System.out.println(); //Show search results List matches= faceSearchResult.getPersons(); for (PersonMatch match: matches) { long milliSeconds=match.getTimestamp(); System.out.print("Timestamp: " + Long.toString(milliSeconds)); System.out.println(" Person number: " + match.getPerson().getIndex()); List faceMatches = match.getFaceMatches(); if (faceMatches != null) { System.out.println("Matches in collection..."); for (FaceMatch faceMatch: faceMatches){ Face face=faceMatch.getFace(); System.out.println("Face Id: "+ face.getFaceId()); System.out.println("Similarity: " + faceMatch.getSimilarity().toString()); System.out.println(); } } System.out.println(); } System.out.println(); } while (faceSearchResult !=null && faceSearchResult.getNextToken() != null); } ``` 在函數 `main` 中，將下行: ``` StartLabelDetection(bucket, video); if (GetSQSMessageSuccess()==true) GetLabelDetectionResults(); ``` 取代為： ``` String collection="collection"; StartFaceSearchCollection(bucket, video, collection); if (GetSQSMessageSuccess()==true) GetFaceSearchCollectionResults(); ``` ------ #### [ Java V2 ] 此程式碼取自 AWS 文件開發套件範例 GitHub 儲存庫。請參閱[此處](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/VideoDetectFaces.java)的完整範例。 ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.rekognition.RekognitionClient; import software.amazon.awssdk.services.rekognition.model.*; import java.util.List; /** * 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 VideoDetectFaces { private static String startJobId = ""; public static void main(String[] args) { final String usage = """ Usage: