ListOTAUnfinishedTaskByDevice - IoT Platform - Alibaba Cloud Documentation Center

QPS limits

You can call this operation up to 10 times per second per account.

Note The 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 for different SDKs.

Request parameters

Parameter	Type	Required	Example	Description
Action	String	Yes	ListOTAUnfinishedTaskByDevice	The operation that you want to perform. Set the value to ListOTAUnfinishedTaskByDevice.
IotInstanceId	String	No	iot-c3j***	The ID of the instance. You can obtain the ID of the instance on the Overview tab in the IoT Platform console. Important If your instance has an ID, you must specify the ID for the parameter. Otherwise, the call fails. If no Overview tab or ID is generated for your instance, you do not need to configure this parameter. For more information about instances, see Overview.
ModuleName	String	No	WifiConfigModify	The name of the over-the-air (OTA) module. If you specify this parameter, the update tasks of the specified OTA module are queried. If you do not specify this parameter, the update tasks of all OTA modules are queried.
TaskStatusList.N	RepeatList	No	QUEUED	The status of the update task that you want to query. CONFIRM: The update task is pending confirmation. QUEUED: The update task is to be pushed. NOTIFIED: The update task is pushed to the device. IN_PROGRESS: The update task is in progress. Note You can specify multiple statuses for TaskStatusList.N when you call the ListOTAUnfinishedTaskByDevice operation. You must configure TaskStatusList.N or TaskStatus.
ProductKey	String	No	a19mzPZ****	The ProductKey of the product to which the device belongs. Important If you specify a value for this parameter, you must configure DeviceName.
DeviceName	String	No	light	The DeviceName of the device. Important If you configure this parameter, you must specify a value for ProductKey.
TaskStatus	String	No	CONFIRM	The status of the update task that you want to query. CONFIRM: The update task is pending confirmation. QUEUED: The update package is to be pushed. NOTIFIED: The update package is pushed to the device. IN_PROGRESS: The update task is in progress. Note You can specify only one status for TaskStatus when you call the ListOTAUnfinishedTaskByDevice operation. You must configure TaskStatusList or TaskStatus.
IotId	String	No	TfmUAeJjQQhCPH84UVNn0010c6****	The ID of the device. Important If you specify a value for this parameter, you do not need to configure ProductKey or DeviceName. The IotId parameter specifies a globally unique identifier (GUID) of the device, which corresponds to a combination of the values of ProductKey and DeviceName. If you specify values for IotId, ProductKey, and DeviceName, the value of IotId takes precedence.

In addition to the preceding operation-specific request parameters, you must configure 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	iot.system.SystemException	The error code returned if the call fails. For more information, see Error codes.
Data	Array of SimpleOTATaskInfo		The information about the update task returned if the call is successful. For more information, see SimpleOTATaskInfo.
SimpleOTATaskInfo
DestVersion	String	1.0.1	The version number of the firmware after the update.
DeviceName	String	light	The DeviceName of the device.
FirmwareId	String	q3j9OYBjUAZMv1hlMgdo03****	The ID of the update package.
IotId	String	nadRdeffljdEndlfadgadfse****	The unique ID of the device that is issued by IoT Platform. The ID of the device. The ID is a unique identifier that is issued by IoT Platform to the device.
JobId	String	7glPHmaDYLAYMD1HHutT02****	The ID of the update batch.
ModuleName	String	WifiConfigModify	The name of the OTA module.
ProductKey	String	a1GUfrM****	The ProductKey of the product to which the device belongs.
ProductName	String	MyProduct	The name of the product to which the device belongs.
SrcVersion	String	1.0.0	The firmware version before the update.
TaskId	String	y3tOmCDNgpR8F9jnVEzC01****	The ID of the update task.
TaskStatus	String	CONFIRM	The status of the update task. CONFIRM: The update task is pending confirmation. QUEUED: The update package is to be pushed. NOTIFIED: The update package is pushed to the device. IN_PROGRESS: The update task is in progress.
UtcCreate	String	2019-11-04T03:38:22.000Z	The time when the update task was created. The time is displayed in UTC.
UtcModified	String	2021-11-04T03:38:22.000Z	The time when the update task was last modified. The time is displayed in UTC.
ErrorMessage	String	A system exception occurred.	The error message returned if the call fails.
RequestId	String	A59D3BE1-E9A3-43F3-9B50-B7C8DE165D9B	The ID of the request.
Success	Boolean	true	Indicates whether the request was successful. Valid values: true: The call was successful. false: The call failed.

Examples

Sample requests

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=ListOTAUnfinishedTaskByDevice
&ProductKey=a19mzPZ****
&DeviceName=light
&TaskStatus=CONFIRM
&<Common request parameters>

Sample success responses

XML format

