thing_groups

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

Overview

Name	thing_groups
Type	Resource
Id	aws.iot.thing_groups

Fields

The following fields are returned by SELECT queries:

describe_thing_group

Name	Datatype	Description
index_name	string	The dynamic thing group index name. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
query_string	string	The dynamic thing group search query string.
query_version	string	The dynamic thing group query version.
status	string	The dynamic thing group status. (ACTIVE, BUILDING, REBUILDING)
thing_group_arn	string	The thing group ARN.
thing_group_id	string	The thing group ID. (pattern: <code>[a-zA-Z0-9-]+</code>)
thing_group_metadata	object	Thing group metadata.
thing_group_name	string	The name of the thing group. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
thing_group_properties	object	Thing group properties.
version	integer (int64)	The version of the thing group.

list_thing_groups

Name	Datatype	Description
group_arn	string	The group ARN.
group_name	string	The group name. (pattern: <code>[a-zA-Z0-9:_-]+</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_thing_group	select	thing_group_name, region		Describe a thing group. Requires permission to access the DescribeThingGroup action.
list_thing_groups	select	region	nextToken, maxResults, parentGroup, namePrefixFilter, recursive	List the thing groups in your account. Requires permission to access the ListThingGroups action.
create_dynamic_thing_group	insert	thing_group_name, region, queryString		Creates a dynamic thing group. Requires permission to access the CreateDynamicThingGroup action.
create_thing_group	insert	thing_group_name, region		Create a thing group. This is a control plane operation. See Authorization for information about authorizing control plane actions. If the ThingGroup that you create has the exact same attributes as an existing ThingGroup, you will get a 200 success response. Requires permission to access the CreateThingGroup action.
update_thing_group	update	thing_group_name, region, thingGroupProperties		Update a thing group. Requires permission to access the UpdateThingGroup action.
add_thing_to_thing_group	update	region		Adds a thing to a thing group. Requires permission to access the AddThingToThingGroup action.
delete_thing_group	delete	thing_group_name, region	expectedVersion	Deletes a thing group. Requires permission to access the DeleteThingGroup action.
delete_dynamic_thing_group	exec	thing_group_name, region	expectedVersion	Deletes a dynamic thing group. Requires permission to access the DeleteDynamicThingGroup action.
update_dynamic_thing_group	exec	thing_group_name, region, thingGroupProperties		Updates a dynamic thing group. Requires permission to access the UpdateDynamicThingGroup action.
remove_thing_from_thing_group	exec	region		Remove the specified thing from the specified group. You must specify either a thingGroupArn or a thingGroupName to identify the thing group and either a thingArn or a thingName to identify the thing to remove from the thing group. Requires permission to access the RemoveThingFromThingGroup action.

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)
thing_group_name	string	The name of the dynamic thing group to update.
expectedVersion	integer (int64)	The expected version of the dynamic thing group to delete.
maxResults	integer	The maximum number of results to return at one time.
namePrefixFilter	string	A filter that limits the results to those with the specified name prefix.
nextToken	string	To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.
parentGroup	string	A filter that limits the results to those with the specified parent group.
recursive	boolean	If true, return child groups as well.

SELECT examples

describe_thing_group

Describe a thing group. Requires permission to access the DescribeThingGroup action.

SELECT
index_name,
query_string,
query_version,
status,
thing_group_arn,
thing_group_id,
thing_group_metadata,
thing_group_name,
thing_group_properties,
version
FROM aws.iot.thing_groups
WHERE thing_group_name = '{{ thing_group_name }}' -- required
AND region = '{{ region }}' -- required
;

list_thing_groups

List the thing groups in your account. Requires permission to access the ListThingGroups action.

SELECT
group_arn,
group_name
FROM aws.iot.thing_groups
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
AND parentGroup = '{{ parentGroup }}'
AND namePrefixFilter = '{{ namePrefixFilter }}'
AND recursive = '{{ recursive }}'
;

INSERT examples

create_dynamic_thing_group

Creates a dynamic thing group. Requires permission to access the CreateDynamicThingGroup action.

INSERT INTO aws.iot.thing_groups (
thingGroupProperties,
indexName,
queryString,
queryVersion,
tags,
thing_group_name,
region
)
SELECT 
'{{ thingGroupProperties }}',
'{{ indexName }}',
'{{ queryString }}' /* required */,
'{{ queryVersion }}',
'{{ tags }}',
'{{ thing_group_name }}',
'{{ region }}'
RETURNING
index_name,
query_string,
query_version,
thing_group_arn,
thing_group_id,
thing_group_name
;

