AWS IoT
Developer Guide

IOT Commands

This chapter contains the following sections:

AcceptCertificateTransfer

Accepts a pending certificate transfer. The default state of the certificate is INACTIVE.

To check for pending certificate transfers, call ListCertificates to enumerate your certificates.

Synopsis

aws iot accept-certificate-transfer \ --certificate-id <value> \ [--set-as-active | --no-set-as-active] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "certificateId": "string", "setAsActive": "boolean" }

cli-input-json fields

Name

Type

Description

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)

setAsActive

boolean

Specifies whether the certificate is active.

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

TransferAlreadyCompletedException

You can't revert the certificate transfer because the transfer is already complete.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

AddThingToBillingGroup

Adds a thing to a billing group.

Synopsis

aws iot add-thing-to-billing-group \ [--billing-group-name <value>] \ [--billing-group-arn <value>] \ [--thing-name <value>] \ [--thing-arn <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "billingGroupName": "string", "billingGroupArn": "string", "thingName": "string", "thingArn": "string" }

cli-input-json fields

Name

Type

Description

billingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the billing group.

billingGroupArn

string

The ARN of the billing group.

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing to be added to the billing group.

thingArn

string

The ARN of the thing to be added to the billing group.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

AddThingToThingGroup

Adds a thing to a thing group.

Synopsis

aws iot add-thing-to-thing-group \ [--thing-group-name <value>] \ [--thing-group-arn <value>] \ [--thing-name <value>] \ [--thing-arn <value>] \ [--override-dynamic-groups | --no-override-dynamic-groups] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingGroupName": "string", "thingGroupArn": "string", "thingName": "string", "thingArn": "string", "overrideDynamicGroups": "boolean" }

cli-input-json fields

Name

Type

Description

thingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the group to which you are adding a thing.

thingGroupArn

string

The ARN of the group to which you are adding a thing.

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing to add to a group.

thingArn

string

The ARN of the thing to add to a group.

overrideDynamicGroups

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.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

AssociateTargetsWithJob

Associates a group with a continuous job. The following criteria must be met:

  • The job must have been created with the targetSelection field set to "CONTINUOUS".

  • The job status must currently be "IN_PROGRESS".

  • The total number of targets associated with a job must not exceed 100.

Synopsis

aws iot associate-targets-with-job \ --targets <value> \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "targets": [ "string" ], "jobId": "string", "comment": "string" }

cli-input-json fields

Name

Type

Description

targets

list

member: TargetArn

A list of thing group ARNs that define the targets of the job.

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

comment

string

length- max:2028

pattern: [^\\p{C}]+

An optional comment string describing why the job was associated with the targets.

Output

{ "jobArn": "string", "jobId": "string", "description": "string" }

CLI output fields

Name

Type

Description

jobArn

string

An ARN identifying the job.

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

description

string

length- max:2028

pattern: [^\\p{C}]+

A short text description of the job.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

LimitExceededException

A limit has been exceeded.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

AttachPolicy

Attaches a policy to the specified target.

Synopsis

aws iot attach-policy \ --policy-name <value> \ --target <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "policyName": "string", "target": "string" }

cli-input-json fields

Name

Type

Description

policyName

string

length- max:128 min:1

pattern: [w+=,.@-]+

The name of the policy to attach.

target

string

The identity to which the policy is attached.

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

LimitExceededException

A limit has been exceeded.

AttachPrincipalPolicy

Attaches the specified policy to the specified principal (certificate or other credential).

Note: This API is deprecated. Please use AttachPolicy instead.

Synopsis

aws iot attach-principal-policy \ --policy-name <value> \ --principal <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "policyName": "string", "principal": "string" }

cli-input-json fields

Name

Type

Description

policyName

string

length- max:128 min:1

pattern: [w+=,.@-]+

The policy name.

principal

string

The principal, which can be a certificate ARN (as returned from the CreateCertificate operation) or an Amazon Cognito ID.

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

LimitExceededException

A limit has been exceeded.

AttachSecurityProfile

Associates a Device Defender security profile with a thing group or with this account. Each thing group or account can have up to five security profiles associated with it.

Synopsis

aws iot attach-security-profile \ --security-profile-name <value> \ --security-profile-target-arn <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "securityProfileName": "string", "securityProfileTargetArn": "string" }

cli-input-json fields

Name

Type

Description

securityProfileName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The security profile that is attached.

securityProfileTargetArn

string

The ARN of the target (thing group) to which the security profile is attached.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

LimitExceededException

A limit has been exceeded.

VersionConflictException

An exception thrown when the version of a thing passed to a command is different than the version specified with the --version parameter.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

AttachThingPrincipal

Attaches the specified principal to the specified thing. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities.

Synopsis

aws iot attach-thing-principal \ --thing-name <value> \ --principal <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingName": "string", "principal": "string" }

cli-input-json fields

Name

Type

Description

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing.

principal

string

The principal, such as a certificate or other credential.

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CancelAuditTask

Cancels an audit that is in progress. The audit can be either scheduled or on-demand. If the audit is not in progress, an "InvalidRequestException" occurs.

Synopsis

aws iot cancel-audit-task \ --task-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "taskId": "string" }

cli-input-json fields

Name

Type

Description

taskId

string

length- max:40 min:1

pattern: [a-zA-Z0-9-]+

The ID of the audit you want to cancel. You can only cancel an audit that is "IN_PROGRESS".

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

CancelCertificateTransfer

Cancels a pending transfer for the specified certificate.

Note Only the transfer source account can use this operation to cancel a transfer. (Transfer destinations can use RejectCertificateTransfer instead.) After transfer, AWS IoT returns the certificate to the source account in the INACTIVE state. After the destination account has accepted the transfer, the transfer cannot be cancelled.

After a certificate transfer is cancelled, the status of the certificate changes from PENDING_TRANSFER to INACTIVE.

Synopsis

aws iot cancel-certificate-transfer \ --certificate-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "certificateId": "string" }

cli-input-json fields

Name

Type

Description

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

TransferAlreadyCompletedException

You can't revert the certificate transfer because the transfer is already complete.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CancelJob

Cancels a job.

Synopsis

aws iot cancel-job \ --job-id <value> \ [--reason-code <value>] \ [--comment <value>] \ [--force | --no-force] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "jobId": "string", "reasonCode": "string", "comment": "string", "force": "boolean" }

cli-input-json fields

Name

Type

Description

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

reasonCode

string

length- max:128

pattern: [\\p{Upper}p Digit_]+

(Optional)A reason code string that explains why the job was canceled.

comment

string

length- max:2028

pattern: [^\\p{C}]+

An optional comment string describing why the job was canceled.

force

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.

Output

{ "jobArn": "string", "jobId": "string", "description": "string" }

CLI output fields

Name

Type

Description

jobArn

string

The job ARN.

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

description

string

length- max:2028

pattern: [^\\p{C}]+

A short text description of the job.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

CancelJobExecution

Cancels the execution of a job for a given thing.

Synopsis

aws iot cancel-job-execution \ --job-id <value> \ --thing-name <value> \ [--force | --no-force] \ [--expected-version <value>] \ [--status-details <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "jobId": "string", "thingName": "string", "force": "boolean", "expectedVersion": "long", "statusDetails": { "string": "string" } }

cli-input-json fields

Name

Type

Description

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The ID of the job to be canceled.

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing whose execution of the job will be canceled.

force

boolean

(Optional) If true the job execution will be canceled if it has status IN_PROGRESS or QUEUED, otherwise the job execution will be canceled only if it has status QUEUED. If you attempt to cancel a job execution that is IN_PROGRESS, and you do not set force to true, then an InvalidStateTransitionException will be thrown. The default is false.

Canceling a job execution which is "IN_PROGRESS", will cause the device to be unable to update the job execution status. Use caution and ensure that the device is able to recover to a valid state.

expectedVersion

long

(Optional) The expected current version of the job execution. Each time you update the job execution, its version is incremented. If the version of the job execution stored in Jobs does not match, the update is rejected with a VersionMismatch error, and an ErrorResponse that contains the current job execution status data is returned. (This makes it unnecessary to perform a separate DescribeJobExecution request in order to obtain the job execution status data.)

statusDetails

map

A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged. You can specify at most 10 name/value pairs.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

InvalidStateTransitionException

An update attempted to change the job execution to a state that is invalid because of the job execution's current state (for example, an attempt to change a request in state SUCCESS to state IN_PROGRESS). In this case, the body of the error message also contains the executionState field.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

VersionConflictException

An exception thrown when the version of a thing passed to a command is different than the version specified with the --version parameter.

ClearDefaultAuthorizer

Clears the default authorizer.

Synopsis

aws iot clear-default-authorizer \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ }

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CreateAuthorizer

Creates an authorizer.

Synopsis

aws iot create-authorizer \ --authorizer-name <value> \ --authorizer-function-arn <value> \ --token-key-name <value> \ --token-signing-public-keys <value> \ [--status <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "authorizerName": "string", "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string" }

cli-input-json fields

Name

Type

Description

authorizerName

string

length- max:128 min:1

pattern: [w=,@-]+

The authorizer name.

authorizerFunctionArn

string

The ARN of the authorizer's Lambda function.

tokenKeyName

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The name of the token key used to extract the token from the HTTP headers.

tokenSigningPublicKeys

map

The public keys used to verify the digital signature returned by your custom authentication service.

status

string

The status of the create authorizer request.

enum: ACTIVE | INACTIVE

Output

{ "authorizerName": "string", "authorizerArn": "string" }

CLI output fields

Name

Type

Description

authorizerName

string

length- max:128 min:1

pattern: [w=,@-]+

The authorizer's name.

authorizerArn

string

The authorizer ARN.

Errors

ResourceAlreadyExistsException

The resource already exists.

InvalidRequestException

The contents of the request were invalid.

LimitExceededException

A limit has been exceeded.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CreateBillingGroup

Creates a billing group.

Synopsis

aws iot create-billing-group \ --billing-group-name <value> \ [--billing-group-properties <value>] \ [--tags <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "billingGroupName": "string", "billingGroupProperties": { "billingGroupDescription": "string" }, "tags": [ { "Key": "string", "Value": "string" } ] }

cli-input-json fields

Name

Type

Description

billingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name you wish to give to the billing group.

billingGroupProperties

BillingGroupProperties

The properties of the billing group.

billingGroupDescription

string

length- max:2028

pattern: [\\p{Graph} ]*

The description of the billing group.

tags

list

member: Tag

java class: java.util.List

Metadata which can be used to manage the billing group.

Key

string

The tag's key.

Value

string

The tag's value.

Output

{ "billingGroupName": "string", "billingGroupArn": "string", "billingGroupId": "string" }

CLI output fields

Name

Type

Description

billingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name you gave to the billing group.

billingGroupArn

string

The ARN of the billing group.

billingGroupId

string

length- max:128 min:1

pattern: [a-zA-Z0-9-]+

The ID of the billing group.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceAlreadyExistsException

The resource already exists.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

CreateCertificateFromCsr

Creates an X.509 certificate using the specified certificate signing request.

Note: The CSR must include a public key that is either an RSA key with a length of at least 2048 bits or an ECC key from NIST P-256 or NIST P-384 curves.

Note: Reusing the same certificate signing request (CSR) results in a distinct certificate.

You can create multiple certificates in a batch by creating a directory, copying multiple .csr files into that directory, and then specifying that directory on the command line. The following commands show how to create a batch of certificates given a batch of CSRs.

Assuming a set of CSRs are located inside of the directory my-csr-directory:

