large_person_group

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

Overview

Name	large_person_group
Type	Resource
Id	azure.ai_vision_face.large_person_group

Fields

The following fields are returned by SELECT queries:

get_face

Name	Datatype	Description
persistedFaceId	string	Face ID of the face. Required.
userData	string	User-provided data attached to the face. The length limit is 1K.

get_person

Name	Datatype	Description
name	string	User defined name, maximum length is 128. Required.
persistedFaceIds	array	Face ids of registered faces in the person.
personId	string	ID of the person. Required.
userData	string	Optional user defined data. Length should not exceed 16K.

get

Name	Datatype	Description
name	string	User defined name, maximum length is 128. Required.
largePersonGroupId	string	ID of the container. Required.
recognitionModel	string	Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds. Known values are: "recognition_01", "recognition_02", "recognition_03", and "recognition_04". (recognition_01, recognition_02, recognition_03, recognition_04)
userData	string	Optional user defined data. Length should not exceed 16K.

get_large_person_groups

Name	Datatype	Description
name	string	User defined name, maximum length is 128. Required.
largePersonGroupId	string	ID of the container. Required.
recognitionModel	string	Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds. Known values are: "recognition_01", "recognition_02", "recognition_03", and "recognition_04". (recognition_01, recognition_02, recognition_03, recognition_04)
userData	string	Optional user defined data. Length should not exceed 16K.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_face	select	large_person_group_id, person_id, persisted_face_id, endpoint, api_version		Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group-person-face for more details.
get_person	select	large_person_group_id, person_id, endpoint, api_version		Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group-person for more details.
get	select	large_person_group_id, endpoint, api_version	returnRecognitionModel	Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group for more details.
get_large_person_groups	select	endpoint, api_version	start, top, returnRecognitionModel	List all existing Large Person Groups' largePersonGroupId, name, userData and recognitionModel. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-groups for more details.
create	insert	large_person_group_id, endpoint, api_version		Create a new Large Person Group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/create-large-person-group for more details.
update	update	large_person_group_id, endpoint, api_version		Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/update-large-person-group for more details.
delete	delete	large_person_group_id, endpoint, api_version		Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/delete-large-person-group for more details.
get_training_status	exec	large_person_group_id, endpoint, api_version		To check Large Person Group training status completed or still ongoing. Large Person Group training is an asynchronous operation triggered by "Train Large Person Group" API. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group-training-status for more details.
delete_person	exec	large_person_group_id, person_id, endpoint, api_version		Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/delete-large-person-group-person for more details.
update_person	exec	large_person_group_id, person_id, endpoint, api_version		Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/update-large-person-group-person for more details.
get_persons	exec	large_person_group_id, endpoint, api_version	start, top	List all persons' information in the specified Large Person Group, including personId, name, userData and persistedFaceIds of registered person faces. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group-persons for more details.
create_person	exec	large_person_group_id, endpoint, api_version		Create a new person in a specified Large Person Group. To add face to this person, please call "Add Large Person Group Person Face". Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/create-large-person-group-person for more details.
delete_face	exec	large_person_group_id, person_id, persisted_face_id, endpoint, api_version		Delete a face from a person in a Large Person Group by specified largePersonGroupId, personId and persistedFaceId. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/delete-large-person-group-person-face for more details.
update_face	exec	large_person_group_id, person_id, persisted_face_id, endpoint, api_version		Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/update-large-person-group-person-face for more details.
train	exec	large_person_group_id, endpoint, api_version		Submit a Large Person Group training task. Training is a crucial step that only a trained Large Person Group can be used by "Identify From Large Person Group". Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/train-large-person-group for more details.
add_face_from_url	exec	large_person_group_id, person_id, endpoint, api_version	targetFace, detectionModel, userData	Add a face to a person into a Large Person Group for face identification or verification. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/add-large-person-group-person-face-from-url for more details.

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
api_version	string	The service endpoint host (no scheme), e.g. myaccount.table.cosmos.azure.com:443 - value of the client apiVersion parameter. (default: )
endpoint	string	The service endpoint host (no scheme), e.g. myaccount.table.cosmos.azure.com:443 - value of the client endpoint parameter. (default: )
large_person_group_id	string	ID of the container. Required.
persisted_face_id	string	Face ID of the face. Required.
person_id	string	ID of the person. Required.
detectionModel	string	The 'detectionModel' associated with the detected faceIds. Supported 'detectionModel' values include 'detection_01', 'detection_02' and 'detection_03'. The default value is 'detection_01'. Known values are: "detection_01", "detection_02", and "detection_03". Default value is None.
returnRecognitionModel	boolean	Return 'recognitionModel' or not. The default value is false. Default value is None.
start	string	List resources greater than the "start". It contains no more than 64 characters. Default is empty. Default value is None.
targetFace	array	A face rectangle to specify the target face to be added to a person, in the format of 'targetFace=left,top,width,height'. Default value is None.
top	integer	The number of items to list, ranging in [1, 1000]. Default is 1000. Default value is None.
userData	string	User-provided data attached to the face. The size limit is 1K. Default value is None.

SELECT examples

get_face

Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group-person-face for more details.

