Search OTA Task¶
搜索设备执行的某个 OTA 任务的详情及执行进度、状态。
操作权限¶
需授权的资源 |
所需操作权限 |
---|---|
设备管理 |
Read |
请求格式¶
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 条。不支持使用 |
响应参数¶
名称 |
数据类型 |
描述 |
---|---|---|
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
}
}
Java SDK 调用示例¶
package com.envisioniot.enos.connect_service.ota.job;
import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;
import com.envisioniot.enos.api.common.constant.request.Pagination;
import com.envisioniot.enos.connect_service.v2_1.ota.job.task.SearchTaskRequest;
import com.envisioniot.enos.connect_service.v2_1.ota.job.task.SearchTaskResponse;
public class SearchTask {
public static void main(String[] args) {
final String appKey = "yourAppKey";
final String appSecret = "yourAppSecret";
String serverUrl = "yourServerUrl";
String orgId = "yourOrgId";
SearchTaskRequest request = new SearchTaskRequest();
request.setOrgId(orgId);
request.setExpression("jobId='yourJobId'");
Pagination pagination = new Pagination();
pagination.setPageNo(1);
pagination.setPageSize(10);
request.setPagination(pagination);
SearchTaskResponse response = Poseidon
.config(PConfig.init().appKey(appKey).appSecret(appSecret).debug())
.url(serverUrl)
.getResponse(request, SearchTaskResponse.class);
}
}