things

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

Overview

Name	things
Type	Resource
Id	aws.iot.things

Fields

The following fields are returned by SELECT queries:

describe_thing

Name	Datatype	Description
attributes	object	The thing attributes.
billing_group_name	string	The name of the billing group the thing belongs to. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
default_client_id	string	The default MQTT client ID. For a typical device, the thing name is also used as the default MQTT client ID. Although we don’t require a mapping between a thing's registry name and its use of MQTT client IDs, certificates, or shadow state, we recommend that you choose a thing name and use it as the MQTT client ID for the registry and the Device Shadow service. This lets you better organize your IoT fleet without removing the flexibility of the underlying device certificate model or shadows.
thing_arn	string	The ARN of the thing to describe.
thing_id	string	The ID of the thing to describe.
thing_name	string	The name of the thing. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
thing_type_name	string	The thing type name. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
version	integer (int64)	The current version of the thing record in the registry. To avoid unintentional changes to the information in the registry, you can pass the version information in the expectedVersion parameter of the UpdateThing and DeleteThing calls.

list_things

Name	Datatype	Description
attributes	object	A list of thing attributes which are name-value pairs.
thing_arn	string	The thing ARN.
thing_name	string	The name of the thing. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
thing_type_name	string	The name of the thing type, if the thing has been associated with a type. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
version	integer (int64)	The version of the thing record in the registry.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_thing	select	thing_name, region		Gets information about the specified thing. Requires permission to access the DescribeThing action.
list_things	select	region	nextToken, maxResults, attributeName, attributeValue, thingTypeName, usePrefixAttributeValue	Lists your things. Use the attributeName and attributeValue parameters to filter your things. For example, calling ListThings with attributeName=Color and attributeValue=Red retrieves all things in the registry that contain an attribute Color with the value Red. For more information, see List Things from the Amazon Web Services IoT Core Developer Guide. Requires permission to access the ListThings action. You will not be charged for calling this API if an Access denied error is returned. You will also not be charged if no attributes or pagination token was provided in request and no pagination token and no results were returned.
create_thing	insert	thing_name, region		Creates a thing record in the registry. If this call is made multiple times using the same thing name and configuration, the call will succeed. If this call is made with the same thing name but different configuration a ResourceAlreadyExistsException is thrown. This is a control plane operation. See Authorization for information about authorizing control plane actions. Requires permission to access the CreateThing action.
register_thing	insert	region, templateBody		Provisions a thing in the device registry. RegisterThing calls other IoT control plane APIs. These calls might exceed your account level IoT Throttling Limits and cause throttle errors. Please contact Amazon Web Services Customer Support to raise your throttling limits if necessary. Requires permission to access the RegisterThing action.
update_thing	update	thing_name, region		Updates the data for a thing. Requires permission to access the UpdateThing action.
delete_thing	delete	thing_name, region	expectedVersion	Deletes the specified thing. Returns successfully with no error if the deletion is successful or you specify a thing that doesn't exist. Requires permission to access the DeleteThing action.
start_thing_registration_task	exec	region, templateBody, inputFileBucket, inputFileKey, roleArn		Creates a bulk thing provisioning task. Requires permission to access the StartThingRegistrationTask action.
stop_thing_registration_task	exec	task_id, region		Cancels a bulk thing provisioning task. Requires permission to access the StopThingRegistrationTask 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)
task_id	string	The bulk thing provisioning task ID.
thing_name	string	The name of the thing to delete.
attributeName	string	The attribute name used to search for things.
attributeValue	string	The attribute value used to search for things.
expectedVersion	integer (int64)	The expected version of the thing record in the registry. If the version of the record in the registry does not match the expected version specified in the request, the DeleteThing request is rejected with a VersionConflictException.
maxResults	integer	The maximum number of results to return in this operation.
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.
thingTypeName	string	The name of the thing type used to search for things.
usePrefixAttributeValue	boolean	When true, the action returns the thing resources with attribute values that start with the attributeValue provided. When false, or not present, the action returns only the thing resources with attribute values that match the entire attributeValue provided.

SELECT examples

describe_thing

Gets information about the specified thing. Requires permission to access the DescribeThing action.

