users

Creates, updates, deletes, gets or lists a users resource.

Overview

Name	users
Type	Resource
Id	aws.rekognition.users

Fields

The following fields are returned by SELECT queries:

search_users

Name	Datatype	Description
face_model_version	string	Version number of the face detection model associated with the input CollectionId.
searched_face	object	Contains the ID of a face that was used to search for matches in a collection.
searched_user	object	Contains the ID of the UserID that was used to search for matches in a collection.
user_matches	array	An array of UserMatch objects that matched the input face along with the confidence in the match. Array will be empty if there are no matches.

list_users

Name	Datatype	Description
user_id	string	A provided ID for the User. Unique within the collection. (pattern: <code>[a-zA-Z0-9_.-:]+</code>)
user_status	string	Communicates if the UserID has been updated with latest set of faces to be associated with the UserID. (ACTIVE, UPDATING, CREATING, CREATED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
search_users	select	region		Searches for UserIDs within a collection based on a FaceId or UserId. This API can be used to find the closest UserID (with a highest similarity) to associate a face. The request must be provided with either FaceId or UserId. The operation returns an array of UserID that match the FaceId or UserId, ordered by similarity score with the highest similarity first.
list_users	select	region		Returns metadata of the User such as UserID in the specified collection. Anonymous User (to reserve faces without any identity) is not returned as part of this request. The results are sorted by system generated primary key ID. If the response is truncated, NextToken is returned in the response that can be used in the subsequent request to retrieve the next set of identities.
create_user	insert	region, CollectionId, UserId		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. The provided UserId will alias the system generated UUID to make the UserId more user friendly. Uses a ClientToken, an idempotency token that ensures a call to CreateUser completes only once. If the value is not supplied, the AWS SDK generates an idempotency token for the requests. This prevents retries after a network error results from making multiple CreateUser calls.
delete_user	delete	region		Deletes the specified UserID within the collection. Faces that are associated with the UserID are disassociated from the UserID before deleting the specified UserID. If the specified Collection or UserID is already deleted or not found, a ResourceNotFoundException will be thrown. If the action is successful with a 200 response, an empty HTTP body is returned.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

search_users

Searches for UserIDs within a collection based on a FaceId or UserId. This API can be used to find the closest UserID (with a highest similarity) to associate a face. The request must be provided with either FaceId or UserId. The operation returns an array of UserID that match the FaceId or UserId, ordered by similarity score with the highest similarity first.

SELECT
face_model_version,
searched_face,
searched_user,
user_matches
FROM aws.rekognition.users
WHERE region = '{{ region }}' -- required
;

list_users

Returns metadata of the User such as UserID in the specified collection. Anonymous User (to reserve faces without any identity) is not returned as part of this request. The results are sorted by system generated primary key ID. If the response is truncated, NextToken is returned in the response that can be used in the subsequent request to retrieve the next set of identities.

SELECT
user_id,
user_status
FROM aws.rekognition.users
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_user

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. The provided UserId will alias the system generated UUID to make the UserId more user friendly. Uses a ClientToken, an idempotency token that ensures a call to CreateUser completes only once. If the value is not supplied, the AWS SDK generates an idempotency token for the requests. This prevents retries after a network error results from making multiple CreateUser calls.

INSERT INTO aws.rekognition.users (
CollectionId,
UserId,
ClientRequestToken,
region
)
SELECT 
'{{ CollectionId }}' /* required */,
'{{ UserId }}' /* required */,
'{{ ClientRequestToken }}',
'{{ region }}'
;

Manifest

# Description fields are for documentation purposes
- name: users
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the users resource.
  - name: CollectionId
    value: "{{ CollectionId }}"
    description: |
      The ID of an existing collection to which the new UserID needs to be created.
  - name: UserId
    value: "{{ UserId }}"
    description: |
      ID for the UserID to be created. This ID needs to be unique within the collection.
  - name: ClientRequestToken
    value: "{{ ClientRequestToken }}"
    description: |
      Idempotent token used to identify the request to CreateUser. If you use the same token with multiple CreateUser requests, the same response is returned. Use ClientRequestToken to prevent the same request from being processed more than once.

DELETE examples

delete_user

Deletes the specified UserID within the collection. Faces that are associated with the UserID are disassociated from the UserID before deleting the specified UserID. If the specified Collection or UserID is already deleted or not found, a ResourceNotFoundException will be thrown. If the action is successful with a 200 response, an empty HTTP body is returned.

DELETE FROM aws.rekognition.users
WHERE region = '{{ region }}' --required
;