On Linux and OS X, the command is:

$ ls my-csr-directory/ | xargs -I aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/

This command lists all of the CSRs in my-csr-directory and pipes each CSR file name to the aws iot create-certificate-from-csr AWS CLI command to create a certificate for the corresponding CSR.

The aws iot create-certificate-from-csr part of the command can also be run in parallel to speed up the certificate creation process:

$ ls my-csr-directory/ | xargs -P 10 -I aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/

On Windows PowerShell, the command to create certificates for all CSRs in my-csr-directory is:

> ls -Name my-csr-directory | % aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/$_

On a Windows command prompt, the command to create certificates for all CSRs in my-csr-directory is:

> forfiles /p my-csr-directory /c "cmd /c aws iot create-certificate-from-csr --certificate-signing-request file://@path"

Synopsis

aws iot create-certificate-from-csr \ --certificate-signing-request <value> \ [--set-as-active | --no-set-as-active] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "certificateSigningRequest": "string", "setAsActive": "boolean" }

cli-input-json fields

Name

Type

Description

certificateSigningRequest

string

length- min:1

The certificate signing request (CSR).

setAsActive

boolean

Specifies whether the certificate is active.

Output

{ "certificateArn": "string", "certificateId": "string", "certificatePem": "string" }

CLI output fields

Name

Type

Description

certificateArn

string

The Amazon Resource Name (ARN) of the certificate. You can use the ARN as a principal for policy operations.

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The ID of the certificate. Certificate management operations only take a certificateId.

certificatePem

string

length- max:65536 min:1

The certificate data, in PEM format.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CreateDynamicThingGroup

Creates a dynamic thing group.

Synopsis

aws iot create-dynamic-thing-group \ --thing-group-name <value> \ [--thing-group-properties <value>] \ [--index-name <value>] \ --query-string <value> \ [--query-version <value>] \ [--tags <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingGroupName": "string", "thingGroupProperties": { "thingGroupDescription": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" } }, "indexName": "string", "queryString": "string", "queryVersion": "string", "tags": [ { "Key": "string", "Value": "string" } ] }

cli-input-json fields

Name

Type

Description

thingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The dynamic thing group name to create.

thingGroupProperties

ThingGroupProperties

The dynamic thing group properties.

thingGroupDescription

string

length- max:2028

pattern: [\\p{Graph} ]*

The thing group description.

attributePayload

AttributePayload

The thing group attributes in JSON format.

attributes

map

A JSON string containing up to three key-value pair in JSON format. For example:

\"attributes\":{\"string1\":\"string2\"}

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.

indexName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The dynamic thing group index name.

Note

Currently one index is supported: "AWS_Things".

queryString

string

length- min:1

The dynamic thing group search query string.

See Query Syntax for information about query string syntax.

queryVersion

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.

tags

list

member: Tag

java class: java.util.List

Metadata which can be used to manage the dynamic thing group.

Key

string

The tag's key.

Value

string

The tag's value.

Output

{ "thingGroupName": "string", "thingGroupArn": "string", "thingGroupId": "string", "indexName": "string", "queryString": "string", "queryVersion": "string" }

CLI output fields

Name

Type

Description

thingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The dynamic thing group name.

thingGroupArn

string

The dynamic thing group ARN.

thingGroupId

string

length- max:128 min:1

pattern: [a-zA-Z0-9-]+

The dynamic thing group ID.

indexName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The dynamic thing group index name.

queryString

string

length- min:1

The dynamic thing group search query string.

queryVersion

string

The dynamic thing group query version.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceAlreadyExistsException

The resource already exists.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

InvalidQueryException

The query is invalid.

LimitExceededException

A limit has been exceeded.

CreateJob

Creates a job.

Synopsis

aws iot create-job \ --job-id <value> \ --targets <value> \ [--document-source <value>] \ [--document <value>] \ [--description <value>] \ [--presigned-url-config <value>] \ [--target-selection <value>] \ [--job-executions-rollout-config <value>] \ [--abort-config <value>] \ [--timeout-config <value>] \ [--tags <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "jobId": "string", "targets": [ "string" ], "documentSource": "string", "document": "string", "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "targetSelection": "string", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer", "exponentialRate": { "baseRatePerMinute": "integer", "incrementFactor": "double", "rateIncreaseCriteria": { "numberOfNotifiedThings": "integer", "numberOfSucceededThings": "integer" } } }, "abortConfig": { "criteriaList": [ { "failureType": "string", "action": "string", "thresholdPercentage": "double", "minNumberOfExecutedThings": "integer" } ] }, "timeoutConfig": { "inProgressTimeoutInMinutes": "long" }, "tags": [ { "Key": "string", "Value": "string" } ] }

cli-input-json fields

Name

Type

Description

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

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.

targets

list

member: TargetArn

A list of things and thing groups to which the job should be sent.

documentSource

string

length- max:1350 min:1

An S3 link to the job document.

document

string

length- max:32768

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.

description

string

length- max:2028

pattern: [^\\p{C}]+

A short text description of the job.

presignedUrlConfig

PresignedUrlConfig

Configuration information for pre-signed S3 URLs.

roleArn

string

length- max:2048 min:20

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

long

range- max:3600 min:60

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.

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 thing when the thing is added to a target group, even after the job was completed by all things originally in the group.

enum: CONTINUOUS | SNAPSHOT

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

Allows you to create a staged rollout of the job.

maximumPerMinute

integer

range- min:1

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

ExponentialRolloutRate

The rate of increase for a job rollout. This parameter allows you to define an exponential rate for a job rollout.

baseRatePerMinute

integer

range- max:1000 min:1

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.

rateIncreaseCriteria

RateIncreaseCriteria

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

range- min:1

The threshold for number of notified things that will initiate the increase in rate of rollout.

numberOfSucceededThings

integer

range- min:1

The threshold for number of succeeded things that will initiate the increase in rate of rollout.

abortConfig

AbortConfig

Allows you to create criteria to abort a job.

criteriaList

list

member: AbortCriteria

java class: java.util.List

The list 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.

enum: FAILED | REJECTED | TIMED_OUT | ALL

action

string

The type of abort action to initiate a job abort.

enum: CANCEL

minNumberOfExecutedThings

integer

range- min:1

Minimum number of executed things before evaluating an abort rule.

timeoutConfig

TimeoutConfig

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

long

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.

tags

list

member: Tag

java class: java.util.List

Metadata which can be used to manage the job.

Key

string

The tag's key.

Value

string

The tag's value.

Output

{ "jobArn": "string", "jobId": "string", "description": "string" }

CLI output fields

Name

Type

Description

jobArn

string

The job ARN.

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job.

description

string

length- max:2028

pattern: [^\\p{C}]+

The job description.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ResourceAlreadyExistsException

The resource already exists.

LimitExceededException

A limit has been exceeded.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

CreateKeysAndCertificate

Creates a 2048-bit RSA key pair and issues an X.509 certificate using the issued public key.

Note This is the only time AWS IoT issues the private key for this certificate, so it is important to keep it in a secure location.

Synopsis

aws iot create-keys-and-certificate \ [--set-as-active | --no-set-as-active] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "setAsActive": "boolean" }

cli-input-json fields

Name

Type

Description

setAsActive

boolean

Specifies whether the certificate is active.

Output

{ "certificateArn": "string", "certificateId": "string", "certificatePem": "string", "keyPair": { "PublicKey": "string", "PrivateKey": "string" } }

CLI output fields

Name

Type

Description

certificateArn

string

The ARN of the certificate.

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The ID of the certificate. AWS IoT issues a default subject name for the certificate (for example, AWS IoT Certificate).

certificatePem

string

length- max:65536 min:1

The certificate data, in PEM format.

keyPair

KeyPair

The generated key pair.

PublicKey

string

length- min:1

The public key.

PrivateKey

string

length- min:1

The private key.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CreateOTAUpdate

Creates an AWS IoT OTAUpdate on a target group of things or groups.

Synopsis

aws iot create-ota-update \ --ota-update-id <value> \ [--description <value>] \ --targets <value> \ [--target-selection <value>] \ [--aws-job-executions-rollout-config <value>] \ --files <value> \ --role-arn <value> \ [--additional-parameters <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "otaUpdateId": "string", "description": "string", "targets": [ "string" ], "targetSelection": "string", "awsJobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "files": [ { "fileName": "string", "fileVersion": "string", "fileLocation": { "stream": { "streamId": "string", "fileId": "integer" }, "s3Location": { "bucket": "string", "key": "string", "version": "string" } }, "codeSigning": { "awsSignerJobId": "string", "startSigningJobParameter": { "signingProfileParameter": { "certificateArn": "string", "platform": "string", "certificatePathOnDevice": "string" }, "signingProfileName": "string", "destination": { "s3Destination": { "bucket": "string", "prefix": "string" } } }, "customCodeSigning": { "signature": { "inlineDocument": "blob" }, "certificateChain": { "certificateName": "string", "inlineDocument": "string" }, "hashAlgorithm": "string", "signatureAlgorithm": "string" } }, "attributes": { "string": "string" } } ], "roleArn": "string", "additionalParameters": { "string": "string" } }

cli-input-json fields

Name

Type

Description

otaUpdateId

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The ID of the OTA update to be created.

description

string

length- max:2028

pattern: [^\\p{C}]+

The description of the OTA update.

targets

list

member: Target

The targeted devices to receive OTA updates.

targetSelection

string

Specifies whether the update will continue to run (CONTINUOUS), or will be complete after all the things specified as targets have completed the update (SNAPSHOT). If continuous, the update may also be run on a thing when a change is detected in a target. For example, an update will run on a thing when the thing is added to a target group, even after the update was completed by all things originally in the group. Valid values: CONTINUOUS | SNAPSHOT.

enum: CONTINUOUS | SNAPSHOT

awsJobExecutionsRolloutConfig

AwsJobExecutionsRolloutConfig

Configuration for the rollout of OTA updates.

maximumPerMinute

integer

range- max:1000 min:1

The maximum number of OTA update job executions started per minute.

files

list

member: OTAUpdateFile

The files to be streamed by the OTA update.

fileName

string

The name of the file.

fileVersion

string

The file version.

fileLocation

FileLocation

The location of the updated firmware.

stream

Stream

The stream that contains the OTA update.

streamId

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The stream ID.

fileId

integer

range- max:255 min:0

The ID of a file associated with a stream.

s3Location

S3Location

The location of the updated firmware in S3.

bucket

string

length- min:1

The S3 bucket.

key

string

length- min:1

The S3 key.

version

string

The S3 bucket version.

codeSigning

CodeSigning

The code signing method of the file.

awsSignerJobId

string

The ID of the AWSSignerJob which was created to sign the file.

startSigningJobParameter

StartSigningJobParameter

Describes the code-signing job.

signingProfileParameter

SigningProfileParameter

Describes the code-signing profile.

certificateArn

string

Certificate ARN.

platform

string

The hardware platform of your device.

certificatePathOnDevice

string

The location of the code-signing certificate on your device.

signingProfileName

string

The code-signing profile name.

destination

Destination

The location to write the code-signed file.

s3Destination

S3Destination

Describes the location in S3 of the updated firmware.

bucket

string

length- min:1

The S3 bucket that contains the updated firmware.

prefix

string

The S3 prefix.

customCodeSigning

CustomCodeSigning

A custom method for code signing a file.

signature

CodeSigningSignature

The signature for the file.

inlineDocument

blob

A base64 encoded binary representation of the code signing signature.

certificateChain

CodeSigningCertificateChain

The certificate chain.

certificateName

string

The name of the certificate.

inlineDocument

string

A base64 encoded binary representation of the code signing certificate chain.

hashAlgorithm

string

The hash algorithm used to code sign the file.

signatureAlgorithm

string

The signature algorithm used to code sign the file.

attributes

map

A list of name/attribute pairs.

roleArn

string

length- max:2048 min:20

The IAM role that allows access to the AWS IoT Jobs service.

additionalParameters

map

A list of additional OTA update parameters which are name-value pairs.

Output

{ "otaUpdateId": "string", "awsIotJobId": "string", "otaUpdateArn": "string", "awsIotJobArn": "string", "otaUpdateStatus": "string" }

CLI output fields

Name

Type

Description

otaUpdateId

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The OTA update ID.

awsIotJobId

string

The AWS IoT job ID associated with the OTA update.

otaUpdateArn

string

The OTA update ARN.

awsIotJobArn

string

The AWS IoT job ARN associated with the OTA update.

otaUpdateStatus

string

The OTA update status.

enum: CREATE_PENDING | CREATE_IN_PROGRESS | CREATE_COMPLETE | CREATE_FAILED

Errors

InvalidRequestException

The contents of the request were invalid.

LimitExceededException

A limit has been exceeded.

ResourceNotFoundException

The specified resource does not exist.

ResourceAlreadyExistsException

The resource already exists.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

InternalFailureException

An unexpected error has occurred.

ServiceUnavailableException

The service is temporarily unavailable.

CreatePolicy

Creates an AWS IoT policy.

The created policy is the default version for the policy. This operation creates a policy version with a version identifier of 1 and sets 1 as the policy's default version.

Synopsis

aws iot create-policy \ --policy-name <value> \ --policy-document <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "policyName": "string", "policyDocument": "string" }