<ListOTAUnfinishedTaskByDevice>
  <Data>
        <SimpleOTATaskInfo>
              <SrcVersion>1.0.0</SrcVersion>
              <DeviceName>testDevice1</DeviceName>
              <FirmwareId>q3j9OYBjUAZMv1hlMgdo03****</FirmwareId>
              <IotId>SR8FiTu1R9tlUR2V1bmi00105****</IotId>
              <ProductKey>a1GUfrM****</ProductKey>
              <JobId>7glPHmaDYLAYMD1HHutT02****</JobId>
              <DestVersion>1.0.1</DestVersion>
              <UtcCreate>2019-11-04T03:38:15.000Z</UtcCreate>
              <UtcModified>2019-11-04T03:38:15.000Z</UtcModified>
              <TaskStatus>QUEUED</TaskStatus>
              <ProductName>MyProduct</ProductName>
              <TaskId>y3tOmCDNgpR8F9jnVEzC01****</TaskId>
              <ModuleName>WifiConfigModify</ModuleName>
        </SimpleOTATaskInfo>
        <SimpleOTATaskInfo>
              <SrcVersion>1.0.0</SrcVersion>
              <DeviceName>testDevice2</DeviceName>
              <FirmwareId>q3j9OYBjUAZMv1hlMgdo03****</FirmwareId>
              <IotId>nadRdeffljdEndlfadgadfse****</IotId>
              <ProductKey>a1GUfrM****</ProductKey>
              <JobId>7glPHmaDYLAYMD1HHutT02****</JobId>
              <DestVersion>1.0.1</DestVersion>
              <UtcCreate>2019-11-04T03:38:22.000Z</UtcCreate>
              <UtcModified>2019-11-04T03:38:22.000Z</UtcModified>
              <TaskStatus>CONFIRM</TaskStatus>
              <ProductName>MyProduct</ProductName>
              <TaskId>ZS9sNBb1ahsu6khqr9II01****</TaskId>
              <ModuleName>ConfigModify</ModuleName>
        </SimpleOTATaskInfo>
  </Data>
  <RequestId>A59D3BE1-E9A3-43F3-9B50-B7C8DE165D9B</RequestId>
  <Success>true</Success>
</ListOTAUnfinishedTaskByDevice>

JSON format

{
  "Data": {
    "SimpleOTATaskInfo": [{
      "SrcVersion": "1.0.0",
      "DeviceName": "testDevice1",
      "FirmwareId": "q3j9OYBjUAZMv1hlMgdo03****",
      "IotId": "SR8FiTu1R9tlUR2V1bmi00105****",
      "ProductKey": "a1GUfrM****",
      "JobId": "7glPHmaDYLAYMD1HHutT02****",
      "DestVersion": "1.0.1",
      "UtcCreate": "2019-11-04T03:38:15.000Z",
      "UtcModified": "2019-11-04T03:38:15.000Z",
      "TaskStatus": "QUEUED",
      "ProductName": "MyProduct",
      "TaskId": "y3tOmCDNgpR8F9jnVEzC01****",
      "ModuleName": "WifiConfigModify"
    }, {
      "SrcVersion": "1.0.0",
      "DeviceName": "testDevice2",
      "FirmwareId": "q3j9OYBjUAZMv1hlMgdo03****",
      "IotId": "nadRdeffljdEndlfadgadfse****",
      "ProductKey": "a1GUfrM****",
      "JobId": "7glPHmaDYLAYMD1HHutT02****",
      "DestVersion": "1.0.1",
      "UtcCreate": "2019-11-04T03:38:22.000Z",
      "UtcModified": "2019-11-04T03:38:22.000Z",
      "TaskStatus": "CONFIRM",
      "ProductName": "MyProduct",
      "TaskId": "ZS9sNBb1ahsu6khqr9II01****",
      "ModuleName": "ConfigModify"
    }]
  },
  "RequestId": "A59D3BE1-E9A3-43F3-9B50-B7C8DE165D9B",
  "Success": true
}

Error codes

HttpCode	Error Code	Error message	Description
400	iot.common.InvalidPageParams	The specified pagination size or pagination parameter is invalid.	The specified page size or page number is invalid.
400	iot.ota.NullOtaModuleName	the module name can not be empty.	No name is specified for the module.
400	iot.ota.InvalidOtaModuleName	the format of module name is invalid.	The module name is invalid.
400	iot.firmware.InvalidTaskStatus	Invalid TaskStatus.	The batch status is invalid.
400	iot.device.InvalidFormattedDeviceNameInNameArray	The deviceName list contains an invalid device name.	An invalid DeviceName exists in the DeviceName list.
400	iot.firmware.ListOTATaskByDeviceFailed	Failed to list OTA tasks by device.	The system failed to obtain the update tasks of the device.
400	iot.prod.NotExistedProduct	The specified product does not exist.	The product that you specified does not exist.

For a list of error codes, see Service error codes.