AmazonRekognitionClient.AssociateFaces Method (AssociateFacesRequest)

Associates one or more faces with an existing UserID. Takes an array of FaceIds. Each FaceId that are present in the FaceIds 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.

Note that the total number of faces that can be associated with a single UserID is also limited to 100. Once a UserID has 100 faces associated with it, no additional faces can be added. If more API calls are made after the limit is reached, a ServiceQuotaExceededException will result.

The UserMatchThreshold parameter specifies the minimum user match confidence required for the face to be associated with a UserID that has at least one FaceID already associated. This ensures that the FaceIds are associated with the right UserID. The value ranges from 0-100 and default value is 75.

If successful, an array of AssociatedFace objects containing the associated FaceIds is returned. If a given face is already associated with the given UserID, it will be ignored and will not be returned in the response. If a given face is already associated to a different UserID, isn't found in the collection, doesn’t meet the UserMatchThreshold, or there are already 100 faces associated with the UserID, it will be returned as part of an array of UnsuccessfulFaceAssociations.

The UserStatus reflects the status of an operation which updates a UserID representation with a list of given faces. The UserStatus can be:

ACTIVE - All associations or disassociations of FaceID(s) for a UserID are complete.
CREATED - A UserID has been created, but has no FaceID(s) associated with it.
UPDATING - A UserID is being updated and there are current associations or disassociations of FaceID(s) taking place.

Note:

For .NET Core this operation is only available in asynchronous form. Please refer to AssociateFacesAsync.

Namespace: Amazon.Rekognition
Assembly: AWSSDK.Rekognition.dll
Version: 3.x.y.z

Syntax

public virtual AssociateFacesResponse AssociateFaces(
         AssociateFacesRequest request
)

Parameters

request: Type: Amazon.Rekognition.Model.AssociateFacesRequest

Container for the necessary parameters to execute the AssociateFaces service method.

Return Value

Type: AssociateFacesResponse

The response from the AssociateFaces service method, as returned by Rekognition.

Exceptions

Exception	Condition
AccessDeniedException	You are not authorized to perform the action.
ConflictException	A User with the same Id already exists within the collection, or the update or deletion of the User caused an inconsistent state. **
IdempotentParameterMismatchException	A ClientRequestToken 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.
InternalServerErrorException	Amazon Rekognition experienced a service issue. Try your call again.
InvalidParameterException	Input parameter violated a constraint. Validate your parameter before calling the API operation again.
ProvisionedThroughputExceededException	The number of requests exceeded your throughput limit. If you want to increase this limit, contact Amazon Rekognition.
ResourceNotFoundException	The resource specified in the request cannot be found.
ServiceQuotaExceededException	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.
ThrottlingException	Amazon Rekognition is temporarily unable to process the request. Try your call again.

Examples

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

AssociateFaces


var client = new AmazonRekognitionClient();
var response = client.AssociateFaces(new AssociateFacesRequest 
{
    ClientRequestToken = "550e8400-e29b-41d4-a716-446655440002",
    CollectionId = "MyCollection",
    FaceIds = new List<string> {
        "f5817d37-94f6-4335-bfee-6cf79a3d806e",
        "851cb847-dccc-4fea-9309-9f4805967855",
        "35ebbb41-7f67-4263-908d-dd0ecba05ab9"
    },
    UserId = "DemoUser",
    UserMatchThreshold = 70
});

List<AssociatedFace> associatedFaces = response.AssociatedFaces;
List<UnsuccessfulFaceAssociation> unsuccessfulFaceAssociations = response.UnsuccessfulFaceAssociations;
string userStatus = response.UserStatus;

Version Information

.NET Framework:
Supported in: 4.5 and newer, 3.5

AmazonRekognitionClient.AssociateFaces (AssociateFacesRequest)

Method