See Also - AWS IoT

For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go

• AWS SDK for Java V2

• AWS SDK for JavaScript

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3

AddThingToBillingGroup

Service: AWS IoT

Adds a thing to a billing group.

Requires permission to access the AddThingToBillingGroup action.

Request Syntax

PUT /billing-groups/addThingToBillingGroup HTTP/1.1 Content-type: application/json

{

"billingGroupArn": "string", "billingGroupName": "string", "thingArn": "string",

"thingName": "string"

}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

billingGroupArn (p. 17)

The ARN of the billing group.

Type: String Required: No

billingGroupName (p. 17)

The name of the billing group.

NoteThis call is asynchronous. It might take several seconds for the detachment to propagate.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

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

Required: No thingArn (p. 17)

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

Type: String Required: No thingName (p. 17)

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

AddThingToBillingGroup

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

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

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500 InvalidRequestException

The request is not valid.

HTTP Status Code: 400 ResourceNotFoundException

The speciﬁed resource does not exist.

HTTP Status Code: 404 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

Request Syntax

PUT /thing-groups/addThingToThingGroup HTTP/1.1 Content-type: application/json

{ "overrideDynamicGroups": boolean, "thingArn": "string",

"thingGroupArn": "string", "thingGroupName": "string", "thingName": "string"

}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

overrideDynamicGroups (p. 20)

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.

Type: Boolean Required: No thingArn (p. 20)

The ARN of the thing to add to a group.

Type: String Required: No thingGroupArn (p. 20)

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

Type: String Required: No thingGroupName (p. 20)

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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

AddThingToThingGroup

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

Required: No thingName (p. 20)

The name of the thing to add to a group.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

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

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500 InvalidRequestException

The request is not valid.

HTTP Status Code: 400 ResourceNotFoundException

The speciﬁed resource does not exist.

HTTP Status Code: 404 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

Request Syntax

POST /jobs/jobId/targets?namespaceId=namespaceId HTTP/1.1 Content-type: application/json

{

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

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 23)

The unique identiﬁer you assigned to this job when it was created.

Length Constraints: Minimum length of 1. Maximum length of 64.

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

Required: Yes namespaceId (p. 23)

The namespace used to indicate that a job is a customer-managed job.

When you specify a value for this parameter, AWS IoT Core sends jobs notiﬁcations to MQTT topics that contain the value in the following format.

$aws/things/THING_NAME/jobs/JOB_ID/notify-namespace-NAMESPACE_ID/

Note

The namespaceId feature is in public preview.

Length Constraints: Minimum length of 1. Maximum length of 64.

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

Request Body

The request accepts the following data in JSON format.

comment (p. 23)

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

AssociateTargetsWithJob

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No targets (p. 23)

A list of thing group ARNs that deﬁne the targets of the job.

Type: Array of strings

Array Members: Minimum number of 1 item.

Length Constraints: Maximum length of 2048.

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "description": "string", "jobArn": "string", "jobId": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

description (p. 24)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

jobArn (p. 24)

An ARN identifying the job.

Type: String jobId (p. 24)

The unique identiﬁer you assigned to this job when it was created.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

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

AssociateTargetsWithJob

Errors

InvalidRequestException The request is not valid.

HTTP Status Code: 400 LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410 ResourceNotFoundException

The speciﬁed resource does not exist.

HTTP Status Code: 404 ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

Request Syntax

PUT /target-policies/policyName HTTP/1.1 Content-type: application/json

{

"target": "string"

}

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 26)

The name of the policy to attach.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\w+=,.@-]+

Required: Yes

Request Body

The request accepts the following data in JSON format.

target (p. 26)

The identity to which the policy is attached. For example, a thing group or a certiﬁcate.

Type: String Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

AttachPolicy

HTTP Status Code: 500 InvalidRequestException

The request is not valid.

HTTP Status Code: 400 LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410 ResourceNotFoundException

The speciﬁed resource does not exist.

HTTP Status Code: 404 ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400 UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

Request Syntax

PUT /principal-policies/policyName HTTP/1.1 x-amzn-iot-principal: principal

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 28) The policy name.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\w+=,.@-]+

Required: Yes principal (p. 28)

The principal, which can be a certiﬁcate ARN (as returned from the CreateCertiﬁcate operation) or an Amazon Cognito ID.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

AttachPrincipalPolicy

InvalidRequestException The request is not valid.

HTTP Status Code: 400 LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410 ResourceNotFoundException

The speciﬁed resource does not exist.

HTTP Status Code: 404 ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400 UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

Request Syntax

PUT /security-profiles/securityProfileName/targets?

securityProfileTargetArn=securityProfileTargetArn HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

securityProﬁleName (p. 30)

The security proﬁle that is attached.

Length Constraints: Minimum length of 1. Maximum length of 128.

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

Required: Yes

securityProﬁleTargetArn (p. 30)

The ARN of the target (thing group) to which the security proﬁle is attached.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500 InvalidRequestException

The request is not valid.

AttachSecurityProﬁle

HTTP Status Code: 400 LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410 ResourceNotFoundException

The speciﬁed resource does not exist.

HTTP Status Code: 404 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400 VersionConﬂictException

An exception thrown when the version of an entity speciﬁed with the expectedVersion parameter does not match the latest version in the system.

HTTP Status Code: 409

Request Syntax

PUT /things/thingName/principals HTTP/1.1 x-amzn-principal: principal

URI Request Parameters

The request uses the following URI parameters.

principal (p. 32)

The principal, which can be a certiﬁcate ARN (as returned from the CreateCertiﬁcate operation) or an Amazon Cognito ID.

Required: Yes thingName (p. 32)

The name of the thing.

Length Constraints: Minimum length of 1. Maximum length of 128.

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

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500 InvalidRequestException

The request is not valid.

AttachThingPrincipal

HTTP Status Code: 400 ResourceNotFoundException

The speciﬁed resource does not exist.

HTTP Status Code: 404 ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400 UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

Request Syntax

PUT /audit/mitigationactions/tasks/taskId/cancel HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 34)

The unique identiﬁer for the task that you want to cancel.

Length Constraints: Minimum length of 1. Maximum length of 128.

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

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500 InvalidRequestException

The request is not valid.

HTTP Status Code: 400 ResourceNotFoundException

The speciﬁed resource does not exist.

CancelAuditMitigationActionsTask

HTTP Status Code: 404 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

Request Syntax

PUT /audit/tasks/taskId/cancel HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 36)

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

Length Constraints: Minimum length of 1. Maximum length of 40.

Pattern: [a-zA-Z0-9\-]+

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500 InvalidRequestException

The request is not valid.

HTTP Status Code: 400 ResourceNotFoundException

The speciﬁed resource does not exist.

CancelAuditTask

HTTP Status Code: 404 ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400