associate_faces ¶

def associate_faces(
    self,
    collection_id: "capo_rekognition.types.collection_id.CollectionId",
    user_id: "capo_rekognition.types.user_id.UserId",
    face_ids: "capo_rekognition.types.user_face_id_list.UserFaceIdList",
    *,
    config_overrides: Optional[RekognitionClientConfig] = None,
    user_match_threshold: Optional["capo_rekognition.types.percent.Percent"] = None,
    client_request_token: Optional[
        "capo_rekognition.types.client_request_token.ClientRequestToken"
    ] = None,
) -> "capo_rekognition.types.associate_faces_response.AssociateFacesResponse":
    """<p>Associates one or more faces with an existing UserID. Takes an array of <code>FaceIds</code>. Each <code>FaceId</code> that are present in the <code>FaceIds</code> list is associated with the provided UserID. The number of FaceIds that can be used as input in a single request is limited to 100.</p> <p>Note that the total number of faces that can be associated with a single <code>UserID</code> is also limited to 100. Once a <code>UserID</code> has 100 faces associated with it, no additional faces can be added. If more API calls are made after the limit is reached, a <code>ServiceQuotaExceededException</code> will result.</p> <p>The <code>UserMatchThreshold</code> parameter specifies the minimum user match confidence required for the face to be associated with a UserID that has at least one <code>FaceID</code> already associated. This ensures that the <code>FaceIds</code> are associated with the right UserID. The value ranges from 0-100 and default value is 75. </p> <p>If successful, an array of <code>AssociatedFace</code> objects containing the associated <code>FaceIds</code> is returned. If a given face is already associated with the given <code>UserID</code>, it will be ignored and will not be returned in the response. If a given face is already associated to a different <code>UserID</code>, isn't found in the collection, doesn’t meet the <code>UserMatchThreshold</code>, or there are already 100 faces associated with the <code>UserID</code>, it will be returned as part of an array of <code>UnsuccessfulFaceAssociations.</code> </p> <p>The <code>UserStatus</code> reflects the status of an operation which updates a UserID representation with a list of given faces. The <code>UserStatus</code> can be: </p> <ul> <li> <p>ACTIVE - All associations or disassociations of FaceID(s) for a UserID are complete.</p> </li> <li> <p>CREATED - A UserID has been created, but has no FaceID(s) associated with it.</p> </li> <li> <p>UPDATING - A UserID is being updated and there are current associations or disassociations of FaceID(s) taking place.</p> </li> </ul>

    Args:
        collection_id: <p>The ID of an existing collection containing the UserID.</p>
        user_id: <p>The ID for the existing UserID.</p>
        face_ids: <p>An array of FaceIDs to associate with the UserID.</p>
        user_match_threshold: <p>An optional value specifying the minimum confidence in the UserID match to return. The default value is 75.</p>
        client_request_token: <p>Idempotent token used to identify the request to <code>AssociateFaces</code>. If you use the same token with multiple <code>AssociateFaces</code> requests, the same response is returned. Use ClientRequestToken to prevent the same request from being processed more than once.</p>

    Raises:
        capo_rekognition.errors.access_denied_exception.AccessDeniedException: <p>You are not authorized to perform the action.</p>
        capo_rekognition.errors.conflict_exception.ConflictException: <p> A User with the same Id already exists within the collection, or the update or deletion of the User caused an inconsistent state. ** </p>
        capo_rekognition.errors.idempotent_parameter_mismatch_exception.IdempotentParameterMismatchException: <p>A <code>ClientRequestToken</code> input parameter was reused with an operation, but at least one of the other input parameters is different from the previous call to the operation.</p>
        capo_rekognition.errors.internal_server_error.InternalServerError: <p>Amazon Rekognition experienced a service issue. Try your call again.</p>
        capo_rekognition.errors.invalid_parameter_exception.InvalidParameterException: <p>Input parameter violated a constraint. Validate your parameter before calling the API operation again.</p>
        capo_rekognition.errors.provisioned_throughput_exceeded_exception.ProvisionedThroughputExceededException: <p>The number of requests exceeded your throughput limit. If you want to increase this limit, contact Amazon Rekognition.</p>
        capo_rekognition.errors.resource_not_found_exception.ResourceNotFoundException: <p>The resource specified in the request cannot be found.</p>
        capo_rekognition.errors.service_quota_exceeded_exception.ServiceQuotaExceededException: <p></p> <p>The size of the collection exceeds the allowed limit. For more information, see Guidelines and quotas in Amazon Rekognition in the Amazon Rekognition Developer Guide. </p>
        capo_rekognition.errors.throttling_exception.ThrottlingException: <p>Amazon Rekognition is temporarily unable to process the request. Try your call again.</p>
        capo_rekognition.errors.UnknownServiceError: The service returned an error code this client does not model.

    Examples:
        AssociateFaces
        This operation associates one or more faces with an existing UserID.

        >>> client.associate_faces(collection_id='MyCollection', user_id='DemoUser', face_ids=['f5817d37-94f6-4335-bfee-6cf79a3d806e', '851cb847-dccc-4fea-9309-9f4805967855', '35ebbb41-7f67-4263-908d-dd0ecba05ab9'], user_match_threshold=70, client_request_token='550e8400-e29b-41d4-a716-446655440002')
    """

    def _handler(
        req: "OperationRequest[capo_rekognition.types.associate_faces_request.AssociateFacesRequest]",
    ) -> OperationResponse[
        "capo_rekognition.types.associate_faces_response.AssociateFacesResponse"
    ]:
        import capo_rekognition._operations.rekognition_service.associate_faces

        output, http_response = (
            capo_rekognition._operations.rekognition_service.associate_faces.associate_faces(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("AssociateFaces")
    )
    input_: capo_rekognition.types.associate_faces_request.AssociateFacesRequest = {
        "collection_id": collection_id,
        "user_id": user_id,
        "face_ids": face_ids,
    }
    if user_match_threshold is not None:
        input_["user_match_threshold"] = user_match_threshold
    if client_request_token is None:
        client_request_token = str(uuid.uuid4())
    input_["client_request_token"] = client_request_token

    response = execute_pipeline(
        OperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    response.response.close()
    return response.output