V2.1 Search OTA Task¶

搜索设备执行的某个 OTA 任务的详情及执行进度、状态。

如果你在使用 API 批量更新相关 OTA 任务信息后调用当前 API，建议两次调用间隔 2 秒左右，以免获取到未更新数据。

该 API 支持在 EnOS 2.2.0 及以上环境中使用。

操作权限¶

使用此 API 前，确保服务账号已被授予包含下列服务和操作权限的策略。有关授权服务账号的更多信息，参见管理服务账号。

需授权的服务	所需操作权限
固件	Read OTA

请求格式¶

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

请求参数（URI）¶

名称	位置（Path/Query）	必需/可选	数据类型	描述
orgId	Query	必需	String	资产所属的组织 ID。如何获取 orgId 信息>>

请求参数（Body）¶

名称

必需/可选

数据类型

描述

expression

可选

String

查询表达式，支持类 SQL 的查询。查询的字段和对应的运算符清单如下。

jobId、deviceKey、fromVersion、toVersion、status 和 desc：= 和 in。

pagination

可选

Pagination 请求结构体

分页参数。如未指定，默认每页 10 条。每页最大记录数为 200 条，但为获得最佳性能，建议每页不超过 50 条。不支持使用 sorters 参数对结果进行排序。Pagination 请求结构体>>

响应参数¶

名称	数据类型	描述
data	TaskInfo 结构体数组	查询到的 OTA 任务详情。TaskInfo 结构体的结构参见 TaskInfo 结构体>>

TaskInfo 结构体¶

名称	数据类型	描述
taskId	String	设备所执行的 OTA task 的 ID。同一个 OTA job，在不同设备上执行时，会使用一个 task ID 来唯一标识该 OTA job 在这台设备上执行时的任务流。
orgId	String	资产所属的组织 ID。
assetId	String	设备的asset ID。
productKey	String	设备的 product key。
deviceKey	String	设备的 Device Key。
jobId	String	OTA job 的 ID。
fromVersion	String	该 OTA task 中，需要升级的固件的版本号。
toVersion	String	该 OTA task 中，固件需要升级到的目标版本号。
progress	Integer	设备升级进度。用0到100之间（包括两端）的数字表示进度百分比。如果是负数，则表示该 task 失败。
desc	String	设备升级状态原因描述。可以返回 EnOS 指定的升级失败原因，具体内容也可由用户在设备端开发 OTA 能力时指定。
status	String	固件升级状态。 `init` : OTA task 已开始 `published` : OTA task 已发布 `upgrading` : OTA task 进行中 `succeeded` : OTA task 成功 `failed` : OTA task 失败
updateTime	Long	固件最近更新时间。

错误码¶

有关错误码的描述，参见通用错误码。

示例¶

请求示例¶

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

返回示例¶

{
    "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 示例¶

你可以在 Github 上获取接入服务的 SDK 示例：

Java
Python