CreateOTADynamicUpgradeJob - IoT Platform

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 status only in one update task. If you initiate another update task for a device that is in the pending or updating status, 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 devices in the China (Shanghai) region can download update packages over the MQTT protocol.

QPS limits

Each Alibaba Cloud account can run a maximum of 20 queries per second (QPS).

Note

The Resource Access Management (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 also call the ListOTAFirmware operation to obtain the ID.
ProductKey	String	Yes	a1Le6d0****	The ProductKey of the product to which the update package belongs. A ProductKey is the unique identifier of a product in IoT Platform. You can view the information about all products within the current Alibaba Cloud account in the IoT Platform console or by calling the QueryProductList operation.
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 length of the tag keys and tag values of all update batches 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. You can view the ID of an instance on the Overview page in the IoT Platform console. Important If your instance has an ID, you must specify the ID for this parameter. If you do not specify the instance ID, the call fails. If no ID is generated for your instance, you do not need to configure this parameter. For more information, see Overview.
SrcVersion.N	RepeatList	No	V1.0.1	The list of firmware versions to be updated. If you specify this parameter, do not specify the GroupId and GroupType parameters. If you do not specify this parameter, you must specify the GroupId and GroupType parameters. Note If you use differential update packages to perform dynamic update tasks based on versions, the value of this parameter must be the same as the value of SrcVersion. If you use differential update packages to perform dynamic update tasks on dynamic groups, you do not need to specify this 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 30 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). Important 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 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: 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. The start time of the update period remains unchanged. 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 10000. Default value: 10000.
OverwriteMode	Integer	No	2	Specifies whether to overwrite the previous update task. Default value: 1. 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. In this case, you cannot set MultiModuleMode to true. Note The update task that is in progress is not overwritten.
DynamicMode	Integer	No	1	The mode of dynamic update. Default value: 1. Valid values: 1: constantly updates the devices that meet the conditions. 2: updates only the devices that subsequently submit the latest firmware versions.
NeedPush	Boolean	No	true	Specifies whether to automatically push update tasks from IoT Platform to devices. Default value: true. Valid values: true: 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 over-the-air (OTA) update task from IoT Platform. false: 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. Default value: false. Valid values: false: A device obtains the information about the OTA update task based on the NeedPush parameter. true: 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.
GroupId	String	No	IwOwQj7DJ***	The ID of the group. If you specify this parameter, you must also specify the GroupType parameter. In this case, do not specify the SrcVersion.N parameter. If you do not specify this parameter, you do not need to specify the GroupType parameter. In this case, you must specify the SrcVersion.N parameter. 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. If you specify this parameter, you must also specify the GroupId parameter. In this case, do not specify the SrcVersion.N parameter. If you do not specify this parameter, you do not need to specify the GroupId parameter. In this case, you must specify the SrcVersion.N parameter.
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. Important If you need to download the update package over MQTT, take note of the following items: Your service must be deployed in the China (Shanghai) region. The OTA update package can contain only one file, and the size of the file cannot exceed 16 MB. You must use the latest version of Link SDK for C to develop the device features to perform OTA updates and download files over MQTT. For more information, see Sample code.
MultiModuleMode	Boolean	No	false	Specifies whether the device supports simultaneous updates of multiple modules. Default value: false. Valid values: false true: In this case, do not set OverwriteMode to 2. The update tasks for the same module are overwritten. The update tasks that are in progress are not overwritten. The update tasks of the modules do not affect each other. Important Only Enterprise Edition instances and new public instances are supported. You must use Link SDK for C 4.x to develop the device. If you initiate a group-based dynamic update batch, the settings of MultiModuleMode and OverwriteMode must be the same as those in the existing dynamic update batch of the group. 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 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 unique identifier 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: The request was successful. false: The request failed.

Examples

Sample requests

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=CreateOTADynamicUpgradeJob
&FirmwareId=nx3xxVvFdwvn6dim50PY03****
&ProductKey=a1Le6d0****
&Tag.1.Key=key1
&Tag.1.Value=value1
&MaximumPerMinute=1000
&RetryCount=1
&RetryInterval=60
&TimeoutInMinutes=1440
&SrcVersion.1=V1.0.1
&OverwriteMode=2
&<Common request parameters>

Sample success response

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, see Service error codes.