cli-input-json fields

Name

Type

Description

policyName

string

length- max:128 min:1

pattern: [w+=,.@-]+

The policy name.

policyDocument

string

The JSON document that describes the policy. policyDocument must have a minimum length of 1, with a maximum length of 2048, excluding whitespace.

Output

{ "policyName": "string", "policyArn": "string", "policyDocument": "string", "policyVersionId": "string" }

CLI output fields

Name

Type

Description

policyName

string

length- max:128 min:1

pattern: [w+=,.@-]+

The policy name.

policyArn

string

The policy ARN.

policyDocument

string

The JSON document that describes the policy.

policyVersionId

string

pattern: [0-9]+

The policy version ID.

Errors

ResourceAlreadyExistsException

The resource already exists.

MalformedPolicyException

The policy documentation is not valid.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CreatePolicyVersion

Creates a new version of the specified AWS IoT policy. To update a policy, create a new policy version. A managed policy can have up to five versions. If the policy has five versions, you must use DeletePolicyVersion to delete an existing version before you create a new one.

Optionally, you can set the new version as the policy's default version. The default version is the operative version (that is, the version that is in effect for the certificates to which the policy is attached).

Synopsis

aws iot create-policy-version \ --policy-name <value> \ --policy-document <value> \ [--set-as-default | --no-set-as-default] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "policyName": "string", "policyDocument": "string", "setAsDefault": "boolean" }

cli-input-json fields

Name

Type

Description

policyName

string

length- max:128 min:1

pattern: [w+=,.@-]+

The policy name.

policyDocument

string

The JSON document that describes the policy. Minimum length of 1. Maximum length of 2048, excluding whitespace.

setAsDefault

boolean

Specifies whether the policy version is set as the default. When this parameter is true, the new policy version becomes the operative version (that is, the version that is in effect for the certificates to which the policy is attached).

Output

{ "policyArn": "string", "policyDocument": "string", "policyVersionId": "string", "isDefaultVersion": "boolean" }

CLI output fields

Name

Type

Description

policyArn

string

The policy ARN.

policyDocument

string

The JSON document that describes the policy.

policyVersionId

string

pattern: [0-9]+

The policy version ID.

isDefaultVersion

boolean

Specifies whether the policy version is the default.

Errors

ResourceNotFoundException

The specified resource does not exist.

MalformedPolicyException

The policy documentation is not valid.

VersionsLimitExceededException

The number of policy versions exceeds the limit.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CreateRoleAlias

Creates a role alias.

Synopsis

aws iot create-role-alias \ --role-alias <value> \ --role-arn <value> \ [--credential-duration-seconds <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "roleAlias": "string", "roleArn": "string", "credentialDurationSeconds": "integer" }

cli-input-json fields

Name

Type

Description

roleAlias

string

length- max:128 min:1

pattern: [w=,@-]+

The role alias that points to a role ARN. This allows you to change the role without having to update the device.

roleArn

string

length- max:2048 min:20

The role ARN.

credentialDurationSeconds

integer

range- max:3600 min:900

How long (in seconds) the credentials will be valid.

Output

{ "roleAlias": "string", "roleAliasArn": "string" }

CLI output fields

Name

Type

Description

roleAlias

string

length- max:128 min:1

pattern: [w=,@-]+

The role alias.

roleAliasArn

string

The role alias ARN.

Errors

ResourceAlreadyExistsException

The resource already exists.

InvalidRequestException

The contents of the request were invalid.

LimitExceededException

A limit has been exceeded.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CreateScheduledAudit

Creates a scheduled audit that is run at a specified time interval.

Synopsis

aws iot create-scheduled-audit \ --frequency <value> \ [--day-of-month <value>] \ [--day-of-week <value>] \ --target-check-names <value> \ [--tags <value>] \ --scheduled-audit-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "frequency": "string", "dayOfMonth": "string", "dayOfWeek": "string", "targetCheckNames": [ "string" ], "tags": [ { "Key": "string", "Value": "string" } ], "scheduledAuditName": "string" }

cli-input-json fields

Name

Type

Description

frequency

string

How often the scheduled audit takes place. Can be one of "DAILY", "WEEKLY", "BIWEEKLY" or "MONTHLY". The actual start time of each audit is determined by the system.

enum: DAILY | WEEKLY | BIWEEKLY | MONTHLY

dayOfMonth

string

pattern: ^([1-9]|[12][0-9]|3[01])$|^LAST$

The day of the month on which the scheduled audit takes place. Can be "1" through "31" or "LAST". This field is required if the "frequency" parameter is set to "MONTHLY". If days 29-31 are specified, and the month does not have that many days, the audit takes place on the "LAST" day of the month.

dayOfWeek

string

The day of the week on which the scheduled audit takes place. Can be one of "SUN", "MON", "TUE", "WED", "THU", "FRI" or "SAT". This field is required if the "frequency" parameter is set to "WEEKLY" or "BIWEEKLY".

enum: SUN | MON | TUE | WED | THU | FRI | SAT

targetCheckNames

list

member: AuditCheckName

Which checks are performed during the scheduled audit. Checks must be enabled for your account. (Use DescribeAccountAuditConfiguration to see the list of all checks including those that are enabled or UpdateAccountAuditConfiguration to select which checks are enabled.)

tags

list

member: Tag

java class: java.util.List

Metadata which can be used to manage the scheduled audit.

Key

string

The tag's key.

Value

string

The tag's value.

scheduledAuditName

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The name you want to give to the scheduled audit. (Max. 128 chars)

Output

{ "scheduledAuditArn": "string" }

CLI output fields

Name

Type

Description

scheduledAuditArn

string

The ARN of the scheduled audit.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

LimitExceededException

A limit has been exceeded.

CreateSecurityProfile

Creates a Device Defender security profile.

Synopsis

aws iot create-security-profile \ --security-profile-name <value> \ [--security-profile-description <value>] \ [--behaviors <value>] \ [--alert-targets <value>] \ [--additional-metrics-to-retain <value>] \ [--tags <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "securityProfileName": "string", "securityProfileDescription": "string", "behaviors": [ { "name": "string", "metric": "string", "criteria": { "comparisonOperator": "string", "value": { "count": "long", "cidrs": [ "string" ], "ports": [ "integer" ] }, "durationSeconds": "integer", "consecutiveDatapointsToAlarm": "integer", "consecutiveDatapointsToClear": "integer", "statisticalThreshold": { "statistic": "string" } } } ], "alertTargets": { "string": { "alertTargetArn": "string", "roleArn": "string" } }, "additionalMetricsToRetain": [ "string" ], "tags": [ { "Key": "string", "Value": "string" } ] }

cli-input-json fields

Name

Type

Description

securityProfileName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name you are giving to the security profile.

securityProfileDescription

string

length- max:1000

pattern: [\\p{Graph} ]*

A description of the security profile.

behaviors

list

member: Behavior

Specifies the behaviors that, when violated by a device (thing), cause an alert.

name

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name you have given to the behavior.

metric

string

What is measured by the behavior.

criteria

BehaviorCriteria

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 (containing a value or statisticalThreshold).

enum: 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

MetricValue

The value to be compared with the metric.

count

long

range- min:0

If the comparisonOperator calls for a numeric value, use this to specify that numeric value to be compared with the metric.

cidrs

list

member: Cidr

If the comparisonOperator calls for a set of CIDRs, use this to specify that set to be compared with the metric.

ports

list

member: Port

If the comparisonOperator calls for a set of ports, use this to specify that set to be compared with the metric.

durationSeconds

integer

Use this to specify the time duration over which the behavior is evaluated, for those criteria which have a time dimension (for example, NUM_MESSAGES_SENT). For a statisticalThreshhold metric comparison, measurements from all devices are accumulated over this time duration before being used to calculate percentiles, and later, measurements from an individual device are also accumulated over this time duration before being given a percentile rank.

consecutiveDatapointsToAlarm

integer

range- max:10 min:1

If a device is in violation of the behavior for the specified number of consecutive datapoints, an alarm occurs. If not specified, the default is 1.

consecutiveDatapointsToClear

integer

range- max:10 min:1

If an alarm has occurred and the offending device is no longer in violation of the behavior for the specified number of consecutive datapoints, the alarm is cleared. If not specified, the default is 1.

statisticalThreshold

StatisticalThreshold

A statistical ranking (percentile) which indicates a threshold value by which a behavior is determined to be in compliance or in violation of the behavior.

statistic

string

pattern: (p0|p0.1|p0.01|p1|p10|p50|p90|p99|p99.9|p99.99|p100)

The percentile which resolves to a threshold value by which compliance with a behavior is determined. Metrics are collected over the specified period (durationSeconds) from all reporting devices in your account and statistical ranks are calculated. Then, the measurements from a device are collected over the same period. If the accumulated measurements from the device fall above or below (comparisonOperator) the value associated with the percentile specified, then the device is considered to be in compliance with the behavior, otherwise a violation occurs.

alertTargets

map

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.

alertTargetArn

string

The ARN of the notification target to which alerts are sent.

roleArn

string

length- max:2048 min:20

The ARN of the role that grants permission to send alerts to the notification target.

additionalMetricsToRetain

list

member: BehaviorMetric

A list of metrics whose data is retained (stored). By default, data is retained for any metric used in the profile's behaviors but it is also retained for any metric specified here.

tags

list

member: Tag

java class: java.util.List

Metadata which can be used to manage the security profile.

Key

string

The tag's key.

Value

string

The tag's value.

Output

{ "securityProfileName": "string", "securityProfileArn": "string" }

CLI output fields

Name

Type

Description

securityProfileName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name you gave to the security profile.

securityProfileArn

string

The ARN of the security profile.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceAlreadyExistsException

The resource already exists.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

CreateStream