SELECT
persistedFaceId,
userData
FROM azure.ai_vision_face.large_person_group
WHERE large_person_group_id = '{{ large_person_group_id }}' -- required
AND person_id = '{{ person_id }}' -- required
AND persisted_face_id = '{{ persisted_face_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND api_version = '{{ api_version }}' -- required
;

get_person

Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group-person for more details.

SELECT
name,
persistedFaceIds,
personId,
userData
FROM azure.ai_vision_face.large_person_group
WHERE large_person_group_id = '{{ large_person_group_id }}' -- required
AND person_id = '{{ person_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND api_version = '{{ api_version }}' -- required
;

get

Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group for more details.

SELECT
name,
largePersonGroupId,
recognitionModel,
userData
FROM azure.ai_vision_face.large_person_group
WHERE large_person_group_id = '{{ large_person_group_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND api_version = '{{ api_version }}' -- required
AND returnRecognitionModel = '{{ returnRecognitionModel }}'
;

get_large_person_groups

List all existing Large Person Groups' largePersonGroupId, name, userData and recognitionModel. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-groups for more details.

SELECT
name,
largePersonGroupId,
recognitionModel,
userData
FROM azure.ai_vision_face.large_person_group
WHERE endpoint = '{{ endpoint }}' -- required
AND api_version = '{{ api_version }}' -- required
AND start = '{{ start }}'
AND top = '{{ top }}'
AND returnRecognitionModel = '{{ returnRecognitionModel }}'
;

INSERT examples

create

Create a new Large Person Group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/create-large-person-group for more details.

INSERT INTO azure.ai_vision_face.large_person_group (
large_person_group_id,
endpoint,
api_version
)
SELECT 
'{{ large_person_group_id }}',
'{{ endpoint }}',
'{{ api_version }}'
;

Manifest

# Description fields are for documentation purposes
- name: large_person_group
props:
  - name: large_person_group_id
    value: "{{ large_person_group_id }}"
    description: Required parameter for the large_person_group resource.
  - name: endpoint
    value: "{{ endpoint }}"
    description: Required parameter for the large_person_group resource.
  - name: api_version
    value: "{{ api_version }}"
    description: Required parameter for the large_person_group resource.

UPDATE examples

update

Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/update-large-person-group for more details.

UPDATE azure.ai_vision_face.large_person_group
SET 
-- No updatable properties
WHERE 
large_person_group_id = '{{ large_person_group_id }}' --required
AND endpoint = '{{ endpoint }}' --required
AND api_version = '{{ api_version }}' --required;

DELETE examples

delete

Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/delete-large-person-group for more details.

DELETE FROM azure.ai_vision_face.large_person_group
WHERE large_person_group_id = '{{ large_person_group_id }}' --required
AND endpoint = '{{ endpoint }}' --required
AND api_version = '{{ api_version }}' --required
;

Lifecycle Methods

get_training_status

To check Large Person Group training status completed or still ongoing. Large Person Group training is an asynchronous operation triggered by "Train Large Person Group" API. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group-training-status for more details.

EXEC azure.ai_vision_face.large_person_group.get_training_status 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required
;

delete_person

Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/delete-large-person-group-person for more details.

EXEC azure.ai_vision_face.large_person_group.delete_person 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@person_id='{{ person_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required
;

update_person

Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/update-large-person-group-person for more details.

EXEC azure.ai_vision_face.large_person_group.update_person 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@person_id='{{ person_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required
;

get_persons

List all persons' information in the specified Large Person Group, including personId, name, userData and persistedFaceIds of registered person faces. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/get-large-person-group-persons for more details.

EXEC azure.ai_vision_face.large_person_group.get_persons 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required, 
@start='{{ start }}', 
@top='{{ top }}'
;

create_person

Create a new person in a specified Large Person Group. To add face to this person, please call "Add Large Person Group Person Face". Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/create-large-person-group-person for more details.

EXEC azure.ai_vision_face.large_person_group.create_person 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required
;

delete_face

Delete a face from a person in a Large Person Group by specified largePersonGroupId, personId and persistedFaceId. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/delete-large-person-group-person-face for more details.

EXEC azure.ai_vision_face.large_person_group.delete_face 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@person_id='{{ person_id }}' --required, 
@persisted_face_id='{{ persisted_face_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required
;

update_face

Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/update-large-person-group-person-face for more details.

EXEC azure.ai_vision_face.large_person_group.update_face 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@person_id='{{ person_id }}' --required, 
@persisted_face_id='{{ persisted_face_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required
;

train

Submit a Large Person Group training task. Training is a crucial step that only a trained Large Person Group can be used by "Identify From Large Person Group". Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/train-large-person-group for more details.

EXEC azure.ai_vision_face.large_person_group.train 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required
;

add_face_from_url

Add a face to a person into a Large Person Group for face identification or verification. Please refer to https://learn.microsoft.com/rest/api/face/person-group-operations/add-large-person-group-person-face-from-url for more details.

EXEC azure.ai_vision_face.large_person_group.add_face_from_url 
@large_person_group_id='{{ large_person_group_id }}' --required, 
@person_id='{{ person_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@api_version='{{ api_version }}' --required, 
@targetFace='{{ targetFace }}', 
@detectionModel='{{ detectionModel }}', 
@userData='{{ userData }}'
;