Creates a static 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 CreateOTAStaticUpgradeJob operation to create an update batch. For more information about how to create a task to verify an update package, see CreateOTAVerifyJob.
- You can initiate update tasks for a maximum of 200 devices in each call. If you use a device list file, you can initiate update tasks for a maximum of 10,000 devices. However, you must call the GenerateDeviceNameListURL operation to generate a URL for the device list file. Then, you can perform the operations as prompted to upload the device list file.
- When you initiate update tasks for multiple devices, the devices that already have the destination firmware versions are skipped.
- Each device can be in the pending or updating state in only one update batch. If you initiate an update task for a device that is in the pending or updating state, the update task fails.
- You can create multiple static update batches by using a single update package.
-
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
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | CreateOTAStaticUpgradeJob |
The operation that you want to perform. Set the value to CreateOTAStaticUpgradeJob. |
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.
|
TargetSelection | String | Yes | ALL |
The scope of the update. Valid values:
|
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
|
ScheduleTime | Long | No | 1577808000000 |
The time to start the OTA update. The scheduled time ranges from 5 minutes to seven days later than the current time. The value must be a 13-digit timestamp. If you do not specify this parameter, the update immediately starts. |
RetryInterval | Integer | No | 60 |
The automatic retry interval if a device fails to be updated. Unit: minutes. Valid values:
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:
|
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
|
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 |
GrayPercent | String | No | 33.33 |
The ratio of the phased update. The value is a percentage in the string format. It can be up to three decimal places. The calculated number of devices is rounded down to the nearest integer. You must specify at least one device for a phased update. For example, if you set the phased update ratio to 33.33 for 100 devices, the number of devices to be updated is 33. You must specify this parameter if you set the TargetSelection parameter to |
TargetDeviceName.N | RepeatList | No | deviceName1 |
The list of device names. Note
|
ScheduleFinishTime | Long | No | 1577909000000 |
The time to end the update. The end time must be 1 hour to 30 days later than the start time that is specified by the ScheduleTime parameter. The value must be a 13-digit timestamp. If you do not specify this parameter, the update is not forcibly ended. |
OverwriteMode | Integer | No | 1 |
Specifies whether to overwrite the previous update task. Valid values:
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.
|
DnListFileUrl | String | No | https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin |
The URL of the device list file that is used to perform a specific update. Note
|
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 | MissingFirmwareId |
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 | wahVIzGkCMuAUE2gDERM02**** |
The ID of the update batch. |
UtcCreate | String | 2019-11-04T06:22:19.566Z |
The time when the update batch was created. The time is displayed in UTC. |
ErrorMessage | String | FirmwareId is mandatory for this action. |
The error message returned if the call fails. |
RequestId | String | 29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1 |
The ID of the request. |
Success | Boolean | true |
Indicates whether the call was successful.
|
Examples
Sample requests
https://iot.cn-shanghai.aliyuncs.com/?Action=CreateOTAStaticUpgradeJob
&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
XML
format
<CreateOTAStaticUpgradeJobResponse>
<Data>
<JobId>wahVIzGkCMuAUE2gDERM02****</JobId>
<UtcCreate>2019-11-04T06:22:19.566Z</UtcCreate>
</Data>
<RequestId>29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1</RequestId>
<Success>true</Success>
</CreateOTAStaticUpgradeJobResponse>
JSON
format
{
"Data": {
"JobId": "wahVIzGkCMuAUE2gDERM02****",
"UtcCreate": "2019-11-04T06:22:19.566Z"
},
"RequestId": "29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1",
"Success": true
}
Error codes
For a list of error codes, visit the API Error Center.