Creates a stream for delivering one or more large files in chunks over MQTT. A stream transports data bytes in chunks or blocks packaged as MQTT messages from a source like S3. You can have one or more files associated with a stream. The total size of a file associated with the stream cannot exceed more than 2 MB. The stream will be created with version 0. If a stream is created with the same streamID as a stream that existed and was deleted within last 90 days, we will resurrect that old stream by incrementing the version by 1.

Synopsis

aws iot create-stream \ --stream-id <value> \ [--description <value>] \ --files <value> \ --role-arn <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "streamId": "string", "description": "string", "files": [ { "fileId": "integer", "s3Location": { "bucket": "string", "key": "string", "version": "string" } } ], "roleArn": "string" }

cli-input-json fields

Name

Type

Description

streamId

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The stream ID.

description

string

length- max:2028

pattern: [^\\p{C}]+

A description of the stream.

files

list

member: StreamFile

The files to stream.

fileId

integer

range- max:255 min:0

The file ID.

s3Location

S3Location

The location of the file in S3.

bucket

string

length- min:1

The S3 bucket.

key

string

length- min:1

The S3 key.

version

string

The S3 bucket version.

roleArn

string

length- max:2048 min:20

An IAM role that allows the IoT service principal assumes to access your S3 files.

Output

{ "streamId": "string", "streamArn": "string", "description": "string", "streamVersion": "integer" }

CLI output fields

Name

Type

Description

streamId

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The stream ID.

streamArn

string

The stream ARN.

description

string

length- max:2028

pattern: [^\\p{C}]+

A description of the stream.

streamVersion

integer

range- max:65535 min:0

The version of the stream.

Errors

InvalidRequestException

The contents of the request were invalid.

LimitExceededException

A limit has been exceeded.

ResourceNotFoundException

The specified resource does not exist.

ResourceAlreadyExistsException

The resource already exists.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

CreateThing

Creates a thing record in the registry.

Note

This is a control plane operation. See Authorization for information about authorizing control plane actions.

Synopsis

aws iot create-thing \ --thing-name <value> \ [--thing-type-name <value>] \ [--attribute-payload <value>] \ [--billing-group-name <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingName": "string", "thingTypeName": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" }, "billingGroupName": "string" }

cli-input-json fields

Name

Type

Description

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing to create.

thingTypeName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing type associated with the new thing.

attributePayload

AttributePayload

The attribute payload, which consists of up to three name/value pairs in a JSON document. For example:

\"attributes\":{\"string1\":\"string2\"}

attributes

map

A JSON string containing up to three key-value pair in JSON format. For example:

\"attributes\":{\"string1\":\"string2\"}

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.

billingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the billing group the thing will be added to.

Output

{ "thingName": "string", "thingArn": "string", "thingId": "string" }

CLI output fields

Name

Type

Description

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the new thing.

thingArn

string

The ARN of the new thing.

thingId

string

The thing ID.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceAlreadyExistsException

The resource already exists.

ResourceNotFoundException

The specified resource does not exist.

CreateThingGroup

Create a thing group.

Note

This is a control plane operation. See Authorization for information about authorizing control plane actions.

Synopsis

aws iot create-thing-group \ --thing-group-name <value> \ [--parent-group-name <value>] \ [--thing-group-properties <value>] \ [--tags <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingGroupName": "string", "parentGroupName": "string", "thingGroupProperties": { "thingGroupDescription": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" } }, "tags": [ { "Key": "string", "Value": "string" } ] }

cli-input-json fields

Name

Type

Description

thingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The thing group name to create.

parentGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the parent thing group.

thingGroupProperties

ThingGroupProperties

The thing group properties.

thingGroupDescription

string

length- max:2028

pattern: [\\p{Graph} ]*

The thing group description.

attributePayload

AttributePayload

The thing group attributes in JSON format.

attributes

map

A JSON string containing up to three key-value pair in JSON format. For example:

\"attributes\":{\"string1\":\"string2\"}

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.

tags

list

member: Tag

java class: java.util.List

Metadata which can be used to manage the thing group.

Key

string

The tag's key.

Value

string

The tag's value.

Output

{ "thingGroupName": "string", "thingGroupArn": "string", "thingGroupId": "string" }

CLI output fields

Name

Type

Description

thingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The thing group name.

thingGroupArn

string

The thing group ARN.

thingGroupId

string

length- max:128 min:1

pattern: [a-zA-Z0-9-]+

The thing group ID.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceAlreadyExistsException

The resource already exists.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

CreateThingType

Creates a new thing type.

Synopsis

aws iot create-thing-type \ --thing-type-name <value> \ [--thing-type-properties <value>] \ [--tags <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingTypeName": "string", "thingTypeProperties": { "thingTypeDescription": "string", "searchableAttributes": [ "string" ] }, "tags": [ { "Key": "string", "Value": "string" } ] }

cli-input-json fields

Name

Type

Description

thingTypeName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing type.

thingTypeProperties

ThingTypeProperties

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

length- max:2028

pattern: [\\p{Graph} ]*

The description of the thing type.

searchableAttributes

list

member: AttributeName

java class: java.util.List

A list of searchable thing attribute names.

tags

list

member: Tag

java class: java.util.List

Metadata which can be used to manage the thing type.

Key

string

The tag's key.

Value

string

The tag's value.

Output

{ "thingTypeName": "string", "thingTypeArn": "string", "thingTypeId": "string" }

CLI output fields

Name

Type

Description

thingTypeName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing type.

thingTypeArn

string

The Amazon Resource Name (ARN) of the thing type.

thingTypeId

string

The thing type ID.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceAlreadyExistsException

The resource already exists.

CreateTopicRule

Creates a rule. Creating rules is an administrator-level action. Any user who has permission to create rules will be able to access data processed by the rule.

Synopsis

aws iot create-topic-rule \ --rule-name <value> \ --topic-rule-payload <value> \ [--tags <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "ruleName": "string", "topicRulePayload": { "sql": "string", "description": "string", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" }, "iotAnalytics": { "channelArn": "string", "channelName": "string", "roleArn": "string" }, "iotEvents": { "inputName": "string", "messageId": "string", "roleArn": "string" }, "stepFunctions": { "executionNamePrefix": "string", "stateMachineName": "string", "roleArn": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" }, "iotAnalytics": { "channelArn": "string", "channelName": "string", "roleArn": "string" }, "iotEvents": { "inputName": "string", "messageId": "string", "roleArn": "string" }, "stepFunctions": { "executionNamePrefix": "string", "stateMachineName": "string", "roleArn": "string" } } }, "tags": "string" }

cli-input-json fields

Name

Type

Description

ruleName

string

length- max:128 min:1

pattern: ^[a-zA-Z0-9_]+$

The name of the rule.

topicRulePayload

TopicRulePayload

The rule payload.

sql

string

The SQL statement used to query the topic. For more information, see AWS IoT SQL Reference in the AWS IoT Developer Guide.

description

string

The description of the rule.

actions

list

member: Action

The actions associated with the rule.

dynamoDB

DynamoDBAction

Write to a DynamoDB table.

tableName

string

The name of the DynamoDB table.

roleArn

string

The ARN of the IAM role that grants access to the DynamoDB table.

operation

string

The type of operation to be performed. This follows the substitution template, so it can be $ operation, but the substitution must result in one of the following: INSERT, UPDATE, or DELETE.

hashKeyField

string

The hash key name.

hashKeyValue

string

The hash key value.

hashKeyType

string

The hash key type. Valid values are "STRING" or "NUMBER"

enum: STRING | NUMBER

rangeKeyField

string

The range key name.

rangeKeyValue

string

The range key value.

rangeKeyType

string

The range key type. Valid values are "STRING" or "NUMBER"

enum: STRING | NUMBER

payloadField

string

The action payload. This name can be customized.

dynamoDBv2

DynamoDBv2Action

Write to a DynamoDB table. This is a new version of the DynamoDB action. It allows you to write each attribute in an MQTT message payload into a separate DynamoDB column.

roleArn

string

The ARN of the IAM role that grants access to the DynamoDB table.

putItem

PutItemInput

Specifies the DynamoDB table to which the message data will be written. For example:

{ "dynamoDBv2": { "roleArn": "aws:iam:12341251:my-role" "putItem": { "tableName": "my-table" } } }

Each attribute in the message payload will be written to a separate column in the DynamoDB database.

tableName

string

The table where the message data will be written

lambda

LambdaAction

Invoke a Lambda function.

functionArn

string

The ARN of the Lambda function.

sns

SnsAction

Publish to an Amazon SNS topic.

targetArn

string

The ARN of the SNS topic.

roleArn

string

The ARN of the IAM role that grants access.

messageFormat

string

(Optional) The message format of the message to publish. Accepted values are "JSON" and "RAW". The default value of the attribute is "RAW". SNS uses this setting to determine if the payload should be parsed and relevant platform-specific bits of the payload should be extracted. To read more about SNS message formats, see https://docs.aws.amazon.com/sns/latest/dg/json-formats.html refer to their official documentation.

enum: RAW | JSON

sqs

SqsAction

Publish to an Amazon SQS queue.

roleArn

string

The ARN of the IAM role that grants access.

queueUrl

string

The URL of the Amazon SQS queue.

useBase64

boolean

Specifies whether to use Base64 encoding.

kinesis

KinesisAction

Write data to an Amazon Kinesis stream.

roleArn

string

The ARN of the IAM role that grants access to the Amazon Kinesis stream.

streamName

string

The name of the Amazon Kinesis stream.

partitionKey

string

The partition key.

republish

RepublishAction

Publish to another MQTT topic.

roleArn

string

The ARN of the IAM role that grants access.

topic

string

The name of the MQTT topic.

s3

S3Action

Write to an Amazon S3 bucket.

roleArn

string

The ARN of the IAM role that grants access.

bucketName

string

The Amazon S3 bucket.

key

string

The object key.

cannedAcl

string

The Amazon S3 canned ACL that controls access to the object identified by the object key. For more information, see S3 canned ACLs.

enum: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control | log-delivery-write

firehose

FirehoseAction

Write to an Amazon Kinesis Firehose stream.

roleArn

string

The IAM role that grants access to the Amazon Kinesis Firehose stream.

deliveryStreamName

string

The delivery stream name.

separator

string

pattern: ([ ])|( )|(,)

A character separator that will be used to separate records written to the Firehose stream. Valid values are: '\n' (newline), '\t' (tab), '\r\n' (Windows newline), ',' (comma).

cloudwatchMetric

CloudwatchMetricAction

Capture a CloudWatch metric.

roleArn

string

The IAM role that allows access to the CloudWatch metric.

metricNamespace

string

The CloudWatch metric namespace name.

metricName

string

The CloudWatch metric name.

metricValue

string

The CloudWatch metric value.

metricUnit

string

The metric unit supported by CloudWatch.

metricTimestamp

string

An optional Unix timestamp.

cloudwatchAlarm

CloudwatchAlarmAction

Change the state of a CloudWatch alarm.

roleArn

string

The IAM role that allows access to the CloudWatch alarm.

alarmName

string

The CloudWatch alarm name.

stateReason

string

The reason for the alarm change.

stateValue

string

The value of the alarm state. Acceptable values are: OK, ALARM, INSUFFICIENT_DATA.

elasticsearch

ElasticsearchAction

Write data to an Amazon Elasticsearch Service domain.

roleArn

string

The IAM role ARN that has access to Elasticsearch.

endpoint

string

pattern: https?://.*

The endpoint of your Elasticsearch domain.

index

string

The Elasticsearch index where you want to store your data.

type

string

The type of document you are storing.

id

string