create_thing_group

Create a thing group. This is a control plane operation. See Authorization for information about authorizing control plane actions. If the ThingGroup that you create has the exact same attributes as an existing ThingGroup, you will get a 200 success response. Requires permission to access the CreateThingGroup action.

INSERT INTO aws.iot.thing_groups (
parentGroupName,
thingGroupProperties,
tags,
thing_group_name,
region
)
SELECT 
'{{ parentGroupName }}',
'{{ thingGroupProperties }}',
'{{ tags }}',
'{{ thing_group_name }}',
'{{ region }}'
RETURNING
thing_group_arn,
thing_group_id,
thing_group_name
;

Manifest

# Description fields are for documentation purposes
- name: thing_groups
props:
  - name: thing_group_name
    value: "{{ thing_group_name }}"
    description: Required parameter for the thing_groups resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the thing_groups resource.
  - name: thingGroupProperties
    description: |
      Thing group properties.
    value:
      thingGroupDescription: "{{ thingGroupDescription }}"
      attributePayload:
        attributes: "{{ attributes }}"
        merge: {{ merge }}
  - name: indexName
    value: "{{ indexName }}"
  - name: queryString
    value: "{{ queryString }}"
  - name: queryVersion
    value: "{{ queryVersion }}"
  - name: tags
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: parentGroupName
    value: "{{ parentGroupName }}"

UPDATE examples

update_thing_group

Update a thing group. Requires permission to access the UpdateThingGroup action.

UPDATE aws.iot.thing_groups
SET 
thingGroupProperties = '{{ thingGroupProperties }}',
expectedVersion = {{ expectedVersion }}
WHERE 
thing_group_name = '{{ thing_group_name }}' --required
AND region = '{{ region }}' --required
AND thingGroupProperties = '{{ thingGroupProperties }}' --required
RETURNING
version;

add_thing_to_thing_group

Adds a thing to a thing group. Requires permission to access the AddThingToThingGroup action.

UPDATE aws.iot.thing_groups
SET 
thingGroupName = '{{ thingGroupName }}',
thingGroupArn = '{{ thingGroupArn }}',
thingName = '{{ thingName }}',
thingArn = '{{ thingArn }}',
overrideDynamicGroups = {{ overrideDynamicGroups }}
WHERE 
region = '{{ region }}' --required;

DELETE examples

delete_thing_group

Deletes a thing group. Requires permission to access the DeleteThingGroup action.

DELETE FROM aws.iot.thing_groups
WHERE thing_group_name = '{{ thing_group_name }}' --required
AND region = '{{ region }}' --required
AND expectedVersion = '{{ expectedVersion }}'
;

Lifecycle Methods

delete_dynamic_thing_group

Deletes a dynamic thing group. Requires permission to access the DeleteDynamicThingGroup action.

EXEC aws.iot.thing_groups.delete_dynamic_thing_group 
@thing_group_name='{{ thing_group_name }}' --required, 
@region='{{ region }}' --required, 
@expectedVersion='{{ expectedVersion }}'
;

update_dynamic_thing_group

Updates a dynamic thing group. Requires permission to access the UpdateDynamicThingGroup action.

EXEC aws.iot.thing_groups.update_dynamic_thing_group 
@thing_group_name='{{ thing_group_name }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"thingGroupProperties": "{{ thingGroupProperties }}", 
"expectedVersion": {{ expectedVersion }}, 
"indexName": "{{ indexName }}", 
"queryString": "{{ queryString }}", 
"queryVersion": "{{ queryVersion }}"
}'
;

remove_thing_from_thing_group

Remove the specified thing from the specified group. You must specify either a thingGroupArn or a thingGroupName to identify the thing group and either a thingArn or a thingName to identify the thing to remove from the thing group. Requires permission to access the RemoveThingFromThingGroup action.

EXEC aws.iot.thing_groups.remove_thing_from_thing_group 
@region='{{ region }}' --required 
@@json=
'{
"thingGroupName": "{{ thingGroupName }}", 
"thingGroupArn": "{{ thingGroupArn }}", 
"thingName": "{{ thingName }}", 
"thingArn": "{{ thingArn }}"
}'
;