Creates a static 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 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.

Limits

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 a sample code of the operation for different SDKs.

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 must be 1 to 30 characters in length and can contain letters, digits, and periods (.). 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 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.

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. The total tag keys and values cannot exceed 4,096 characters in length.
TargetSelection String Yes ALL

The scope of the update. Valid values:

  • ALL: updates all devices.
  • SPECIFIC: updates specified devices.
  • GRAY: performs a phased update.
IotInstanceId String No iot-cn-0pp1n8t****

The ID of the instance.

You do not need to specify this parameter.

SrcVersion.N RepeatList No V1.0.1

The list of firmware versions to be updated.

Note
  • This parameter is available if you set the TargetSelection parameter to ALL or GRAY.
  • If you use a differential update package to perform a complete update or phased update, the value of this parameter must be the same as the value of the SrcVersion parameter.
  • This parameter is unavailable if you set the TargetSelection parameter to SPECIFIC.
  • 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.
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-bit 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:

  • 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).
Notice The value of the RetryInterval parameter must be less than the value of the TimeoutInMinutes parameter. Examples:
  • If the value of the TimeoutInMinutes parameter is set to 60, the maximum value of the RetryInterval parameter is 30.
  • If the value of the TimeoutInMinutes parameter is set to 1440, the maximum value of the RetryInterval parameter is 60.

If the value of the TimeoutInMinutes 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.

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. If the device is not updated within the specified period, a timeout error occurs. Unit: minutes. Valid values: 1 to 1440.

Note
  • The timeout period starts from the time when the specified device submits the update progress for the first time. During the update, the update package may be repeatedly pushed to the specified device because the device goes online and offline multiple times. However, the start time of the update period does not change.
  • If an update fails due to timeout, no retry is triggered.

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

TargetDeviceName.N RepeatList No deviceName1

The list of device names.

Note
  • If you set the TargetSelection parameter to SPECIFIC, you must specify this parameter or the DnListFileUrl parameter. You cannot specify the two parameters at the same time.
  • If you use a differential update package to perform a specific update, the OTA module version of the device to be updated 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 devices in the list must belong to the same product as the update package.
  • The device names must be unique in the list.
  • The list can contain up to 200 device names.
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:

  • 1: The previous update task is not overwritten. If a device already has an update task, the previous update task is implemented. This value is used by default.
  • 2: The previous update task is overwritten. Only the current task is implemented.
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
  • If you set the TargetSelection parameter to SPECIFIC, you must specify this parameter or the TargetDeviceName.N parameter. You cannot specify the two parameters at the same time.
  • You can call the GenerateDeviceNameListURL operation to generate a file URL. Then, you can perform the operations as prompted to upload the device list file.
  • During a full update, the devices that have been updated are skipped.
  • During a delta update, the devices that have been updated and the devices whose initial version numbers are different from the update package are skipped.
NeedPush Boolean No true

Specifies whether to automatically push update tasks from IoT Platform to devices.

  • true: yes. This value is used by default. After an update batch is created, IoT Platform automatically pushes update tasks to the specified online devices.

    In this case, a device can still initiate a request to obtain the information about the OTA update task from IoT Platform.

  • false: no. A device must initiate a request to obtain the information about the OTA update task from IoT Platform.
NeedConfirm Boolean No false

Specifies whether to control the update by using a mobile app. You must develop the mobile app as needed.

  • false: no. A device obtains the information about the OTA update task based on the NeedPush parameter. This value is used by default.
  • true: yes. To perform an OTA update on a device, you must confirm the update by using your mobile app. Then, the device can obtain the information about the OTA update task based on the NeedPush parameter.

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

  • true: The call was successful.
  • false: The call failed.

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 response

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.