The unique identifier for the document you are storing.

salesforce

SalesforceAction

Send a message to a Salesforce IoT Cloud Input Stream.

token

string

length- min:40

The token used to authenticate access to the Salesforce IoT Cloud Input Stream. The token is available from the Salesforce IoT Cloud platform after creation of the Input Stream.

url

string

length- max:2000

pattern: https://ingestion-[a-zA-Z0-9]{1,12}.[a-zA-Z0-9]+.((sfdc-matrix.net)|(sfdcnow.com))/streams/w 1,20/w 1,20/event

The URL exposed by the Salesforce IoT Cloud Input Stream. The URL is available from the Salesforce IoT Cloud platform after creation of the Input Stream.

iotAnalytics

IotAnalyticsAction

Sends message data to an AWS IoT Analytics channel.

channelArn

string

(deprecated) The ARN of the IoT Analytics channel to which message data will be sent.

channelName

string

The name of the IoT Analytics channel to which message data will be sent.

roleArn

string

The ARN of the role which has a policy that grants IoT Analytics permission to send message data via IoT Analytics (iotanalytics:BatchPutMessage).

iotEvents

IotEventsAction

Sends an input to an AWS IoT Events detector.

inputName

string

length- max:128 min:1

The name of the AWS IoT Events input.

messageId

string

length- max:128

[Optional] Use this to ensure that only one input (message) with a given messageId will be processed by an AWS IoT Events detector.

roleArn

string

The ARN of the role that grants AWS IoT permission to send an input to an AWS IoT Events detector. ("Action":"iotevents:BatchPutMessage").

stepFunctions

StepFunctionsAction

Starts execution of a Step Functions state machine.

executionNamePrefix

string

(Optional) A name will be given to the state machine execution consisting of this prefix followed by a UUID. Step Functions automatically creates a unique name for each state machine execution if one is not provided.

stateMachineName

string

The name of the Step Functions state machine whose execution will be started.

roleArn

string

The ARN of the role that grants IoT permission to start execution of a state machine ("Action":"states:StartExecution").

ruleDisabled

boolean

Specifies whether the rule is disabled.

awsIotSqlVersion

string

The version of the SQL rules engine to use when evaluating the rule.

errorAction

Action

The action to take when an error occurs.

dynamoDB

DynamoDBAction

Write to a DynamoDB table.

tableName

string

The name of the DynamoDB table.

roleArn

string

The ARN of the IAM role that grants access to the DynamoDB table.

operation

string

The type of operation to be performed. This follows the substitution template, so it can be $ operation, but the substitution must result in one of the following: INSERT, UPDATE, or DELETE.

hashKeyField

string

The hash key name.

hashKeyValue

string

The hash key value.

hashKeyType

string

The hash key type. Valid values are "STRING" or "NUMBER"

enum: STRING | NUMBER

rangeKeyField

string

The range key name.

rangeKeyValue

string

The range key value.

rangeKeyType

string

The range key type. Valid values are "STRING" or "NUMBER"

enum: STRING | NUMBER

payloadField

string

The action payload. This name can be customized.

dynamoDBv2

DynamoDBv2Action

Write to a DynamoDB table. This is a new version of the DynamoDB action. It allows you to write each attribute in an MQTT message payload into a separate DynamoDB column.

roleArn

string

The ARN of the IAM role that grants access to the DynamoDB table.

putItem

PutItemInput

Specifies the DynamoDB table to which the message data will be written. For example:

{ "dynamoDBv2": { "roleArn": "aws:iam:12341251:my-role" "putItem": { "tableName": "my-table" } } }

Each attribute in the message payload will be written to a separate column in the DynamoDB database.

tableName

string

The table where the message data will be written

lambda

LambdaAction

Invoke a Lambda function.

functionArn

string

The ARN of the Lambda function.

sns

SnsAction

Publish to an Amazon SNS topic.

targetArn

string

The ARN of the SNS topic.

roleArn

string

The ARN of the IAM role that grants access.

messageFormat

string

(Optional) The message format of the message to publish. Accepted values are "JSON" and "RAW". The default value of the attribute is "RAW". SNS uses this setting to determine if the payload should be parsed and relevant platform-specific bits of the payload should be extracted. To read more about SNS message formats, see https://docs.aws.amazon.com/sns/latest/dg/json-formats.html refer to their official documentation.

enum: RAW | JSON

sqs

SqsAction

Publish to an Amazon SQS queue.

roleArn

string

The ARN of the IAM role that grants access.

queueUrl

string

The URL of the Amazon SQS queue.

useBase64

boolean

Specifies whether to use Base64 encoding.

kinesis

KinesisAction

Write data to an Amazon Kinesis stream.

roleArn

string

The ARN of the IAM role that grants access to the Amazon Kinesis stream.

streamName

string

The name of the Amazon Kinesis stream.

partitionKey

string

The partition key.

republish

RepublishAction

Publish to another MQTT topic.

roleArn

string

The ARN of the IAM role that grants access.

topic

string

The name of the MQTT topic.

s3

S3Action

Write to an Amazon S3 bucket.

roleArn

string

The ARN of the IAM role that grants access.

bucketName

string

The Amazon S3 bucket.

key

string

The object key.

cannedAcl

string

The Amazon S3 canned ACL that controls access to the object identified by the object key. For more information, see S3 canned ACLs.

enum: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control | log-delivery-write

firehose

FirehoseAction

Write to an Amazon Kinesis Firehose stream.

roleArn

string

The IAM role that grants access to the Amazon Kinesis Firehose stream.

deliveryStreamName

string

The delivery stream name.

separator

string

pattern: ([ ])|( )|(,)

A character separator that will be used to separate records written to the Firehose stream. Valid values are: '\n' (newline), '\t' (tab), '\r\n' (Windows newline), ',' (comma).

cloudwatchMetric

CloudwatchMetricAction

Capture a CloudWatch metric.

roleArn

string

The IAM role that allows access to the CloudWatch metric.

metricNamespace

string

The CloudWatch metric namespace name.

metricName

string

The CloudWatch metric name.

metricValue

string

The CloudWatch metric value.

metricUnit

string

The metric unit supported by CloudWatch.

metricTimestamp

string

An optional Unix timestamp.

cloudwatchAlarm

CloudwatchAlarmAction

Change the state of a CloudWatch alarm.

roleArn

string

The IAM role that allows access to the CloudWatch alarm.

alarmName

string

The CloudWatch alarm name.

stateReason

string

The reason for the alarm change.

stateValue

string

The value of the alarm state. Acceptable values are: OK, ALARM, INSUFFICIENT_DATA.

elasticsearch

ElasticsearchAction

Write data to an Amazon Elasticsearch Service domain.

roleArn

string

The IAM role ARN that has access to Elasticsearch.

endpoint

string

pattern: https?://.*

The endpoint of your Elasticsearch domain.

index

string

The Elasticsearch index where you want to store your data.

type

string

The type of document you are storing.

id

string

The unique identifier for the document you are storing.

salesforce

SalesforceAction

Send a message to a Salesforce IoT Cloud Input Stream.

token

string

length- min:40

The token used to authenticate access to the Salesforce IoT Cloud Input Stream. The token is available from the Salesforce IoT Cloud platform after creation of the Input Stream.

url

string

length- max:2000

pattern: https://ingestion-[a-zA-Z0-9]{1,12}.[a-zA-Z0-9]+.((sfdc-matrix.net)|(sfdcnow.com))/streams/w 1,20/w 1,20/event

The URL exposed by the Salesforce IoT Cloud Input Stream. The URL is available from the Salesforce IoT Cloud platform after creation of the Input Stream.

iotAnalytics

IotAnalyticsAction

Sends message data to an AWS IoT Analytics channel.

channelArn

string

(deprecated) The ARN of the IoT Analytics channel to which message data will be sent.

channelName

string

The name of the IoT Analytics channel to which message data will be sent.

roleArn

string

The ARN of the role which has a policy that grants IoT Analytics permission to send message data via IoT Analytics (iotanalytics:BatchPutMessage).

iotEvents

IotEventsAction

Sends an input to an AWS IoT Events detector.

inputName

string

length- max:128 min:1

The name of the AWS IoT Events input.

messageId

string

length- max:128

[Optional] Use this to ensure that only one input (message) with a given messageId will be processed by an AWS IoT Events detector.

roleArn

string

The ARN of the role that grants AWS IoT permission to send an input to an AWS IoT Events detector. ("Action":"iotevents:BatchPutMessage").

stepFunctions

StepFunctionsAction

Starts execution of a Step Functions state machine.

executionNamePrefix

string

(Optional) A name will be given to the state machine execution consisting of this prefix followed by a UUID. Step Functions automatically creates a unique name for each state machine execution if one is not provided.

stateMachineName

string

The name of the Step Functions state machine whose execution will be started.

roleArn

string

The ARN of the role that grants IoT permission to start execution of a state machine ("Action":"states:StartExecution").

tags

string

Metadata which can be used to manage the topic rule.

Note

For URI Request parameters use format: ...key1=value1&key2=value2...

For the CLI command-line parameter use format: --tags "key1=value1&key2=value2..."

For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

Output

None

Errors

SqlParseException

The Rule-SQL expression can't be parsed correctly.

InternalException

An unexpected error has occurred.

InvalidRequestException

The contents of the request were invalid.

ResourceAlreadyExistsException

The resource already exists.

ServiceUnavailableException

The service is temporarily unavailable.

ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a conflict.

DeleteAccountAuditConfiguration

Restores the default settings for Device Defender audits for this account. Any configuration data you entered is deleted and all audit checks are reset to disabled.

Synopsis

aws iot delete-account-audit-configuration \ [--delete-scheduled-audits | --no-delete-scheduled-audits] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "deleteScheduledAudits": "boolean" }

cli-input-json fields

Name

Type

Description

deleteScheduledAudits

boolean

If true, all scheduled audits are deleted.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

DeleteAuthorizer

Deletes an authorizer.

Synopsis

aws iot delete-authorizer \ --authorizer-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "authorizerName": "string" }

cli-input-json fields

Name

Type

Description

authorizerName

string

length- max:128 min:1

pattern: [w=,@-]+

The name of the authorizer to delete.

Output

None

Errors

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DeleteBillingGroup

Deletes the billing group.

Synopsis

aws iot delete-billing-group \ --billing-group-name <value> \ [--expected-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "billingGroupName": "string", "expectedVersion": "long" }

cli-input-json fields

Name

Type

Description

billingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the billing group.

expectedVersion

long

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.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

VersionConflictException

An exception thrown when the version of a thing passed to a command is different than the version specified with the --version parameter.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

DeleteCACertificate

Deletes a registered CA certificate.

Synopsis

aws iot delete-ca-certificate \ --certificate-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "certificateId": "string" }

cli-input-json fields

Name

Type

Description

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The ID of the certificate to delete. (The last part of the certificate ARN contains the certificate ID.)

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

CertificateStateException

The certificate operation is not allowed.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

DeleteCertificate

Deletes the specified certificate.

A certificate cannot be deleted if it has a policy attached to it or if its status is set to ACTIVE. To delete a certificate, first use the DetachPrincipalPolicy API to detach all policies. Next, use the UpdateCertificate API to set the certificate to the INACTIVE status.

Synopsis

aws iot delete-certificate \ --certificate-id <value> \ [--force-delete | --no-force-delete] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "certificateId": "string", "forceDelete": "boolean" }

cli-input-json fields

Name

Type

Description

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)

forceDelete

boolean

Forces a certificate request to be deleted.

Output

None

Errors

CertificateStateException

