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 的查询。查询的字段和对应的运算符清单如下。

  • jobIddeviceKeyfromVersiontoVersionstatusdesc:= 和 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
    }
}

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