Creates a dynamic update batch.
Usage notes
- You can specify that an update package does not need to be verified when you call the CreateOTAFirmware operation. Otherwise, you must make sure 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 only in one update job. 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 job is created, the system automatically creates the corresponding dynamic update policy. You can call the CancelOTAStrategyByJob operation to cancel a dynamic update policy.
- Only Enterprise Edition instances and new public instances in the China (Shanghai) region support creating dynamic update batches for dynamic groups.
- Only devices in the China (Shanghai), China (Beijing), and China (Shenzhen) regions can download update packages by using the MQTT protocol.
Limits
Each Alibaba Cloud account can run a maximum of 20 queries per second (QPS).
Debugging
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 must be 1 to 30 characters in length and can contain letters, digits, and periods (.). You can add up to 10 tags for each update batch. The tags of an update batch are sent to devices when IoT Platform pushes update notifications to these devices. Note Update batch tags are optional. If you want to specify a tag, you must specify the
Tag.N.Value and Tag.N.Key parameters 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. You can add up to 10 tags for each update batch. The total tag keys and values cannot exceed 4,096 characters in length. Note Update batch tags are optional. If you want to specify a tag, you must specify the
Tag.N.Value and Tag.N.Key parameters in pair.
|
IotInstanceId | String | No | iot-cn-0pp1n8t**** |
The ID of the instance. Notice
|
SrcVersion.N | RepeatList | No | V1.0.1 |
The list of firmware versions to be updated.
Note
|
RetryInterval | Integer | No | 60 |
The automatic retry interval if a device fails to be updated. Unit: minutes. Valid values:
Notice The value of the RetryInterval parameter must be less than the value of the TimeoutInMinutes parameter. Examples:
If the value of the RetryInterval parameter is set to 1440, we recommend that you do not specify the TimeoutInMinutes parameter. If an update times out, no retry is performed. If you do not specify this parameter, no retry is performed. |
RetryCount | Integer | No | 1 |
The number of automatic retries. If you specify the RetryInterval parameter, you must specify this parameter. Valid values:
|
TimeoutInMinutes | Integer | No | 1440 |
The timeout period of the update. If the device is not updated within the specified period, a timeout error occurs. Unit: minutes. Valid values: 1 to 1440. Note
If you do not specify this parameter, timeout errors do not occur. |
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 10000. Default value: 10000. |
OverwriteMode | Integer | No | 2 |
Specifies whether to overwrite the previous update task. Valid values:
Note The update task that is in progress is not overwritten.
|
DynamicMode | Integer | No | 1 |
The mode of dynamic update. Valid values:
|
NeedPush | Boolean | No | true |
Specifies whether to automatically push update tasks from IoT Platform to devices.
|
NeedConfirm | Boolean | No | false |
Specifies whether to control the update by using a mobile app. You must develop the mobile app as needed.
|
GroupId | String | No | IwOwQj7DJ*** |
The ID of the group.
You can call the QueryDeviceGroupList operation to query the GroupId parameter. |
GroupType | String | No | LINK_PLATFORM_DYNAMIC |
The type of the group. Valid value: LINK_PLATFORM_DYNAMIC.
|
DownloadProtocol | String | No | HTTPS |
The download protocol of the update package. Valid values: HTTPS and MQTT. Default value: HTTPS. After the device receives the update package information pushed by IoT Platform, this protocol is used to download the update package. Notice If you need to download the update package over MQTT, take note of the following items:
|
MultiModuleMode | Boolean | No | false |
Specifies whether the device supports simultaneous updates of multiple modules.
Notice
For more information, see Overview. |
In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information, see Common request 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 update batch information returned if the call is successful. For more information, see Data. |
|
JobId | String | XUbmsMHmkqv0PiAG****010001 |
The ID of the update batch. This parameter is used to uniquely identify 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.
|
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.