The certificate operation is not allowed.

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

DeleteDynamicThingGroup

Deletes a dynamic thing group.

Synopsis

aws iot delete-dynamic-thing-group \ --thing-group-name <value> \ [--expected-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingGroupName": "string", "expectedVersion": "long" }

cli-input-json fields

Name

Type

Description

thingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the dynamic thing group to delete.

expectedVersion

long

The expected version of the dynamic thing group to delete.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

VersionConflictException

An exception thrown when the version of a thing passed to a command is different than the version specified with the --version parameter.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

DeleteJob

Deletes a job and its related job executions.

Deleting a job may take time, depending on the number of job executions created for the job and various other factors. While the job is being deleted, the status of the job will be shown as "DELETION_IN_PROGRESS". Attempting to delete or cancel a job whose status is already "DELETION_IN_PROGRESS" will result in an error.

Only 10 jobs may have status "DELETION_IN_PROGRESS" at the same time, or a LimitExceededException will occur.

Synopsis

aws iot delete-job \ --job-id <value> \ [--force | --no-force] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "jobId": "string", "force": "boolean" }

cli-input-json fields

Name

Type

Description

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The ID of the job to be deleted.

After a job deletion is completed, you may reuse this jobId when you create a new job. However, this is not recommended, and you must ensure that your devices are not using the jobId to refer to the deleted job.

force

boolean

(Optional) When true, you can delete a job which is "IN_PROGRESS". Otherwise, you can only delete a job which is in a terminal state ("COMPLETED" or "CANCELED") or an exception will occur. The default is false.

Note

Deleting a job which is "IN_PROGRESS", will cause a device which is executing the job to be unable to access job information or update the job execution status. Use caution and ensure that each device executing a job which is deleted is able to recover to a valid state.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

InvalidStateTransitionException

An update attempted to change the job execution to a state that is invalid because of the job execution's current state (for example, an attempt to change a request in state SUCCESS to state IN_PROGRESS). In this case, the body of the error message also contains the executionState field.

ResourceNotFoundException

The specified resource does not exist.

LimitExceededException

A limit has been exceeded.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

DeleteJobExecution

Deletes a job execution.

Synopsis

aws iot delete-job-execution \ --job-id <value> \ --thing-name <value> \ --execution-number <value> \ [--force | --no-force] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "jobId": "string", "thingName": "string", "executionNumber": "long", "force": "boolean" }

cli-input-json fields

Name

Type

Description

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The ID of the job whose execution on a particular device will be deleted.

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing whose job execution will be deleted.

executionNumber

long

The ID of the job execution to be deleted. The executionNumber refers to the execution of a particular job on a particular device.

Note that once a job execution is deleted, the executionNumber may be reused by IoT, so be sure you get and use the correct value here.

force

boolean

(Optional) When true, you can delete a job execution which is "IN_PROGRESS". Otherwise, you can only delete a job execution which is in a terminal state ("SUCCEEDED", "FAILED", "REJECTED", "REMOVED" or "CANCELED") or an exception will occur. The default is false.

Note

Deleting a job execution which is "IN_PROGRESS", will cause the device to be unable to access job information or update the job execution status. Use caution and ensure that the device is able to recover to a valid state.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

InvalidStateTransitionException

An update attempted to change the job execution to a state that is invalid because of the job execution's current state (for example, an attempt to change a request in state SUCCESS to state IN_PROGRESS). In this case, the body of the error message also contains the executionState field.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

DeleteOTAUpdate

Delete an OTA update.

Synopsis

aws iot delete-ota-update \ --ota-update-id <value> \ [--delete-stream | --no-delete-stream] \ [--force-delete-aws-job | --no-force-delete-aws-job] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "otaUpdateId": "string", "deleteStream": "boolean", "forceDeleteAWSJob": "boolean" }

cli-input-json fields

Name

Type

Description

otaUpdateId

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The OTA update ID to delete.

deleteStream

boolean

Specifies if the stream associated with an OTA update should be deleted when the OTA update is deleted.

forceDeleteAWSJob

boolean

Specifies if the AWS Job associated with the OTA update should be deleted with the OTA update is deleted.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

InternalFailureException

An unexpected error has occurred.

ServiceUnavailableException

The service is temporarily unavailable.

VersionConflictException

An exception thrown when the version of a thing passed to a command is different than the version specified with the --version parameter.

DeletePolicy

Deletes the specified policy.

A policy cannot be deleted if it has non-default versions or it is attached to any certificate.

To delete a policy, use the DeletePolicyVersion API to delete all non-default versions of the policy; use the DetachPrincipalPolicy API to detach the policy from any certificate; and then use the DeletePolicy API to delete the policy.

When a policy is deleted using DeletePolicy, its default version is deleted with it.

Synopsis

aws iot delete-policy \ --policy-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "policyName": "string" }

cli-input-json fields

Name

Type

Description

policyName

string

length- max:128 min:1

pattern: [w+=,.@-]+

The name of the policy to delete.

Output

None

Errors

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DeletePolicyVersion

Deletes the specified version of the specified policy. You cannot delete the default version of a policy using this API. To delete the default version of a policy, use DeletePolicy. To find out which version of a policy is marked as the default version, use ListPolicyVersions.

Synopsis

aws iot delete-policy-version \ --policy-name <value> \ --policy-version-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "policyName": "string", "policyVersionId": "string" }

cli-input-json fields

Name

Type

Description

policyName

string

length- max:128 min:1

pattern: [w+=,.@-]+

The name of the policy.

policyVersionId

string

pattern: [0-9]+

The policy version ID.

Output

None

Errors

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DeleteRegistrationCode

Deletes a CA certificate registration code.

Synopsis

aws iot delete-registration-code \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ }

Output

None

Errors

ThrottlingException

The rate exceeds the limit.

ResourceNotFoundException

The specified resource does not exist.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DeleteRoleAlias

Deletes a role alias

Synopsis

aws iot delete-role-alias \ --role-alias <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "roleAlias": "string" }

cli-input-json fields

Name

Type

Description

roleAlias

string

length- max:128 min:1

pattern: [w=,@-]+

The role alias to delete.

Output

None

Errors

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

DeleteScheduledAudit

Deletes a scheduled audit.

Synopsis

aws iot delete-scheduled-audit \ --scheduled-audit-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "scheduledAuditName": "string" }

cli-input-json fields

Name

Type

Description

scheduledAuditName

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The name of the scheduled audit you want to delete.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

DeleteSecurityProfile

Deletes a Device Defender security profile.

Synopsis

aws iot delete-security-profile \ --security-profile-name <value> \ [--expected-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "securityProfileName": "string", "expectedVersion": "long" }

cli-input-json fields

Name

Type

Description

securityProfileName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the security profile to be deleted.

expectedVersion

long

The expected version of the security profile. A new version is generated whenever the security profile is updated. If you specify a value that is different than the actual version, a VersionConflictException is thrown.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

VersionConflictException

An exception thrown when the version of a thing passed to a command is different than the version specified with the --version parameter.

DeleteStream

Deletes a stream.

Synopsis

aws iot delete-stream \ --stream-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "streamId": "string" }

cli-input-json fields

Name

Type

Description

streamId

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The stream ID.

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DeleteThing

Deletes the specified thing. Returns successfully with no error if the deletion is successful or you specify a thing that doesn't exist.

Synopsis

aws iot delete-thing \ --thing-name <value> \ [--expected-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingName": "string", "expectedVersion": "long" }

cli-input-json fields

Name

Type

Description

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing to delete.

expectedVersion

long

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.

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

VersionConflictException

An exception thrown when the version of a thing passed to a command is different than the version specified with the --version parameter.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DeleteThingGroup

Deletes a thing group.

Synopsis

aws iot delete-thing-group \ --thing-group-name <value> \ [--expected-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingGroupName": "string", "expectedVersion": "long" }

cli-input-json fields

Name

Type

Description

thingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing group to delete.

expectedVersion

long

The expected version of the thing group to delete.

Output

None

Errors

InvalidRequestException

The contents of the request were invalid.

VersionConflictException

An exception thrown when the version of a thing passed to a command is different than the version specified with the --version parameter.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

DeleteThingShadow

Deletes the shadow for the specified thing.

For more information, see DeleteThingShadow in the AWS IoT Developer Guide.

Synopsis

aws iot-data delete-thing-shadow \ --thing-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingName": "string" }

cli-input-json fields

Name

Type

Description

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing.

Output

{ "payload": "blob" }

CLI output fields

Name

Type

Description

payload

blob

The state information, in JSON format.

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

UnsupportedDocumentEncodingException

The encoding is not supported.

DeleteThingType

Deletes the specified thing type. You cannot delete a thing type if it has things associated with it. To delete a thing type, first mark it as deprecated by calling DeprecateThingType, then remove any associated things by calling UpdateThing to change the thing type on any associated thing, and finally use DeleteThingType to delete the thing type.

Synopsis

aws iot delete-thing-type \ --thing-type-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingTypeName": "string" }

cli-input-json fields

Name

Type

Description

thingTypeName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing type.

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DeleteTopicRule

Deletes the rule.

Synopsis

aws iot delete-topic-rule \ [--rule-name <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "ruleName": "string" }

cli-input-json fields

Name

Type

Description

ruleName

string

length- max:128 min:1

pattern: ^[a-zA-Z0-9_]+$

The name of the rule.

Output

None

Errors

InternalException

An unexpected error has occurred.

InvalidRequestException

The contents of the request were invalid.

ServiceUnavailableException

The service is temporarily unavailable.

UnauthorizedException

You are not authorized to perform this operation.

ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a conflict.

DeleteV2LoggingLevel

Deletes a logging level.

Synopsis

aws iot delete-v2-logging-level \ --target-type <value> \ --target-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "targetType": "string", "targetName": "string" }

cli-input-json fields

Name

Type

Description

targetType

string

The type of resource for which you are configuring logging. Must be THING_Group.

enum: DEFAULT | THING_GROUP

targetName

string

The name of the resource for which you are configuring logging.

Output

None

Errors

InternalException

An unexpected error has occurred.

InvalidRequestException

The contents of the request were invalid.

ServiceUnavailableException

The service is temporarily unavailable.

DeprecateThingType

Deprecates a thing type. You can not associate new things with deprecated thing type.

Synopsis

aws iot deprecate-thing-type \ --thing-type-name <value> \ [--undo-deprecate | --no-undo-deprecate] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "thingTypeName": "string", "undoDeprecate": "boolean" }

cli-input-json fields

Name

Type

Description

thingTypeName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing type to deprecate.

undoDeprecate

boolean

Whether to undeprecate a deprecated thing type. If true, the thing type will not be deprecated anymore and you can associate it with things.

Output

None

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DescribeAccountAuditConfiguration

Gets information about the Device Defender audit settings for this account. Settings include how audit notifications are sent and which audit checks are enabled or disabled.

Synopsis

aws iot describe-account-audit-configuration \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ }

Output

{ "roleArn": "string", "auditNotificationTargetConfigurations": { "string": { "targetArn": "string", "roleArn": "string", "enabled": "boolean" } }, "auditCheckConfigurations": { "string": { "enabled": "boolean" } } }

CLI output fields

Name

Type

Description

roleArn

string

length- max:2048 min:20

The ARN of the role that grants permission to AWS IoT to access information about your devices, policies, certificates and other items as necessary when performing an audit.

On the first call to UpdateAccountAuditConfiguration this parameter is required.

auditNotificationTargetConfigurations

map

Information about the targets to which audit notifications are sent for this account.

