Creates a dynamic update job.

Limits

  • The firmware must be verified before you call this operation. For more information about how to create a firmware verification task, see CreateOTAVerifyJob.
  • Do not initiate an update task for a device that is pending or updating in an update job.
  • Each set of firmware can have at most one dynamic update job.
  • If a device is included in multiple dynamic update policies of different firmware, the device performs the latest created update task.
  • After a dynamic update job is created, the system automatically creates the corresponding dynamic update policy. You can call CancelOTAStrategyByJob to cancel a dynamic update policy.
  • The maximum number of queries per second (QPS) for a single Alibaba Cloud account to call this operation is 5. The quota is shared between the Alibaba Cloud account and RAM users.

Request parameters

Parameter Type Required Description
Action String Yes The operation that you want to perform. Set the value to CreateOTADynamicUpgradeJob.
ProductKey String Yes The key of the product to which the firmware belongs.
FirmwareId String Yes The firmware ID. It is the unique identifier of the firmware.

The firmware ID is a response parameter that is returned by the CreateOTAFirmware operation.

You can call the ListOTAFirmware operation to check the response parameters for the firmware ID.

SrcVersions List<String> No The list of firmware versions to be updated.

You can call QueryDeviceDetail to view the firmware version FirmwareVersion.

Note
  • When a dynamic update job is initiated by using differential firmware, this parameter value must be the same as the version (SrcVersion) of the differential firmware.
  • The list cannot contain duplicate versions.
  • A maximum of 10 versions can be specified.
RetryInterval Integer No The automatic retry interval after a device fails to be updated. Unit: minutes. Valid values:
  • 0: retries immediately.
  • 10: retries after 10 minutes.
  • 30: retries after 30 minutes.
  • 60: retries after 60 minutes (1 hour).
  • 1440: retries after 1,440 minutes (24 hours).

If you do not specify this parameter, no retry is performed.
RetryCount Integer No The number of automatic retries.

If you specify the RetryInterval parameter, you must specify this parameter.

Valid values:

  • 1: retries once.
  • 2: retries twice.
  • 5: retries five times.
MaximumPerMinute Integer No The maximum number of devices to which the download URL of the firmware is pushed per minute. Valid values: 0 to 1000.

If you do not specify this parameter, the default value 1000 is used.
TimeoutInMinutes Integer No The timeout period for a device update. Unit: minutes. Valid values: 1 to 1,440.

If an update is not completed after the specified timeout period, the update fails.

Note
  • The period starts from the time when the specified device reports the update progress for the first time.
  • If an update fails after the timeout period is exceeded, no retry is triggered.
IotInstanceId String No The ID of your IoT Platform instance. This parameter is not required for public instances. However, the parameter is required for the instances that you have purchased.
Common request parameters N/A Yes For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Description
RequestId String The globally unique ID that is generated by Alibaba Cloud for the request.
Success Boolean Indicates whether the call is successful. true indicates that the call was successful. false indicates that the call failed.
ErrorMessage String The error message returned if the call fails.
Code String The error code returned if the call fails. For more information about error codes, see Error codes.
Data Data The job information returned when the call is successful. For more information, see the following table.
Table 1. Data
Parameter Type Description
JobId String The ID of the update job. It is the unique identifier of the update job.
UtcCreate String The time when the update job was created in UTC.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=CreateOTADynamicUpgradeJob
&FirmwareId=nx3xxVvFdwvn6dim50PY03****
&MaximumPerMinute=1000
&ProductKey=a1Le6d0****
&RetryCount=1
&RetryInterval=60
&TargetSelection=ALL
&TimeoutInMinutes=1440
&SrcVersion.1=V1.0.1
&Common request parameters

Sample success responses

  • JSON format 
    {
  "Data": {
    "JobId": "XUbmsMHmkqv0PiAG****010001",
    "UtcCreate": "2019-05-10T02:18:53.000Z"
  },
  "RequestId": "9F41D14E-CB5F-4CCE-939C-057F39E688F5",
  "Success": true
}
  • XML format 
    <? xml version="1.0" encoding="utf-8"? >
<CreateOTADynamicUpgradeJobResponse>
 <Data>
   <JobId>wahVIzGkCMuAUE2gDERM02****</JobId>
   <UtcCreate>2019-11-04T06:22:19.566Z</UtcCreate>
 </Data>
 <RequestId>29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1</RequestId>
 <Success>true</Success>
</CreateOTADynamicUpgradeJobResponse>