SELECT
attributes,
billing_group_name,
default_client_id,
thing_arn,
thing_id,
thing_name,
thing_type_name,
version
FROM aws.iot.things
WHERE thing_name = '{{ thing_name }}' -- required
AND region = '{{ region }}' -- required
;

list_things

Lists your things. Use the attributeName and attributeValue parameters to filter your things. For example, calling ListThings with attributeName=Color and attributeValue=Red retrieves all things in the registry that contain an attribute Color with the value Red. For more information, see List Things from the Amazon Web Services IoT Core Developer Guide. Requires permission to access the ListThings action. You will not be charged for calling this API if an Access denied error is returned. You will also not be charged if no attributes or pagination token was provided in request and no pagination token and no results were returned.

SELECT
attributes,
thing_arn,
thing_name,
thing_type_name,
version
FROM aws.iot.things
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
AND attributeName = '{{ attributeName }}'
AND attributeValue = '{{ attributeValue }}'
AND thingTypeName = '{{ thingTypeName }}'
AND usePrefixAttributeValue = '{{ usePrefixAttributeValue }}'
;

INSERT examples

create_thing

Creates a thing record in the registry. If this call is made multiple times using the same thing name and configuration, the call will succeed. If this call is made with the same thing name but different configuration a ResourceAlreadyExistsException is thrown. This is a control plane operation. See Authorization for information about authorizing control plane actions. Requires permission to access the CreateThing action.

INSERT INTO aws.iot.things (
thingTypeName,
attributePayload,
billingGroupName,
thing_name,
region
)
SELECT 
'{{ thingTypeName }}',
'{{ attributePayload }}',
'{{ billingGroupName }}',
'{{ thing_name }}',
'{{ region }}'
RETURNING
thing_arn,
thing_id,
thing_name
;

register_thing

Provisions a thing in the device registry. RegisterThing calls other IoT control plane APIs. These calls might exceed your account level IoT Throttling Limits and cause throttle errors. Please contact Amazon Web Services Customer Support to raise your throttling limits if necessary. Requires permission to access the RegisterThing action.

INSERT INTO aws.iot.things (
templateBody,
parameters,
region
)
SELECT 
'{{ templateBody }}' /* required */,
'{{ parameters }}',
'{{ region }}'
RETURNING
certificate_pem,
resource_arns
;

Manifest

# Description fields are for documentation purposes
- name: things
props:
  - name: thing_name
    value: "{{ thing_name }}"
    description: Required parameter for the things resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the things resource.
  - name: thingTypeName
    value: "{{ thingTypeName }}"
  - name: attributePayload
    description: |
      The attribute payload.
    value:
      attributes: "{{ attributes }}"
      merge: {{ merge }}
  - name: billingGroupName
    value: "{{ billingGroupName }}"
  - name: templateBody
    value: "{{ templateBody }}"
  - name: parameters
    value: "{{ parameters }}"

UPDATE examples

update_thing

Updates the data for a thing. Requires permission to access the UpdateThing action.

UPDATE aws.iot.things
SET 
thingTypeName = '{{ thingTypeName }}',
attributePayload = '{{ attributePayload }}',
expectedVersion = {{ expectedVersion }},
removeThingType = {{ removeThingType }}
WHERE 
thing_name = '{{ thing_name }}' --required
AND region = '{{ region }}' --required;

DELETE examples

delete_thing

Deletes the specified thing. Returns successfully with no error if the deletion is successful or you specify a thing that doesn't exist. Requires permission to access the DeleteThing action.

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

Lifecycle Methods

start_thing_registration_task

Creates a bulk thing provisioning task. Requires permission to access the StartThingRegistrationTask action.

EXEC aws.iot.things.start_thing_registration_task 
@region='{{ region }}' --required 
@@json=
'{
"templateBody": "{{ templateBody }}", 
"inputFileBucket": "{{ inputFileBucket }}", 
"inputFileKey": "{{ inputFileKey }}", 
"roleArn": "{{ roleArn }}"
}'
;

stop_thing_registration_task

Cancels a bulk thing provisioning task. Requires permission to access the StopThingRegistrationTask action.

EXEC aws.iot.things.stop_thing_registration_task 
@task_id='{{ task_id }}' --required, 
@region='{{ region }}' --required
;