targetArn

string

The ARN of the target (SNS topic) to which audit notifications are sent.

roleArn

string

length- max:2048 min:20

The ARN of the role that grants permission to send notifications to the target.

enabled

boolean

True if notifications to the target are enabled.

auditCheckConfigurations

map

Which audit checks are enabled and disabled for this account.

enabled

boolean

True if this audit check is enabled for this account.

Errors

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

DescribeAuditTask

Gets information about a Device Defender audit.

Synopsis

aws iot describe-audit-task \ --task-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "taskId": "string" }

cli-input-json fields

Name

Type

Description

taskId

string

length- max:40 min:1

pattern: [a-zA-Z0-9-]+

The ID of the audit whose information you want to get.

Output

{ "taskStatus": "string", "taskType": "string", "taskStartTime": "timestamp", "taskStatistics": { "totalChecks": "integer", "inProgressChecks": "integer", "waitingForDataCollectionChecks": "integer", "compliantChecks": "integer", "nonCompliantChecks": "integer", "failedChecks": "integer", "canceledChecks": "integer" }, "scheduledAuditName": "string", "auditDetails": { "string": { "checkRunStatus": "string", "checkCompliant": "boolean", "totalResourcesCount": "long", "nonCompliantResourcesCount": "long", "errorCode": "string", "message": "string" } } }

CLI output fields

Name

Type

Description

taskStatus

string

The status of the audit: one of "IN_PROGRESS", "COMPLETED", "FAILED", or "CANCELED".

enum: IN_PROGRESS | COMPLETED | FAILED | CANCELED

taskType

string

The type of audit: "ON_DEMAND_AUDIT_TASK" or "SCHEDULED_AUDIT_TASK".

enum: ON_DEMAND_AUDIT_TASK | SCHEDULED_AUDIT_TASK

taskStartTime

timestamp

The time the audit started.

taskStatistics

TaskStatistics

Statistical information about the audit.

totalChecks

integer

The number of checks in this audit.

inProgressChecks

integer

The number of checks in progress.

waitingForDataCollectionChecks

integer

The number of checks waiting for data collection.

compliantChecks

integer

The number of checks that found compliant resources.

nonCompliantChecks

integer

The number of checks that found non-compliant resources.

failedChecks

integer

The number of checks

canceledChecks

integer

The number of checks that did not run because the audit was canceled.

scheduledAuditName

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The name of the scheduled audit (only if the audit was a scheduled audit).

auditDetails

map

Detailed information about each check performed during this audit.

checkRunStatus

string

The completion status of this check, one of "IN_PROGRESS", "WAITING_FOR_DATA_COLLECTION", "CANCELED", "COMPLETED_COMPLIANT", "COMPLETED_NON_COMPLIANT", or "FAILED".

enum: IN_PROGRESS | WAITING_FOR_DATA_COLLECTION | CANCELED | COMPLETED_COMPLIANT | COMPLETED_NON_COMPLIANT | FAILED

checkCompliant

boolean

True if the check completed and found all resources compliant.

totalResourcesCount

long

The number of resources on which the check was performed.

nonCompliantResourcesCount

long

The number of resources that the check found non-compliant.

errorCode

string

The code of any error encountered when performing this check during this audit. One of "INSUFFICIENT_PERMISSIONS", or "AUDIT_CHECK_DISABLED".

message

string

length- max:2048

The message associated with any error encountered when performing this check during this audit.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

DescribeAuthorizer

Describes an authorizer.

Synopsis

aws iot describe-authorizer \ --authorizer-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "authorizerName": "string" }

cli-input-json fields

Name

Type

Description

authorizerName

string

length- max:128 min:1

pattern: [w=,@-]+

The name of the authorizer to describe.

Output

{ "authorizerDescription": { "authorizerName": "string", "authorizerArn": "string", "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp" } }

CLI output fields

Name

Type

Description

authorizerDescription

AuthorizerDescription

The authorizer description.

authorizerName

string

length- max:128 min:1

pattern: [w=,@-]+

The authorizer name.

authorizerArn

string

The authorizer ARN.

authorizerFunctionArn

string

The authorizer's Lambda function ARN.

tokenKeyName

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The key used to extract the token from the HTTP headers.

tokenSigningPublicKeys

map

The public keys used to validate the token signature returned by your custom authentication service.

status

string

The status of the authorizer.

enum: ACTIVE | INACTIVE

creationDate

timestamp

The UNIX timestamp of when the authorizer was created.

lastModifiedDate

timestamp

The UNIX timestamp of when the authorizer was last updated.

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DescribeBillingGroup

Returns information about a billing group.

Synopsis

aws iot describe-billing-group \ --billing-group-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "billingGroupName": "string" }

cli-input-json fields

Name

Type

Description

billingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the billing group.

Output

{ "billingGroupName": "string", "billingGroupId": "string", "billingGroupArn": "string", "version": "long", "billingGroupProperties": { "billingGroupDescription": "string" }, "billingGroupMetadata": { "creationDate": "timestamp" } }

CLI output fields

Name

Type

Description

billingGroupName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the billing group.

billingGroupId

string

length- max:128 min:1

pattern: [a-zA-Z0-9-]+

The ID of the billing group.

billingGroupArn

string

The ARN of the billing group.

version

long

The version of the billing group.

billingGroupProperties

BillingGroupProperties

The properties of the billing group.

billingGroupDescription

string

length- max:2028

pattern: [\\p{Graph} ]*

The description of the billing group.

billingGroupMetadata

BillingGroupMetadata

Additional information about the billing group.

creationDate

timestamp

The date the billing group was created.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

DescribeCACertificate

Describes a registered CA certificate.

Synopsis

aws iot describe-ca-certificate \ --certificate-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "certificateId": "string" }

cli-input-json fields

Name

Type

Description

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The CA certificate identifier.

Output

{ "certificateDescription": { "certificateArn": "string", "certificateId": "string", "status": "string", "certificatePem": "string", "ownedBy": "string", "creationDate": "timestamp", "autoRegistrationStatus": "string", "lastModifiedDate": "timestamp", "customerVersion": "integer", "generationId": "string", "validity": { "notBefore": "timestamp", "notAfter": "timestamp" } }, "registrationConfig": { "templateBody": "string", "roleArn": "string" } }

CLI output fields

Name

Type

Description

certificateDescription

CACertificateDescription

The CA certificate description.

certificateArn

string

The CA certificate ARN.

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The CA certificate ID.

status

string

The status of a CA certificate.

enum: ACTIVE | INACTIVE

certificatePem

string

length- max:65536 min:1

The CA certificate data, in PEM format.

ownedBy

string

length- max:12 min:12

pattern: [0-9]+

The owner of the CA certificate.

creationDate

timestamp

The date the CA certificate was created.

autoRegistrationStatus

string

Whether the CA certificate configured for auto registration of device certificates. Valid values are "ENABLE" and "DISABLE"

enum: ENABLE | DISABLE

lastModifiedDate

timestamp

The date the CA certificate was last modified.

customerVersion

integer

range- min:1

The customer version of the CA certificate.

generationId

string

The generation ID of the CA certificate.

validity

CertificateValidity

When the CA certificate is valid.

notBefore

timestamp

The certificate is not valid before this date.

notAfter

timestamp

The certificate is not valid after this date.

registrationConfig

RegistrationConfig

Information about the registration configuration.

templateBody

string

The template body.

roleArn

string

length- max:2048 min:20

The ARN of the role.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

DescribeCertificate

Gets information about the specified certificate.

Synopsis

aws iot describe-certificate \ --certificate-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "certificateId": "string" }

cli-input-json fields

Name

Type

Description

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)

Output

{ "certificateDescription": { "certificateArn": "string", "certificateId": "string", "caCertificateId": "string", "status": "string", "certificatePem": "string", "ownedBy": "string", "previousOwnedBy": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp", "customerVersion": "integer", "transferData": { "transferMessage": "string", "rejectReason": "string", "transferDate": "timestamp", "acceptDate": "timestamp", "rejectDate": "timestamp" }, "generationId": "string", "validity": { "notBefore": "timestamp", "notAfter": "timestamp" } } }

CLI output fields

Name

Type

Description

certificateDescription

CertificateDescription

The description of the certificate.

certificateArn

string

The ARN of the certificate.

certificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The ID of the certificate.

caCertificateId

string

length- max:64 min:64

pattern: (0x)?[a-fA-F0-9]+

The certificate ID of the CA certificate used to sign this certificate.

status

string

The status of the certificate.

enum: ACTIVE | INACTIVE | REVOKED | PENDING_TRANSFER | REGISTER_INACTIVE | PENDING_ACTIVATION

certificatePem

string

length- max:65536 min:1

The certificate data, in PEM format.

ownedBy

string

length- max:12 min:12

pattern: [0-9]+

The ID of the AWS account that owns the certificate.

previousOwnedBy

string

length- max:12 min:12

pattern: [0-9]+

The ID of the AWS account of the previous owner of the certificate.

creationDate

timestamp

The date and time the certificate was created.

lastModifiedDate

timestamp

The date and time the certificate was last modified.

customerVersion

integer

range- min:1

The customer version of the certificate.

transferData

TransferData

The transfer data.

transferMessage

string

length- max:128

The transfer message.

rejectReason

string

length- max:128

The reason why the transfer was rejected.

transferDate

timestamp

The date the transfer took place.

acceptDate

timestamp

The date the transfer was accepted.

rejectDate

timestamp

The date the transfer was rejected.

generationId

string

The generation ID of the certificate.

validity

CertificateValidity

When the certificate is valid.

notBefore

timestamp

The certificate is not valid before this date.

notAfter

timestamp

The certificate is not valid after this date.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

DescribeDefaultAuthorizer

Describes the default authorizer.

Synopsis

aws iot describe-default-authorizer \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ }

Output

{ "authorizerDescription": { "authorizerName": "string", "authorizerArn": "string", "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp" } }

CLI output fields

Name

Type

Description

authorizerDescription

AuthorizerDescription

The default authorizer's description.

authorizerName

string

length- max:128 min:1

pattern: [w=,@-]+

The authorizer name.

authorizerArn

string

The authorizer ARN.

authorizerFunctionArn

string

The authorizer's Lambda function ARN.

tokenKeyName

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The key used to extract the token from the HTTP headers.

tokenSigningPublicKeys

map

The public keys used to validate the token signature returned by your custom authentication service.

status

string

The status of the authorizer.

enum: ACTIVE | INACTIVE

creationDate

timestamp

The UNIX timestamp of when the authorizer was created.

lastModifiedDate

timestamp

The UNIX timestamp of when the authorizer was last updated.

Errors

ResourceNotFoundException

The specified resource does not exist.

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

DescribeEndpoint

Returns a unique endpoint specific to the AWS account making the call.

Synopsis

aws iot describe-endpoint \ [--endpoint-type <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "endpointType": "string" }

cli-input-json fields

Name

Type

Description

endpointType

string

The endpoint type. Valid endpoint types include:

  • iot:Data - Returns a VeriSign signed data endpoint.

  • iot:Data-ATS - Returns an ATS signed data endpoint.

  • iot:CredentialProvider - Returns an AWS IoT credentials provider API endpoint.

  • iot:Jobs - Returns an AWS IoT device management Jobs API endpoint.

Output

{ "endpointAddress": "string" }

CLI output fields

Name

Type

Description

endpointAddress

string

The endpoint. The format of the endpoint is as follows: identifier.iot.region.amazonaws.com.

Errors

InternalFailureException

An unexpected error has occurred.

InvalidRequestException

The contents of the request were invalid.

UnauthorizedException

You are not authorized to perform this operation.

ThrottlingException

The rate exceeds the limit.

DescribeEventConfigurations

Describes event configurations.

Synopsis

aws iot describe-event-configurations \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ }

