Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

CreateOTAUpdate

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

Requires permission to access the CreateOTAUpdate action.

Request Syntax


POST /otaUpdates/otaUpdateId HTTP/1.1
Content-type: application/json

{
   "additionalParameters": { 
      "string" : "string" 
   },
   "awsJobAbortConfig": { 
      "abortCriteriaList": [ 
         { 
            "action": "string",
            "failureType": "string",
            "minNumberOfExecutedThings": number,
            "thresholdPercentage": number
         }
      ]
   },
   "awsJobExecutionsRolloutConfig": { 
      "exponentialRate": { 
         "baseRatePerMinute": number,
         "incrementFactor": number,
         "rateIncreaseCriteria": { 
            "numberOfNotifiedThings": number,
            "numberOfSucceededThings": number
         }
      },
      "maximumPerMinute": number
   },
   "awsJobPresignedUrlConfig": { 
      "expiresInSec": number
   },
   "awsJobTimeoutConfig": { 
      "inProgressTimeoutInMinutes": number
   },
   "description": "string",
   "files": [ 
      { 
         "attributes": { 
            "string" : "string" 
         },
         "codeSigning": { 
            "awsSignerJobId": "string",
            "customCodeSigning": { 
               "certificateChain": { 
                  "certificateName": "string",
                  "inlineDocument": "string"
               },
               "hashAlgorithm": "string",
               "signature": { 
                  "inlineDocument": blob
               },
               "signatureAlgorithm": "string"
            },
            "startSigningJobParameter": { 
               "destination": { 
                  "s3Destination": { 
                     "bucket": "string",
                     "prefix": "string"
                  }
               },
               "signingProfileName": "string",
               "signingProfileParameter": { 
                  "certificateArn": "string",
                  "certificatePathOnDevice": "string",
                  "platform": "string"
               }
            }
         },
         "fileLocation": { 
            "s3Location": { 
               "bucket": "string",
               "key": "string",
               "version": "string"
            },
            "stream": { 
               "fileId": number,
               "streamId": "string"
            }
         },
         "fileName": "string",
         "fileType": number,
         "fileVersion": "string"
      }
   ],
   "protocols": [ "string" ],
   "roleArn": "string",
   "tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ],
   "targets": [ "string" ],
   "targetSelection": "string"
}

URI Request Parameters

The request uses the following URI parameters.

otaUpdateId

The ID of the OTA update to be created.

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

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

Required: Yes

Request Body

The request accepts the following data in JSON format.

additionalParameters

A list of additional OTA update parameters, which are name-value pairs. They won't be sent to devices as a part of the Job document.

Type: String to string map

Value Length Constraints: Minimum length of 0. Maximum length of 4096.

Value Pattern: [\s\S]*

Required: No

awsJobAbortConfig

The criteria that determine when and how a job abort takes place.

Type: AwsJobAbortConfig object

Required: No

awsJobExecutionsRolloutConfig

Configuration for the rollout of OTA updates.

Type: AwsJobExecutionsRolloutConfig object

Required: No

awsJobPresignedUrlConfig

Configuration information for pre-signed URLs.

Type: AwsJobPresignedUrlConfig object

Required: No

awsJobTimeoutConfig

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.

Type: AwsJobTimeoutConfig object

Required: No

description

The description of the OTA update.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No

files

The files to be streamed by the OTA update.

Type: Array of OTAUpdateFile objects

Array Members: Minimum number of 1 item.

Required: Yes

protocols

The protocol used to transfer the OTA update image. Valid values are [HTTP], [MQTT], [HTTP, MQTT]. When both HTTP and MQTT are specified, the target device can choose the protocol.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 2 items.

Valid Values: MQTT | HTTP

Required: No

roleArn

The IAM role that grants AWS IoT Core access to the Amazon S3, AWS IoT jobs and AWS Code Signing resources to create an OTA update job.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes

tags

Metadata which can be used to manage updates.

Type: Array of Tag objects

Required: No

targets

The devices targeted to receive OTA updates.

Type: Array of strings

Array Members: Minimum number of 1 item.

Required: Yes

targetSelection

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.

Type: String

Valid Values: CONTINUOUS | SNAPSHOT

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "awsIotJobArn": "string",
   "awsIotJobId": "string",
   "otaUpdateArn": "string",
   "otaUpdateId": "string",
   "otaUpdateStatus": "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.

awsIotJobArn

The AWS IoT job ARN associated with the OTA update.

Type: String

awsIotJobId

The AWS IoT job ID associated with the OTA update.

Type: String

otaUpdateArn

The OTA update ARN.

Type: String

otaUpdateId

The OTA update ID.

Type: String

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

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

otaUpdateStatus

The OTA update status.

Type: String

Errors

InternalFailureException

An unexpected error has occurred.

message: The message for the exception.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

message: The message for the exception.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

message: The message for the exception.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

message: The message for the exception.
resourceArn: The ARN of the resource that caused the exception.
resourceId: The ID of the resource that caused the exception.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

message: The message for the exception.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

message: The message for the exception.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

message: The message for the exception.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

message: The message for the exception.

HTTP Status Code: 401