Creates a static update job.

Limits

  • The firmware must be verified before you call this operation. For more information about how to create a firmware verification job, see CreateOTAVerifyJob.
  • You can initiate firmware update tasks for up to 200 devices in a single call.
  • Do not initiate an update task for a device that is pending or updating in an update job.
  • You can initiate multiple static update jobs for a single firmware.
  • 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 CreateOTAStaticUpgradeJob.
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.

TargetSelection String Yes The update scope.
  • ALL: push the firmware to all the devices that meet the conditions.
  • SPECIFIC: push the firmware to specified devices.
  • GRAY: phased update.
TargetDeviceNames List<String> No The names of the devices to perform update.
Note
  • This parameter is required when TargetSelection=SPECIFIC and you cannot specify the parameter SrcVersions.
  • When you perform specific updates by using differential firmware, the current firmware version of the device to be updated must be the same as the SrcVersion parameter of the differential firmware.

    You can call QueryDeviceDetail to view the FirmwareVersion.

  • The devices in the list must belong to the same product as the firmware.
  • The list cannot contain duplicate device names.
  • The list can contain up to 200 device names.
SrcVersions List<String> No The list of firmware versions to be updated.

You can call QueryDeviceDetail to view the parameter FirmwareVersion.

Note
  • when TargetSelection=ALL or TargetSelection=GRAY, this parameter is required and you cannot specify the TargetDeviceNames parameter.
  • You cannot specify this parameter when you initiate a specific update (TargetSelection=SPECIFIC).
  • When the firmware is 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.
ScheduleTime Long No The time to push the firmware update notification to the devices.

The scheduled time range must be 5 minutes later than the current time and within 7 days. The value must be a 13-bit timestamp, for example, 1577808000000.

If you do not specify this parameter, the update starts immediately.
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.
GrayPercent String No The phase 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.

This parameter is required when the update is phased (TargetSelection=GRAY).

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

  • JSON format 
    {
  "Data": {
    "JobId": "wahVIzGkCMuAUE2gDERM02****",
    "UtcCreate": "2019-11-04T06:22:19.566Z"
  },
  "RequestId": "29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1",
  "Success": true
}
  • XML format 
    <? xml version="1.0" encoding="utf-8"? >
<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>