Output

{ "eventConfigurations": { "string": { "Enabled": "boolean" } }, "creationDate": "timestamp", "lastModifiedDate": "timestamp" }

CLI output fields

Name

Type

Description

eventConfigurations

map

The event configurations.

Enabled

boolean

True to enable the configuration.

creationDate

timestamp

The creation date of the event configuration.

lastModifiedDate

timestamp

The date the event configurations were last modified.

Errors

InternalFailureException

An unexpected error has occurred.

ThrottlingException

The rate exceeds the limit.

DescribeIndex

Describes a search index.

Synopsis

aws iot describe-index \ --index-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "indexName": "string" }

cli-input-json fields

Name

Type

Description

indexName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The index name.

Output

{ "indexName": "string", "indexStatus": "string", "schema": "string" }

CLI output fields

Name

Type

Description

indexName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The index name.

indexStatus

string

The index status.

enum: ACTIVE | BUILDING | REBUILDING

schema

string

Contains a value that specifies the type of indexing performed. Valid values are:

  • REGISTRY – Your thing index will contain only registry data.

  • REGISTRY_AND_SHADOW - Your thing index will contain registry data and shadow data.

  • REGISTRY_AND_CONNECTIVITY_STATUS - Your thing index will contain registry data and thing connectivity status data.

  • REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS - Your thing index will contain registry data, shadow data, and thing connectivity status data.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

DescribeJob

Describes a job.

Synopsis

aws iot describe-job \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "jobId": "string" }

cli-input-json fields

Name

Type

Description

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

Output

{ "documentSource": "string", "job": { "jobArn": "string", "jobId": "string", "targetSelection": "string", "status": "string", "forceCanceled": "boolean", "reasonCode": "string", "comment": "string", "targets": [ "string" ], "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer", "exponentialRate": { "baseRatePerMinute": "integer", "incrementFactor": "double", "rateIncreaseCriteria": { "numberOfNotifiedThings": "integer", "numberOfSucceededThings": "integer" } } }, "abortConfig": { "criteriaList": [ { "failureType": "string", "action": "string", "thresholdPercentage": "double", "minNumberOfExecutedThings": "integer" } ] }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer", "numberOfTimedOutThings": "integer" }, "timeoutConfig": { "inProgressTimeoutInMinutes": "long" } } }

CLI output fields

Name

Type

Description

documentSource

string

length- max:1350 min:1

An S3 link to the job document.

job

Job

Information about the job.

jobArn

string

An ARN identifying the job with format "arn:aws:iot:region:account:job/jobId".

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

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.

enum: CONTINUOUS | SNAPSHOT

status

string

The status of the job, one of IN_PROGRESS, CANCELED, DELETION_IN_PROGRESS or COMPLETED.

enum: IN_PROGRESS | CANCELED | COMPLETED | DELETION_IN_PROGRESS

forceCanceled

boolean

Will be true if the job was canceled with the optional force parameter set to true.

reasonCode

string

length- max:128

pattern: [\\p{Upper}p Digit_]+

If the job was updated, provides the reason code for the update.

comment

string

length- max:2028

pattern: [^\\p{C}]+

If the job was updated, describes the reason for the update.

targets

list

member: TargetArn

A list of IoT things and thing groups to which the job should be sent.

description

string

length- max:2028

pattern: [^\\p{C}]+

A short text description of the job.

presignedUrlConfig

PresignedUrlConfig

Configuration for pre-signed S3 URLs.

roleArn

string

length- max:2048 min:20

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

long

range- max:3600 min:60

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

JobExecutionsRolloutConfig

Allows you to create a staged rollout of a job.

maximumPerMinute

integer

range- min:1

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

ExponentialRolloutRate

The rate of increase for a job rollout. This parameter allows you to define an exponential rate for a job rollout.

baseRatePerMinute

integer

range- max:1000 min:1

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.

rateIncreaseCriteria

RateIncreaseCriteria

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

range- min:1

The threshold for number of notified things that will initiate the increase in rate of rollout.

numberOfSucceededThings

integer

range- min:1

The threshold for number of succeeded things that will initiate the increase in rate of rollout.

abortConfig

AbortConfig

Configuration for criteria to abort the job.

criteriaList

list

member: AbortCriteria

java class: java.util.List

The list 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.

enum: FAILED | REJECTED | TIMED_OUT | ALL

action

string

The type of abort action to initiate a job abort.

enum: CANCEL

minNumberOfExecutedThings

integer

range- min:1

Minimum number of executed things before evaluating an abort rule.

createdAt

timestamp

The time, in seconds since the epoch, when the job was created.

lastUpdatedAt

timestamp

The time, in seconds since the epoch, when the job was last updated.

completedAt

timestamp

The time, in seconds since the epoch, when the job was completed.

jobProcessDetails

JobProcessDetails

Details about the job process.

processingTargets

list

member: ProcessingTargetName

java class: java.util.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.

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

TimeoutConfig

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

long

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.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

DescribeJobExecution

Describes a job execution.

Synopsis

aws iot describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "jobId": "string", "thingName": "string", "executionNumber": "long" }

cli-input-json fields

Name

Type

Description

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing on which the job execution is running.

executionNumber

long

A string (consisting of the digits "0" through "9" which is used to specify a particular job execution on a particular device.

Output

{ "execution": { "jobId": "string", "status": "string", "forceCanceled": "boolean", "statusDetails": { "detailsMap": { "string": "string" } }, "thingArn": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long", "versionNumber": "long", "approximateSecondsBeforeTimedOut": "long" } }

CLI output fields

Name

Type

Description

execution

JobExecution

Information about the job execution.

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to the job when it was created.

status

string

The status of the job execution (IN_PROGRESS, QUEUED, FAILED, SUCCEEDED, TIMED_OUT, CANCELED, or REJECTED).

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED | REMOVED | CANCELED

forceCanceled

boolean

Will be true if the job execution was canceled with the optional force parameter set to true.

statusDetails

JobExecutionStatusDetails

A collection of name/value pairs that describe the status of the job execution.

detailsMap

map

The job execution status.

thingArn

string

The ARN of the thing on which the job execution is running.

queuedAt

timestamp

The time, in seconds since the epoch, when the job execution was queued.

startedAt

timestamp

The time, in seconds since the epoch, when the job execution started.

lastUpdatedAt

timestamp

The time, in seconds since the epoch, when the job execution was last updated.

executionNumber

long

A string (consisting of the digits "0" through "9") which identifies this particular job execution on this particular device. It can be used in commands which return or update job execution information.

versionNumber

long

The version of the job execution. Job execution versions are incremented each time they are updated by a device.

approximateSecondsBeforeTimedOut

long

The estimated number of seconds that remain before the job execution status will be changed to TIMED_OUT. The timeout interval can be anywhere between 1 minute and 7 days (1 to 10080 minutes). The actual job execution timeout can occur up to 60 seconds later than the estimated duration. This value will not be included if the job execution has reached a terminal status.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

DescribeJobExecution

Gets details of a job execution.

Synopsis

aws iot-jobs-data describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "jobId": "string", "thingName": "string", "includeJobDocument": "boolean", "executionNumber": "long" }

cli-input-json fields

Name

Type

Description

jobId

string

pattern: [a-zA-Z0-9_-]+|^$next

The unique identifier assigned to this job when it was created.

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The thing name associated with the device the job execution is running on.

includeJobDocument

boolean

Optional. When set to true, the response contains the job document. The default is false.

executionNumber

long

Optional. A number that identifies a particular job execution on a particular device. If not specified, the latest job execution is returned.

Output

{ "execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "approximateSecondsBeforeTimedOut": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" } }

CLI output fields

Name

Type

Description

execution

JobExecution

Contains data about a job execution.

jobId

string

length- max:64 min:1

pattern: [a-zA-Z0-9_-]+

The unique identifier you assigned to this job when it was created.

thingName

string

length- max:128 min:1

pattern: [a-zA-Z0-9:_-]+

The name of the thing that is executing the job.

status

string

The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "TIMED_OUT", "REJECTED", or "REMOVED".

enum: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED | REMOVED | CANCELED

statusDetails

map

A collection of name/value pairs that describe the status of the job execution.

queuedAt

long

The time, in seconds since the epoch, when the job execution was enqueued.

startedAt

long

The time, in seconds since the epoch, when the job execution was started.

lastUpdatedAt

long

The time, in seconds since the epoch, when the job execution was last updated.

approximateSecondsBeforeTimedOut

long

The estimated number of seconds that remain before the job execution status will be changed to TIMED_OUT. The actual job execution timeout can occur up to 60 seconds later than the estimated duration.

versionNumber

long

The version of the job execution. Job execution versions are incremented each time they are updated by a device.

executionNumber

long

A number that identifies a particular job execution on a particular device. It can be used later in commands that return or update job execution information.

jobDocument

string

length- max:32768

The content of the job document.

Errors

InvalidRequestException

The contents of the request were invalid.

ResourceNotFoundException

The specified resource does not exist.

ThrottlingException

The rate exceeds the limit.

ServiceUnavailableException

The service is temporarily unavailable.

CertificateValidationException

The certificate is invalid.

TerminalStateException

The job is in a terminal state.

DescribeRoleAlias

Describes a role alias.

Synopsis

aws iot describe-role-alias \ --role-alias <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "roleAlias": "string" }

cli-input-json fields

Name

Type

Description

roleAlias

string

length- max:128 min:1

pattern: [w=,@-]+

The role alias to describe.

Output

{ "roleAliasDescription": { "roleAlias": "string", "roleAliasArn": "string", "roleArn": "string", "owner": "string", "credentialDurationSeconds": "integer", "creationDate": "timestamp", "lastModifiedDate": "timestamp" } }

CLI output fields

Name

Type

Description

roleAliasDescription

RoleAliasDescription

The role alias description.

roleAlias

string

length- max:128 min:1

pattern: [w=,@-]+

The role alias.

roleAliasArn

string

The ARN of the role alias.

roleArn

string

length- max:2048 min:20

The role ARN.

owner

string

length- max:12 min:12

pattern: [0-9]+

The role alias owner.

credentialDurationSeconds

integer

range- max:3600 min:900

The number of seconds for which the credential is valid.

creationDate

timestamp

The UNIX timestamp of when the role alias was created.

lastModifiedDate

timestamp

The UNIX timestamp of when the role alias was last modified.

Errors

InvalidRequestException

The contents of the request were invalid.

ThrottlingException

The rate exceeds the limit.

UnauthorizedException

You are not authorized to perform this operation.

ServiceUnavailableException

The service is temporarily unavailable.

InternalFailureException

An unexpected error has occurred.

ResourceNotFoundException

The specified resource does not exist.

DescribeScheduledAudit

Gets information about a scheduled audit.

Synopsis

aws iot describe-scheduled-audit \ --scheduled-audit-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format

{ "scheduledAuditName": "string" }

cli-input-json fields

Name

Type

Description

scheduledAuditName

string

length- max:128 min:1

pattern: [a-zA-Z0-9_-]+

The name of the scheduled audit whose information you want to get.

Output

{ "frequency": "string", "dayOfMonth": "string", "dayOfWeek": "string", "targetCheckNames": [ "string" ], "scheduledAuditName": "string", "scheduledAuditArn": "string" }

CLI output fields

Name

Type

Description

frequency