V2.1 Search OTA Task¶

Search for OTA tasks based on the search criteria.

This API is available in EnOS 2.2.0 and above.

If you need to invoke this API after performing bulk updates to relevant OTA tasks using other APIs, it is recommended to wait for about 2 seconds to avoid obtaining unupdated data.

Operation Permissions¶

Before invoking this API, ensure that the service account has been authorized the policy that includes the following service(s) and action permission(s). For how to authorize the service account, see Managing Service Accounts.

Required Service	Required Operation Permission
Firmware	Read OTA

Request Format¶

POST https://{apigw-address}/connect-service/v2.1/ota-jobs?action=searchTask

Request Parameters (URI)¶

Name	Location (Path/Query)	Mandatory/Optional	Data Type	Description
orgId	Query	Mandatory	String	The organization ID which the asset belongs to. How to get orgId>>

Request Parameters (Body)¶

Name	Location (Path/Query)	Mandatory/Optional	Data Type
expression	Optional	String	The query expression, which supports sql-like query. The supported query fields are `jobId`, `deviceKey`, `fromVersion`, `toVersion`, `status`, and `desc`. All the fields support arithmetic operators “=” and “in”.
pagination	Optional	Pagination Request Struct	Lists the paging requirements in a request. When not specified, 10 records are displayed per page by default. The maximum records per page is 200 but for optimal performance, it is recommended to have not more than 50 records per page. `sorters` is not supported to sort the response. For more details, see Pagination Request Struct>>

Response Parameters¶

Name	Data Type	Description
data	Array of TaskInfo Structs	The list of OTA tasks. For more details, see TaskInfo Struct>>

TaskInfo Struct ¶

Name	Data Type	Description
taskId	String	The task ID. When the same OTA job is executed on different devices, a task ID will be used to uniquely identify the task flow when the OTA job is executed on this device.
orgId	String	The organization ID.
assetId	String	The asset ID.
productKey	String	The product key.
deviceKey	String	The device key.
jobId	String	The OTA job ID.
fromVersion	String	The firmware version to be upgraded in this task.
toVersion	String	The firmware version to be upgrade from in this task.
progress	Integer	The progress of the task. 0 - 100 is used to indicated the percentage of the progress. If it is a negative number, it means the task failed.
desc	String	The device upgrade status description. Content can include the reason for the upgrade failure, or customized content specified by the user when developing the OTA capability on the device side.
status	String	The status of the task. `init`: OTA task has started. `upgrading`: OTA task upgrading in progress. `succeeded`: OTA task is successful. `failed`: OTA task failed.
updateTime	Long	The last firmware updated time.

Error Codes¶

For the description of error codes, see Common Error Codes.

Samples¶

Request Sample¶

url: https://{apigw-address}/connect-service/v2.1/ota-jobs?action=searchTask&orgId=yourOrgId
method: POST
requestBody:
{
    "expression":"deviceKey='ota-device1'",
    "pagination":{
        "pageNo":1,
        "pageSize":5
    }
}

Return Sample¶

{
    "code":0,
    "msg":"OK",
    "requestId":"6b88c1ba-3388-4888-9429-6d332d4dbe2b",
    "data":[
        {
            "taskId":"5ed0de47646542001b3d1146",
            "orgId":"o15475466766371",
            "assetId":"FOrco0Hu",
            "productKey":"BXwU4kMk",
            "deviceKey":"ota-device1",
            "jobId":"5ed0de47646542001b3d1145",
            "fromVersion":"1.0",
            "toVersion":"2.0",
            "progress":null,
            "desc":"user cancel",
            "status":"failed",
            "updateTime":1590746699719
        }
    ],
    "pagination":{
        "sortedBy":null,
        "pageNo":1,
        "pageSize":10,
        "totalSize":1
    }
}

SDK Samples¶

You can access the SDK samples for Connection Service on GitHub:

Java
Python