2018/11/19 - AWS IoT - 15 new 14 updated api methods
Changes IoT now supports resource tagging and tag based access control for Billing Groups, Thing Groups, Thing Types, Jobs, and Security Profiles. IoT Billing Groups help you group devices to categorize and track your costs. AWS IoT Device Management also introduces three new features: 1. Dynamic thing groups. 2. Jobs dynamic rollouts. 3. Device connectivity indexing. Dynamic thing groups lets you to create a group of devices using a Fleet Indexing query. The devices in your group will be automatically added or removed when they match your specified query criteria. Jobs dynamic rollout allows you to configure an exponentially increasing rate of deployment for device updates and define failure criteria to cancel your job. Device connectivity indexing allows you to index your devices' lifecycle events to discover whether devices are connected or disconnected to AWS IoT.
Lists the billing groups you have created.
See also: AWS API Documentation
Request Syntax
client.list_billing_groups(
nextToken='string',
maxResults=123,
namePrefixFilter='string'
)
string
The token to retrieve the next set of results.
integer
The maximum number of results to return per request.
string
Limit the results to billing groups whose names have the given prefix.
dict
Response Syntax
{
'billingGroups': [
{
'groupName': 'string',
'groupArn': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
billingGroups (list) --
The list of billing groups.
(dict) --
The name and ARN of a group.
groupName (string) --
The group name.
groupArn (string) --
The group ARN.
nextToken (string) --
The token used to get the next set of results, or null if there are no additional results.
Deletes a dynamic thing group.
See also: AWS API Documentation
Request Syntax
client.delete_dynamic_thing_group(
thingGroupName='string',
expectedVersion=123
)
string
[REQUIRED]
The name of the dynamic thing group to delete.
integer
The expected version of the dynamic thing group to delete.
dict
Response Syntax
{}
Response Structure
(dict) --
Returns information about a billing group.
See also: AWS API Documentation
Request Syntax
client.describe_billing_group(
billingGroupName='string'
)
string
[REQUIRED]
The name of the billing group.
dict
Response Syntax
{
'billingGroupName': 'string',
'billingGroupId': 'string',
'billingGroupArn': 'string',
'version': 123,
'billingGroupProperties': {
'billingGroupDescription': 'string'
},
'billingGroupMetadata': {
'creationDate': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
billingGroupName (string) --
The name of the billing group.
billingGroupId (string) --
The ID of the billing group.
billingGroupArn (string) --
The ARN of the billing group.
version (integer) --
The version of the billing group.
billingGroupProperties (dict) --
The properties of the billing group.
billingGroupDescription (string) --
The description of the billing group.
billingGroupMetadata (dict) --
Additional information about the billing group.
creationDate (datetime) --
The date the billing group was created.
Adds to or modifies the tags of the given resource. Tags are metadata which can be used to manage a resource.
See also: AWS API Documentation
Request Syntax
client.tag_resource(
resourceArn='string',
tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The ARN of the resource.
list
[REQUIRED]
The new or modified tags for the resource.
(dict) --
A set of key/value pairs that are used to manage the resource.
Key (string) --
The tag's key.
Value (string) --
The tag's value.
dict
Response Syntax
{}
Response Structure
(dict) --
Removes the given tags (metadata) from the resource.
See also: AWS API Documentation
Request Syntax
client.untag_resource(
resourceArn='string',
tagKeys=[
'string',
]
)
string
[REQUIRED]
The ARN of the resource.
list
[REQUIRED]
A list of the keys of the tags to be removed from the resource.
(string) --
dict
Response Syntax
{}
Response Structure
(dict) --
Creates a billing group.
See also: AWS API Documentation
Request Syntax
client.create_billing_group(
billingGroupName='string',
billingGroupProperties={
'billingGroupDescription': 'string'
},
tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The name you wish to give to the billing group.
dict
The properties of the billing group.
billingGroupDescription (string) --
The description of the billing group.
list
Metadata which can be used to manage the billing group.
(dict) --
A set of key/value pairs that are used to manage the resource.
Key (string) --
The tag's key.
Value (string) --
The tag's value.
dict
Response Syntax
{
'billingGroupName': 'string',
'billingGroupArn': 'string',
'billingGroupId': 'string'
}
Response Structure
(dict) --
billingGroupName (string) --
The name you gave to the billing group.
billingGroupArn (string) --
The ARN of the billing group.
billingGroupId (string) --
The ID of the billing group.
Updates information about the billing group.
See also: AWS API Documentation
Request Syntax
client.update_billing_group(
billingGroupName='string',
billingGroupProperties={
'billingGroupDescription': 'string'
},
expectedVersion=123
)
string
[REQUIRED]
The name of the billing group.
dict
[REQUIRED]
The properties of the billing group.
billingGroupDescription (string) --
The description of the billing group.
integer
The expected version of the billing group. If the version of the billing group does not match the expected version specified in the request, the UpdateBillingGroup request is rejected with a VersionConflictException .
dict
Response Syntax
{
'version': 123
}
Response Structure
(dict) --
version (integer) --
The latest version of the billing group.
Lists the things you have added to the given billing group.
See also: AWS API Documentation
Request Syntax
client.list_things_in_billing_group(
billingGroupName='string',
nextToken='string',
maxResults=123
)
string
[REQUIRED]
The name of the billing group.
string
The token to retrieve the next set of results.
integer
The maximum number of results to return per request.
dict
Response Syntax
{
'things': [
'string',
],
'nextToken': 'string'
}
Response Structure
(dict) --
things (list) --
A list of things in the billing group.
(string) --
nextToken (string) --
The token used to get the next set of results, or null if there are no additional results.
Deletes the billing group.
See also: AWS API Documentation
Request Syntax
client.delete_billing_group(
billingGroupName='string',
expectedVersion=123
)
string
[REQUIRED]
The name of the billing group.
integer
The expected version of the billing group. If the version of the billing group does not match the expected version specified in the request, the DeleteBillingGroup request is rejected with a VersionConflictException .
dict
Response Syntax
{}
Response Structure
(dict) --
Adds a thing to a billing group.
See also: AWS API Documentation
Request Syntax
client.add_thing_to_billing_group(
billingGroupName='string',
billingGroupArn='string',
thingName='string',
thingArn='string'
)
string
The name of the billing group.
string
The ARN of the billing group.
string
The name of the thing to be added to the billing group.
string
The ARN of the thing to be added to the billing group.
dict
Response Syntax
{}
Response Structure
(dict) --
Updates a dynamic thing group.
See also: AWS API Documentation
Request Syntax
client.update_dynamic_thing_group(
thingGroupName='string',
thingGroupProperties={
'thingGroupDescription': 'string',
'attributePayload': {
'attributes': {
'string': 'string'
},
'merge': True|False
}
},
expectedVersion=123,
indexName='string',
queryString='string',
queryVersion='string'
)
string
[REQUIRED]
The name of the dynamic thing group to update.
dict
[REQUIRED]
The dynamic thing group properties to update.
thingGroupDescription (string) --
The thing group description.
attributePayload (dict) --
The thing group attributes in JSON format.
attributes (dict) --
A JSON string containing up to three key-value pair in JSON format. For example:
{\"attributes\":{\"string1\":\"string2\"}}
(string) --
(string) --
merge (boolean) --
Specifies whether the list of attributes provided in the AttributePayload is merged with the attributes stored in the registry, instead of overwriting them.
To remove an attribute, call UpdateThing with an empty attribute value.
Note
The merge attribute is only valid when calling UpdateThing .
integer
The expected version of the dynamic thing group to update.
string
The dynamic thing group index to update.
Note
Currently one index is supported: 'AWS_Things'.
string
The dynamic thing group search query string to update.
string
The dynamic thing group query version to update.
Note
Currently one query version is supported: "2017-09-30". If not specified, the query version defaults to this value.
dict
Response Syntax
{
'version': 123
}
Response Structure
(dict) --
version (integer) --
The dynamic thing group version.
Creates a dynamic thing group.
See also: AWS API Documentation
Request Syntax
client.create_dynamic_thing_group(
thingGroupName='string',
thingGroupProperties={
'thingGroupDescription': 'string',
'attributePayload': {
'attributes': {
'string': 'string'
},
'merge': True|False
}
},
indexName='string',
queryString='string',
queryVersion='string',
tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The dynamic thing group name to create.
dict
The dynamic thing group properties.
thingGroupDescription (string) --
The thing group description.
attributePayload (dict) --
The thing group attributes in JSON format.
attributes (dict) --
A JSON string containing up to three key-value pair in JSON format. For example:
{\"attributes\":{\"string1\":\"string2\"}}
(string) --
(string) --
merge (boolean) --
Specifies whether the list of attributes provided in the AttributePayload is merged with the attributes stored in the registry, instead of overwriting them.
To remove an attribute, call UpdateThing with an empty attribute value.
Note
The merge attribute is only valid when calling UpdateThing .
string
The dynamic thing group index name.
Note
Currently one index is supported: "AWS_Things".
string
[REQUIRED]
The dynamic thing group search query string.
See Query Syntax for information about query string syntax.
string
The dynamic thing group query version.
Note
Currently one query version is supported: "2017-09-30". If not specified, the query version defaults to this value.
list
Metadata which can be used to manage the dynamic thing group.
(dict) --
A set of key/value pairs that are used to manage the resource.
Key (string) --
The tag's key.
Value (string) --
The tag's value.
dict
Response Syntax
{
'thingGroupName': 'string',
'thingGroupArn': 'string',
'thingGroupId': 'string',
'indexName': 'string',
'queryString': 'string',
'queryVersion': 'string'
}
Response Structure
(dict) --
thingGroupName (string) --
The dynamic thing group name.
thingGroupArn (string) --
The dynamic thing group ARN.
thingGroupId (string) --
The dynamic thing group ID.
indexName (string) --
The dynamic thing group index name.
queryString (string) --
The dynamic thing group search query string.
queryVersion (string) --
The dynamic thing group query version.
Updates supported fields of the specified job.
See also: AWS API Documentation
Request Syntax
client.update_job(
jobId='string',
description='string',
presignedUrlConfig={
'roleArn': 'string',
'expiresInSec': 123
},
jobExecutionsRolloutConfig={
'maximumPerMinute': 123,
'exponentialRate': {
'baseRatePerMinute': 123,
'incrementFactor': 123.0,
'rateIncreaseCriteria': {
'numberOfNotifiedThings': 123,
'numberOfSucceededThings': 123
}
}
},
abortConfig={
'criteriaList': [
{
'failureType': 'FAILED'|'REJECTED'|'TIMED_OUT'|'ALL',
'action': 'CANCEL',
'thresholdPercentage': 123.0,
'minNumberOfExecutedThings': 123
},
]
},
timeoutConfig={
'inProgressTimeoutInMinutes': 123
}
)
string
[REQUIRED]
The ID of the job to be updated.
string
A short text description of the job.
dict
Configuration information for pre-signed S3 URLs.
roleArn (string) --
The ARN of an IAM role that grants grants permission to download files from the S3 bucket where the job data/updates are stored. The role must also grant permission for IoT to download the files.
expiresInSec (integer) --
How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is 3600 seconds. Pre-signed URLs are generated when Jobs receives an MQTT request for the job document.
dict
Allows you to create a staged rollout of the job.
maximumPerMinute (integer) --
The maximum number of things that will be notified of a pending job, per minute. This parameter allows you to create a staged rollout.
exponentialRate (dict) --
The rate of increase for a job rollout. This parameter allows you to define an exponential rate for a job rollout.
baseRatePerMinute (integer) -- [REQUIRED]
The minimum number of things that will be notified of a pending job, per minute at the start of job rollout. This parameter allows you to define the initial rate of rollout.
incrementFactor (float) -- [REQUIRED]
The exponential factor to increase the rate of rollout for a job.
rateIncreaseCriteria (dict) -- [REQUIRED]
The criteria to initiate the increase in rate of rollout for a job.
AWS IoT supports up to one digit after the decimal (for example, 1.5, but not 1.55).
numberOfNotifiedThings (integer) --
The threshold for number of notified things that will initiate the increase in rate of rollout.
numberOfSucceededThings (integer) --
The threshold for number of succeeded things that will initiate the increase in rate of rollout.
dict
Allows you to create criteria to abort a job.
criteriaList (list) -- [REQUIRED]
The list of abort criteria to define rules to abort the job.
(dict) --
Details of abort criteria to define rules to abort the job.
failureType (string) -- [REQUIRED]
The type of job execution failure to define a rule to initiate a job abort.
action (string) -- [REQUIRED]
The type of abort action to initiate a job abort.
thresholdPercentage (float) -- [REQUIRED]
The threshold as a percentage of the total number of executed things that will initiate a job abort.
AWS IoT supports up to two digits after the decimal (for example, 10.9 and 10.99, but not 10.999).
minNumberOfExecutedThings (integer) -- [REQUIRED]
Minimum number of executed things before evaluating an abort rule.
dict
Specifies the amount of time each device has to finish its execution of the job. The timer is started when the job execution status is set to IN_PROGRESS . If the job execution status is not set to another terminal state before the time expires, it will be automatically set to TIMED_OUT .
inProgressTimeoutInMinutes (integer) --
Specifies the amount of time, in minutes, this device has to finish execution of this job. The timeout interval can be anywhere between 1 minute and 7 days (1 to 10080 minutes). The in progress timer can't be updated and will apply to all job executions for the job. Whenever a job execution remains in the IN_PROGRESS status for longer than this interval, the job execution will fail and switch to the terminal TIMED_OUT status.
None
Removes the given thing from the billing group.
See also: AWS API Documentation
Request Syntax
client.remove_thing_from_billing_group(
billingGroupName='string',
billingGroupArn='string',
thingName='string',
thingArn='string'
)
string
The name of the billing group.
string
The ARN of the billing group.
string
The name of the thing to be removed from the billing group.
string
The ARN of the thing to be removed from the billing group.
dict
Response Syntax
{}
Response Structure
(dict) --
Lists the tags (metadata) you have assigned to the resource.
See also: AWS API Documentation
Request Syntax
client.list_tags_for_resource(
resourceArn='string',
nextToken='string'
)
string
[REQUIRED]
The ARN of the resource.
string
The token to retrieve the next set of results.
dict
Response Syntax
{
'tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
tags (list) --
The list of tags assigned to the resource.
(dict) --
A set of key/value pairs that are used to manage the resource.
Key (string) --
The tag's key.
Value (string) --
The tag's value.
nextToken (string) --
The token used to get the next set of results, or null if there are no additional results.
{'overrideDynamicGroups': 'boolean'}
Adds a thing to a thing group.
See also: AWS API Documentation
Request Syntax
client.add_thing_to_thing_group(
thingGroupName='string',
thingGroupArn='string',
thingName='string',
thingArn='string',
overrideDynamicGroups=True|False
)
string
The name of the group to which you are adding a thing.
string
The ARN of the group to which you are adding a thing.
string
The name of the thing to add to a group.
string
The ARN of the thing to add to a group.
boolean
Override dynamic thing groups with static thing groups when 10-group limit is reached. If a thing belongs to 10 thing groups, and one or more of those groups are dynamic thing groups, adding a thing to a static group removes the thing from the last dynamic group.
dict
Response Syntax
{}
Response Structure
(dict) --
{'reasonCode': 'string'}
Cancels a job.
See also: AWS API Documentation
Request Syntax
client.cancel_job(
jobId='string',
reasonCode='string',
comment='string',
force=True|False
)
string
[REQUIRED]
The unique identifier you assigned to this job when it was created.
string
(Optional)A reason code string that explains why the job was canceled.
string
An optional comment string describing why the job was canceled.
boolean
(Optional) If true job executions with status "IN_PROGRESS" and "QUEUED" are canceled, otherwise only job executions with status "QUEUED" are canceled. The default is false .
Canceling a job which is "IN_PROGRESS", will cause a device which is executing the job to be unable to update the job execution status. Use caution and ensure that each device executing a job which is canceled is able to recover to a valid state.
dict
Response Syntax
{
'jobArn': 'string',
'jobId': 'string',
'description': 'string'
}
Response Structure
(dict) --
jobArn (string) --
The job ARN.
jobId (string) --
The unique identifier you assigned to this job when it was created.
description (string) --
A short text description of the job.
{'abortConfig': {'criteriaList': [{'action': 'CANCEL',
'failureType': 'FAILED | REJECTED | '
'TIMED_OUT | ALL',
'minNumberOfExecutedThings': 'integer',
'thresholdPercentage': 'double'}]},
'jobExecutionsRolloutConfig': {'exponentialRate': {'baseRatePerMinute': 'integer',
'incrementFactor': 'double',
'rateIncreaseCriteria': {'numberOfNotifiedThings': 'integer',
'numberOfSucceededThings': 'integer'}}},
'tags': [{'Key': 'string', 'Value': 'string'}]}
Creates a job.
See also: AWS API Documentation
Request Syntax
client.create_job(
jobId='string',
targets=[
'string',
],
documentSource='string',
document='string',
description='string',
presignedUrlConfig={
'roleArn': 'string',
'expiresInSec': 123
},
targetSelection='CONTINUOUS'|'SNAPSHOT',
jobExecutionsRolloutConfig={
'maximumPerMinute': 123,
'exponentialRate': {
'baseRatePerMinute': 123,
'incrementFactor': 123.0,
'rateIncreaseCriteria': {
'numberOfNotifiedThings': 123,
'numberOfSucceededThings': 123
}
}
},
abortConfig={
'criteriaList': [
{
'failureType': 'FAILED'|'REJECTED'|'TIMED_OUT'|'ALL',
'action': 'CANCEL',
'thresholdPercentage': 123.0,
'minNumberOfExecutedThings': 123
},
]
},
timeoutConfig={
'inProgressTimeoutInMinutes': 123
},
tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
A job identifier which must be unique for your AWS account. We recommend using a UUID. Alpha-numeric characters, "-" and "_" are valid for use here.
list
[REQUIRED]
A list of things and thing groups to which the job should be sent.
(string) --
string
An S3 link to the job document.
string
The job document.
Note
If the job document resides in an S3 bucket, you must use a placeholder link when specifying the document.
The placeholder link is of the following form:
${aws:iot:s3-presigned-url:https://s3.amazonaws.com/*bucket* /*key* }
where bucket is your bucket name and key is the object in the bucket to which you are linking.
string
A short text description of the job.
dict
Configuration information for pre-signed S3 URLs.
roleArn (string) --
The ARN of an IAM role that grants grants permission to download files from the S3 bucket where the job data/updates are stored. The role must also grant permission for IoT to download the files.
expiresInSec (integer) --
How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is 3600 seconds. Pre-signed URLs are generated when Jobs receives an MQTT request for the job document.
string
Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be run on a thing when a change is detected in a target. For example, a job will run on a thing when the thing is added to a target group, even after the job was completed by all things originally in the group.
dict
Allows you to create a staged rollout of the job.
maximumPerMinute (integer) --
The maximum number of things that will be notified of a pending job, per minute. This parameter allows you to create a staged rollout.
exponentialRate (dict) --
The rate of increase for a job rollout. This parameter allows you to define an exponential rate for a job rollout.
baseRatePerMinute (integer) -- [REQUIRED]
The minimum number of things that will be notified of a pending job, per minute at the start of job rollout. This parameter allows you to define the initial rate of rollout.
incrementFactor (float) -- [REQUIRED]
The exponential factor to increase the rate of rollout for a job.
rateIncreaseCriteria (dict) -- [REQUIRED]
The criteria to initiate the increase in rate of rollout for a job.
AWS IoT supports up to one digit after the decimal (for example, 1.5, but not 1.55).
numberOfNotifiedThings (integer) --
The threshold for number of notified things that will initiate the increase in rate of rollout.
numberOfSucceededThings (integer) --
The threshold for number of succeeded things that will initiate the increase in rate of rollout.
dict
Allows you to create criteria to abort a job.
criteriaList (list) -- [REQUIRED]
The list of abort criteria to define rules to abort the job.
(dict) --
Details of abort criteria to define rules to abort the job.
failureType (string) -- [REQUIRED]
The type of job execution failure to define a rule to initiate a job abort.
action (string) -- [REQUIRED]
The type of abort action to initiate a job abort.
thresholdPercentage (float) -- [REQUIRED]
The threshold as a percentage of the total number of executed things that will initiate a job abort.
AWS IoT supports up to two digits after the decimal (for example, 10.9 and 10.99, but not 10.999).
minNumberOfExecutedThings (integer) -- [REQUIRED]
Minimum number of executed things before evaluating an abort rule.
dict
Specifies the amount of time each device has to finish its execution of the job. The timer is started when the job execution status is set to IN_PROGRESS . If the job execution status is not set to another terminal state before the time expires, it will be automatically set to TIMED_OUT .
inProgressTimeoutInMinutes (integer) --
Specifies the amount of time, in minutes, this device has to finish execution of this job. The timeout interval can be anywhere between 1 minute and 7 days (1 to 10080 minutes). The in progress timer can't be updated and will apply to all job executions for the job. Whenever a job execution remains in the IN_PROGRESS status for longer than this interval, the job execution will fail and switch to the terminal TIMED_OUT status.
list
Metadata which can be used to manage the job.
(dict) --
A set of key/value pairs that are used to manage the resource.
Key (string) --
The tag's key.
Value (string) --
The tag's value.
dict
Response Syntax
{
'jobArn': 'string',
'jobId': 'string',
'description': 'string'
}
Response Structure
(dict) --
jobArn (string) --
The job ARN.
jobId (string) --
The unique identifier you assigned to this job.
description (string) --
The job description.
{'tags': [{'Key': 'string', 'Value': 'string'}]}
Creates a Device Defender security profile.
See also: AWS API Documentation
Request Syntax
client.create_security_profile(
securityProfileName='string',
securityProfileDescription='string',
behaviors=[
{
'name': 'string',
'metric': 'string',
'criteria': {
'comparisonOperator': 'less-than'|'less-than-equals'|'greater-than'|'greater-than-equals'|'in-cidr-set'|'not-in-cidr-set'|'in-port-set'|'not-in-port-set',
'value': {
'count': 123,
'cidrs': [
'string',
],
'ports': [
123,
]
},
'durationSeconds': 123
}
},
],
alertTargets={
'string': {
'alertTargetArn': 'string',
'roleArn': 'string'
}
},
tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The name you are giving to the security profile.
string
A description of the security profile.
list
[REQUIRED]
Specifies the behaviors that, when violated by a device (thing), cause an alert.
(dict) --
A Device Defender security profile behavior.
name (string) -- [REQUIRED]
The name you have given to the behavior.
metric (string) --
What is measured by the behavior.
criteria (dict) --
The criteria that determine if a device is behaving normally in regard to the metric .
comparisonOperator (string) --
The operator that relates the thing measured (metric ) to the criteria (value ).
value (dict) --
The value to be compared with the metric .
count (integer) --
If the comparisonOperator calls for a numeric value, use this to specify that numeric value to be compared with the metric .
cidrs (list) --
If the comparisonOperator calls for a set of CIDRs, use this to specify that set to be compared with the metric .
(string) --
ports (list) --
If the comparisonOperator calls for a set of ports, use this to specify that set to be compared with the metric .
(integer) --
durationSeconds (integer) --
Use this to specify the period of time over which the behavior is evaluated, for those criteria which have a time dimension (for example, NUM_MESSAGES_SENT ).
dict
Specifies the destinations to which alerts are sent. (Alerts are always sent to the console.) Alerts are generated when a device (thing) violates a behavior.
(string) --
The type of alert target: one of "SNS".
(dict) --
A structure containing the alert target ARN and the role ARN.
alertTargetArn (string) -- [REQUIRED]
The ARN of the notification target to which alerts are sent.
roleArn (string) -- [REQUIRED]
The ARN of the role that grants permission to send alerts to the notification target.
list
Metadata which can be used to manage the security profile.
(dict) --
A set of key/value pairs that are used to manage the resource.
Key (string) --
The tag's key.
Value (string) --
The tag's value.
dict
Response Syntax
{
'securityProfileName': 'string',
'securityProfileArn': 'string'
}
Response Structure
(dict) --
securityProfileName (string) --
The name you gave to the security profile.
securityProfileArn (string) --
The ARN of the security profile.
{'billingGroupName': 'string'}
Creates a thing record in the registry.
Note
This is a control plane operation. See Authorization for information about authorizing control plane actions.
See also: AWS API Documentation
Request Syntax
client.create_thing(
thingName='string',
thingTypeName='string',
attributePayload={
'attributes': {
'string': 'string'
},
'merge': True|False
},
billingGroupName='string'
)
string
[REQUIRED]
The name of the thing to create.
string
The name of the thing type associated with the new thing.
dict
The attribute payload, which consists of up to three name/value pairs in a JSON document. For example:
{\"attributes\":{\"string1\":\"string2\"}}
attributes (dict) --
A JSON string containing up to three key-value pair in JSON format. For example:
{\"attributes\":{\"string1\":\"string2\"}}
(string) --
(string) --
merge (boolean) --
Specifies whether the list of attributes provided in the AttributePayload is merged with the attributes stored in the registry, instead of overwriting them.
To remove an attribute, call UpdateThing with an empty attribute value.
Note
The merge attribute is only valid when calling UpdateThing .
string
The name of the billing group the thing will be added to.
dict
Response Syntax
{
'thingName': 'string',
'thingArn': 'string',
'thingId': 'string'
}
Response Structure
(dict) --
The output of the CreateThing operation.
thingName (string) --
The name of the new thing.
thingArn (string) --
The ARN of the new thing.
thingId (string) --
The thing ID.
{'tags': [{'Key': 'string', 'Value': 'string'}]}
Create a thing group.
Note
This is a control plane operation. See Authorization for information about authorizing control plane actions.
See also: AWS API Documentation
Request Syntax
client.create_thing_group(
thingGroupName='string',
parentGroupName='string',
thingGroupProperties={
'thingGroupDescription': 'string',
'attributePayload': {
'attributes': {
'string': 'string'
},
'merge': True|False
}
},
tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The thing group name to create.
string
The name of the parent thing group.
dict
The thing group properties.
thingGroupDescription (string) --
The thing group description.
attributePayload (dict) --
The thing group attributes in JSON format.
attributes (dict) --
A JSON string containing up to three key-value pair in JSON format. For example:
{\"attributes\":{\"string1\":\"string2\"}}
(string) --
(string) --
merge (boolean) --
Specifies whether the list of attributes provided in the AttributePayload is merged with the attributes stored in the registry, instead of overwriting them.
To remove an attribute, call UpdateThing with an empty attribute value.
Note
The merge attribute is only valid when calling UpdateThing .
list
Metadata which can be used to manage the thing group.
(dict) --
A set of key/value pairs that are used to manage the resource.
Key (string) --
The tag's key.
Value (string) --
The tag's value.
dict
Response Syntax
{
'thingGroupName': 'string',
'thingGroupArn': 'string',
'thingGroupId': 'string'
}
Response Structure
(dict) --
thingGroupName (string) --
The thing group name.
thingGroupArn (string) --
The thing group ARN.
thingGroupId (string) --
The thing group ID.
{'tags': [{'Key': 'string', 'Value': 'string'}]}
Creates a new thing type.
See also: AWS API Documentation
Request Syntax
client.create_thing_type(
thingTypeName='string',
thingTypeProperties={
'thingTypeDescription': 'string',
'searchableAttributes': [
'string',
]
},
tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The name of the thing type.
dict
The ThingTypeProperties for the thing type to create. It contains information about the new thing type including a description, and a list of searchable thing attribute names.
thingTypeDescription (string) --
The description of the thing type.
searchableAttributes (list) --
A list of searchable thing attribute names.
(string) --
list
Metadata which can be used to manage the thing type.
(dict) --
A set of key/value pairs that are used to manage the resource.
Key (string) --
The tag's key.
Value (string) --
The tag's value.
dict
Response Syntax
{
'thingTypeName': 'string',
'thingTypeArn': 'string',
'thingTypeId': 'string'
}
Response Structure
(dict) --
The output of the CreateThingType operation.
thingTypeName (string) --
The name of the thing type.
thingTypeArn (string) --
The Amazon Resource Name (ARN) of the thing type.
thingTypeId (string) --
The thing type ID.
{'job': {'abortConfig': {'criteriaList': [{'action': 'CANCEL',
'failureType': 'FAILED | REJECTED | '
'TIMED_OUT | ALL',
'minNumberOfExecutedThings': 'integer',
'thresholdPercentage': 'double'}]},
'jobExecutionsRolloutConfig': {'exponentialRate': {'baseRatePerMinute': 'integer',
'incrementFactor': 'double',
'rateIncreaseCriteria': {'numberOfNotifiedThings': 'integer',
'numberOfSucceededThings': 'integer'}}},
'reasonCode': 'string'}}
Describes a job.
See also: AWS API Documentation
Request Syntax
client.describe_job(
jobId='string'
)
string
[REQUIRED]
The unique identifier you assigned to this job when it was created.
dict
Response Syntax
{
'documentSource': 'string',
'job': {
'jobArn': 'string',
'jobId': 'string',
'targetSelection': 'CONTINUOUS'|'SNAPSHOT',
'status': 'IN_PROGRESS'|'CANCELED'|'COMPLETED'|'DELETION_IN_PROGRESS',
'forceCanceled': True|False,
'reasonCode': 'string',
'comment': 'string',
'targets': [
'string',
],
'description': 'string',
'presignedUrlConfig': {
'roleArn': 'string',
'expiresInSec': 123
},
'jobExecutionsRolloutConfig': {
'maximumPerMinute': 123,
'exponentialRate': {
'baseRatePerMinute': 123,
'incrementFactor': 123.0,
'rateIncreaseCriteria': {
'numberOfNotifiedThings': 123,
'numberOfSucceededThings': 123
}
}
},
'abortConfig': {
'criteriaList': [
{
'failureType': 'FAILED'|'REJECTED'|'TIMED_OUT'|'ALL',
'action': 'CANCEL',
'thresholdPercentage': 123.0,
'minNumberOfExecutedThings': 123
},
]
},
'createdAt': datetime(2015, 1, 1),
'lastUpdatedAt': datetime(2015, 1, 1),
'completedAt': datetime(2015, 1, 1),
'jobProcessDetails': {
'processingTargets': [
'string',
],
'numberOfCanceledThings': 123,
'numberOfSucceededThings': 123,
'numberOfFailedThings': 123,
'numberOfRejectedThings': 123,
'numberOfQueuedThings': 123,
'numberOfInProgressThings': 123,
'numberOfRemovedThings': 123,
'numberOfTimedOutThings': 123
},
'timeoutConfig': {
'inProgressTimeoutInMinutes': 123
}
}
}
Response Structure
(dict) --
documentSource (string) --
An S3 link to the job document.
job (dict) --
Information about the job.
jobArn (string) --
An ARN identifying the job with format "arn:aws:iot:region:account:job/jobId".
jobId (string) --
The unique identifier you assigned to this job when it was created.
targetSelection (string) --
Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be run on a thing when a change is detected in a target. For example, a job will run on a device when the thing representing the device is added to a target group, even after the job was completed by all things originally in the group.
status (string) --
The status of the job, one of IN_PROGRESS , CANCELED , DELETION_IN_PROGRESS or COMPLETED .
forceCanceled (boolean) --
Will be true if the job was canceled with the optional force parameter set to true .
reasonCode (string) --
If the job was updated, provides the reason code for the update.
comment (string) --
If the job was updated, describes the reason for the update.
targets (list) --
A list of IoT things and thing groups to which the job should be sent.
(string) --
description (string) --
A short text description of the job.
presignedUrlConfig (dict) --
Configuration for pre-signed S3 URLs.
roleArn (string) --
The ARN of an IAM role that grants grants permission to download files from the S3 bucket where the job data/updates are stored. The role must also grant permission for IoT to download the files.
expiresInSec (integer) --
How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is 3600 seconds. Pre-signed URLs are generated when Jobs receives an MQTT request for the job document.
jobExecutionsRolloutConfig (dict) --
Allows you to create a staged rollout of a job.
maximumPerMinute (integer) --
The maximum number of things that will be notified of a pending job, per minute. This parameter allows you to create a staged rollout.
exponentialRate (dict) --
The rate of increase for a job rollout. This parameter allows you to define an exponential rate for a job rollout.
baseRatePerMinute (integer) --
The minimum number of things that will be notified of a pending job, per minute at the start of job rollout. This parameter allows you to define the initial rate of rollout.
incrementFactor (float) --
The exponential factor to increase the rate of rollout for a job.
rateIncreaseCriteria (dict) --
The criteria to initiate the increase in rate of rollout for a job.
AWS IoT supports up to one digit after the decimal (for example, 1.5, but not 1.55).
numberOfNotifiedThings (integer) --
The threshold for number of notified things that will initiate the increase in rate of rollout.
numberOfSucceededThings (integer) --
The threshold for number of succeeded things that will initiate the increase in rate of rollout.
abortConfig (dict) --
Configuration for criteria to abort the job.
criteriaList (list) --
The list of abort criteria to define rules to abort the job.
(dict) --
Details of abort criteria to define rules to abort the job.
failureType (string) --
The type of job execution failure to define a rule to initiate a job abort.
action (string) --
The type of abort action to initiate a job abort.
thresholdPercentage (float) --
The threshold as a percentage of the total number of executed things that will initiate a job abort.
AWS IoT supports up to two digits after the decimal (for example, 10.9 and 10.99, but not 10.999).
minNumberOfExecutedThings (integer) --
Minimum number of executed things before evaluating an abort rule.
createdAt (datetime) --
The time, in milliseconds since the epoch, when the job was created.
lastUpdatedAt (datetime) --
The time, in milliseconds since the epoch, when the job was last updated.
completedAt (datetime) --
The time, in milliseconds since the epoch, when the job was completed.
jobProcessDetails (dict) --
Details about the job process.
processingTargets (list) --
The target devices to which the job execution is being rolled out. This value will be null after the job execution has finished rolling out to all the target devices.
(string) --
numberOfCanceledThings (integer) --
The number of things that cancelled the job.
numberOfSucceededThings (integer) --
The number of things which successfully completed the job.
numberOfFailedThings (integer) --
The number of things that failed executing the job.
numberOfRejectedThings (integer) --
The number of things that rejected the job.
numberOfQueuedThings (integer) --
The number of things that are awaiting execution of the job.
numberOfInProgressThings (integer) --
The number of things currently executing the job.
numberOfRemovedThings (integer) --
The number of things that are no longer scheduled to execute the job because they have been deleted or have been removed from the group that was a target of the job.
numberOfTimedOutThings (integer) --
The number of things whose job execution status is TIMED_OUT .
timeoutConfig (dict) --
Specifies the amount of time each device has to finish its execution of the job. A timer is started when the job execution status is set to IN_PROGRESS . If the job execution status is not set to another terminal state before the timer expires, it will be automatically set to TIMED_OUT .
inProgressTimeoutInMinutes (integer) --
Specifies the amount of time, in minutes, this device has to finish execution of this job. The timeout interval can be anywhere between 1 minute and 7 days (1 to 10080 minutes). The in progress timer can't be updated and will apply to all job executions for the job. Whenever a job execution remains in the IN_PROGRESS status for longer than this interval, the job execution will fail and switch to the terminal TIMED_OUT status.
{'billingGroupName': 'string'}
Gets information about the specified thing.
See also: AWS API Documentation
Request Syntax
client.describe_thing(
thingName='string'
)
string
[REQUIRED]
The name of the thing.
dict
Response Syntax
{
'defaultClientId': 'string',
'thingName': 'string',
'thingId': 'string',
'thingArn': 'string',
'thingTypeName': 'string',
'attributes': {
'string': 'string'
},
'version': 123,
'billingGroupName': 'string'
}
Response Structure
(dict) --
The output from the DescribeThing operation.
defaultClientId (string) --
The default client ID.
thingName (string) --
The name of the thing.
thingId (string) --
The ID of the thing to describe.
thingArn (string) --
The ARN of the thing to describe.
thingTypeName (string) --
The thing type name.
attributes (dict) --
The thing attributes.
(string) --
(string) --
version (integer) --
The current version of the thing record in the registry.
Note
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.
billingGroupName (string) --
The name of the billing group the thing belongs to.
{'indexName': 'string',
'queryString': 'string',
'queryVersion': 'string',
'status': 'ACTIVE | BUILDING | REBUILDING'}
Describe a thing group.
See also: AWS API Documentation
Request Syntax
client.describe_thing_group(
thingGroupName='string'
)
string
[REQUIRED]
The name of the thing group.
dict
Response Syntax
{
'thingGroupName': 'string',
'thingGroupId': 'string',
'thingGroupArn': 'string',
'version': 123,
'thingGroupProperties': {
'thingGroupDescription': 'string',
'attributePayload': {
'attributes': {
'string': 'string'
},
'merge': True|False
}
},
'thingGroupMetadata': {
'parentGroupName': 'string',
'rootToParentThingGroups': [
{
'groupName': 'string',
'groupArn': 'string'
},
],
'creationDate': datetime(2015, 1, 1)
},
'indexName': 'string',
'queryString': 'string',
'queryVersion': 'string',
'status': 'ACTIVE'|'BUILDING'|'REBUILDING'
}
Response Structure
(dict) --
thingGroupName (string) --
The name of the thing group.
thingGroupId (string) --
The thing group ID.
thingGroupArn (string) --
The thing group ARN.
version (integer) --
The version of the thing group.
thingGroupProperties (dict) --
The thing group properties.
thingGroupDescription (string) --
The thing group description.
attributePayload (dict) --
The thing group attributes in JSON format.
attributes (dict) --
A JSON string containing up to three key-value pair in JSON format. For example:
{\"attributes\":{\"string1\":\"string2\"}}
(string) --
(string) --
merge (boolean) --
Specifies whether the list of attributes provided in the AttributePayload is merged with the attributes stored in the registry, instead of overwriting them.
To remove an attribute, call UpdateThing with an empty attribute value.
Note
The merge attribute is only valid when calling UpdateThing .
thingGroupMetadata (dict) --
Thing group metadata.
parentGroupName (string) --
The parent thing group name.
rootToParentThingGroups (list) --
The root parent thing group.
(dict) --
The name and ARN of a group.
groupName (string) --
The group name.
groupArn (string) --
The group ARN.
creationDate (datetime) --
The UNIX timestamp of when the thing group was created.
indexName (string) --
The dynamic thing group index name.
queryString (string) --
The dynamic thing group search query string.
queryVersion (string) --
The dynamic thing group query version.
status (string) --
The dynamic thing group status.
{'thingIndexingConfiguration': {'thingConnectivityIndexingMode': 'OFF | '
'STATUS'}}
Gets the search configuration.
See also: AWS API Documentation
Request Syntax
client.get_indexing_configuration()
dict
Response Syntax
{
'thingIndexingConfiguration': {
'thingIndexingMode': 'OFF'|'REGISTRY'|'REGISTRY_AND_SHADOW',
'thingConnectivityIndexingMode': 'OFF'|'STATUS'
},
'thingGroupIndexingConfiguration': {
'thingGroupIndexingMode': 'OFF'|'ON'
}
}
Response Structure
(dict) --
thingIndexingConfiguration (dict) --
Thing indexing configuration.
thingIndexingMode (string) --
Thing indexing mode. Valid values are:
REGISTRY – Your thing index will contain only registry data.
REGISTRY_AND_SHADOW - Your thing index will contain registry and shadow data.
OFF - Thing indexing is disabled.
thingConnectivityIndexingMode (string) --
Thing connectivity indexing mode. Valid values are:
STATUS – Your thing index will contain connectivity status. In order to enable thing connectivity indexing, thingIndexMode must not be set to OFF.
OFF - Thing connectivity status indexing is disabled.
thingGroupIndexingConfiguration (dict) --
The index configuration.
thingGroupIndexingMode (string) --
Thing group indexing mode.
{'things': {'connectivity': {'connected': 'boolean', 'timestamp': 'long'}}}
The query search index.
See also: AWS API Documentation
Request Syntax
client.search_index(
indexName='string',
queryString='string',
nextToken='string',
maxResults=123,
queryVersion='string'
)
string
The search index name.
string
[REQUIRED]
The search query string.
string
The token used to get the next set of results, or null if there are no additional results.
integer
The maximum number of results to return at one time.
string
The query version.
dict
Response Syntax
{
'nextToken': 'string',
'things': [
{
'thingName': 'string',
'thingId': 'string',
'thingTypeName': 'string',
'thingGroupNames': [
'string',
],
'attributes': {
'string': 'string'
},
'shadow': 'string',
'connectivity': {
'connected': True|False,
'timestamp': 123
}
},
],
'thingGroups': [
{
'thingGroupName': 'string',
'thingGroupId': 'string',
'thingGroupDescription': 'string',
'attributes': {
'string': 'string'
},
'parentGroupNames': [
'string',
]
},
]
}
Response Structure
(dict) --
nextToken (string) --
The token used to get the next set of results, or null if there are no additional results.
things (list) --
The things that match the search query.
(dict) --
The thing search index document.
thingName (string) --
The thing name.
thingId (string) --
The thing ID.
thingTypeName (string) --
The thing type name.
thingGroupNames (list) --
Thing group names.
(string) --
attributes (dict) --
The attributes.
(string) --
(string) --
shadow (string) --
The shadow.
connectivity (dict) --
Indicates whether or not the thing is connected to the AWS IoT service.
connected (boolean) --
True if the thing is connected to the AWS IoT service, false if it is not connected.
timestamp (integer) --
The epoch time (in milliseconds) when the thing last connected or disconnected. Note that if the thing has been disconnected for more than a few weeks, the time value can be missing.
thingGroups (list) --
The thing groups that match the search query.
(dict) --
The thing group search index document.
thingGroupName (string) --
The thing group name.
thingGroupId (string) --
The thing group ID.
thingGroupDescription (string) --
The thing group description.
attributes (dict) --
The thing group attributes.
(string) --
(string) --
parentGroupNames (list) --
Parent group names.
(string) --
{'thingIndexingConfiguration': {'thingConnectivityIndexingMode': 'OFF | '
'STATUS'}}
Updates the search configuration.
See also: AWS API Documentation
Request Syntax
client.update_indexing_configuration(
thingIndexingConfiguration={
'thingIndexingMode': 'OFF'|'REGISTRY'|'REGISTRY_AND_SHADOW',
'thingConnectivityIndexingMode': 'OFF'|'STATUS'
},
thingGroupIndexingConfiguration={
'thingGroupIndexingMode': 'OFF'|'ON'
}
)
dict
Thing indexing configuration.
thingIndexingMode (string) -- [REQUIRED]
Thing indexing mode. Valid values are:
REGISTRY – Your thing index will contain only registry data.
REGISTRY_AND_SHADOW - Your thing index will contain registry and shadow data.
OFF - Thing indexing is disabled.
thingConnectivityIndexingMode (string) --
Thing connectivity indexing mode. Valid values are:
STATUS – Your thing index will contain connectivity status. In order to enable thing connectivity indexing, thingIndexMode must not be set to OFF.
OFF - Thing connectivity status indexing is disabled.
dict
Thing group indexing configuration.
thingGroupIndexingMode (string) -- [REQUIRED]
Thing group indexing mode.
dict
Response Syntax
{}
Response Structure
(dict) --
{'overrideDynamicGroups': 'boolean'}
Updates the groups to which the thing belongs.
See also: AWS API Documentation
Request Syntax
client.update_thing_groups_for_thing(
thingName='string',
thingGroupsToAdd=[
'string',
],
thingGroupsToRemove=[
'string',
],
overrideDynamicGroups=True|False
)
string
The thing whose group memberships will be updated.
list
The groups to which the thing will be added.
(string) --
list
The groups from which the thing will be removed.
(string) --
boolean
Override dynamic thing groups with static thing groups when 10-group limit is reached. If a thing belongs to 10 thing groups, and one or more of those groups are dynamic thing groups, adding a thing to a static group removes the thing from the last dynamic group.
dict
Response Syntax
{}
Response Structure
(dict) --