All Products
Search
Document Center

IoT Platform:ListOTAUnfinishedTaskByDevice

更新時間:Dec 18, 2023

Queries uncompleted update tasks of a device.

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.