Creates a dynamic update batch.

Limits

  • If you do not specify that an update package does not need to be verified when you call the CreateOTAFirmware operation, you must ensure that the update package is verified before you call the CreateOTADynamicUpgradeJob operation to create an update batch. For more information about how to create a task to verify an update package, see CreateOTAVerifyJob.
  • Each device can be in the pending or updating state in only one update batch. If you initiate another update task for a device that is in the pending or updating state, the update task fails.
  • Each update package can have only one dynamic update task that is in the running state.
  • If a device is included in dynamic update policies of different update packages, the device performs the latest dynamic update.
  • After a dynamic update batch is created, IoT Platform automatically creates the related dynamic update policy. You can call the CancelOTAStrategyByJob operation to cancel a dynamic update policy.
  • Each Alibaba Cloud account can run a maximum of 20 queries per second (QPS).
    Note RAM users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateOTADynamicUpgradeJob

The operation that you want to perform. Set the value to CreateOTADynamicUpgradeJob.
FirmwareId String Yes nx3xxVvFdwvn6dim50PY03****

The ID of the update package.

An update package ID is returned when you call the CreateOTAFirmware operation to create the update package.

You can call the ListOTAFirmware operation and view the update package ID in the response.

ProductKey String Yes a1Le6d0****

The ProductKey of the product to which the update package belongs.

Tag.N.Key String Yes key1

The key of the update batch tag. The key can contain letters, digits, and periods (.). The name must be 1 to 30 characters in length. An update batch tag is sent to devices when IoT Platform pushes an update notification to these devices.

Note Update batch tags are optional. If you want to specify a tag, you must specify the Tag.N.Value parameter and the Tag.N.Key parameter in pair.
Tag.N.Value String Yes value1

The value of the update batch tag. The value must be 1 to 1,024 characters in length.

Note Update batch tags are optional. If you want to specify a tag, you must specify the Tag.N.Value parameter and the Tag.N.Key parameter in pair. The total tag keys and values cannot exceed 4,096 characters in length.
IotInstanceId String No iot-cn-0pp1n8t****

The ID of the instance. This parameter is not required for the public instance but required for Enterprise Edition instances.

SrcVersion.N RepeatList No V1.0.1

The list of firmware versions to be updated.

Note
  • If you use a differential update package to perform dynamic update tasks, the value of this parameter must be the same as the value of the SrcVersion parameter.
  • You can call the QueryDeviceDetail operation and view the FirmwareVersion parameter in the response.
  • The version numbers must be unique in the list.
  • You can specify a maximum of 10 version numbers.
RetryInterval Integer No 60

The automatic retry interval if a device fails to be updated. Unit: minutes. Valid values:

  • 0: An automatic retry is immediately performed.
  • 10: An automatic retry is performed after 10 minutes.
  • 30: An automatic retry is performed after 30 minutes.
  • 60: An automatic retry is performed after 60 minutes (1 hour).
  • 1440: An automatic retry is performed after 1,440 minutes (24 hours).

If you do not specify this parameter, no retry is performed.
RetryCount Integer No 1

The number of automatic retries.

You must specify this parameter if you specify the RetryInterval parameter.

Valid values:

  • 1: retries once
  • 2: retries twice
  • 5: retries five times
TimeoutInMinutes Integer No 1440

The timeout period of the update. Unit: minutes. Valid values: 1 to 1440.

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

Note
  • The timeout period starts from the time when the specified device submits the update progress for the first time.
  • If an update fails due to timeout, no retry is triggered.
MaximumPerMinute Integer No 1000

The maximum number of devices to which the download URL of the update package is pushed per minute. Valid values: 10 to 1000.

Default value: 1000.
OverwriteMode Integer No 2

Specifies whether to overwrite the previous update task. Valid values:

  • 1: The previous update task is not overwritten. If a device already has an update task, the previous update task is implemented.
  • 2: The previous update task is overwritten. Only the current update task is implemented.

If you do not specify this parameter, the previous update task is not overwritten.

Note The update task that is in progress is not overwritten.
DynamicMode Integer No 1

The mode of dynamic update. Valid values:

  • 1: constantly updates the devices that meet the conditions.
  • 2: updates only the devices that subsequently submit the latest firmware versions.

Default value: 1.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

The error code returned if the call fails. For more information, see Error codes.

Data Struct

The upgrade batch information returned if the call is successful. For more information, see Data.

JobId String XUbmsMHmkqv0PiAG****010001

The ID of the update batch.
UtcCreate String 2019-05-10T02:18:53.000Z

The time when the update batch was created. The time is displayed in UTC.
ErrorMessage String A system exception occurred.

The error message returned if the call fails.
RequestId String 9F41D14E-CB5F-4CCE-939C-057F39E688F5

The ID of the request.
Success Boolean true

Indicates whether the call was successful. true indicates that the call was successful and false indicates that the call failed.

Examples

Sample requests

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

Sample success responses

XML format 

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

JSON format 

{
  "Data": {
    "JobId": "XUbmsMHmkqv0PiAG****010001",
    "UtcCreate": "2019-05-10T02:18:53.000Z"
  },
  "RequestId": "9F41D14E-CB5F-4CCE-939C-057F39E688F5",
  "Success": true
}

Error codes

For a list of error codes, visit the API Error Center.