V2.1 Search OTA Task¶
搜索设备执行的某个 OTA 任务的详情及执行进度、状态。
如果你在使用 API 批量更新相关 OTA 任务信息后调用当前 API，建议两次调用间隔 2 秒左右，以免获取到未更新数据。
该 API 支持在 EnOS 2.2.0 及以上环境中使用。
请求格式¶
POST https://{apigw-address}/connect-service/v2.1/ota-jobs?action=searchTask
请求参数（URI）¶
| 名称 | 位置（Path/Query） | 必需/可选 | 数据类型 | 描述 |
|---|---|---|---|---|
| orgId | Query | 必需 | String | 资产所属的组织 ID。如何获取 orgId 信息>> |
请求参数（Body）¶
| 名称 | 必需/可选 | 数据类型 | 描述 |
|---|---|---|---|
| expression | 可选 | String | 查询表达式，支持类 SQL 的查询。查询的字段和对应的运算符清单如下。
|
| 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 | 固件升级状态。
|
| 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
}
}