Search OTA Task


Search for OTA tasks based on the search criteria.

Operation Permissions

Required Authorization Required Operation Permission
Device Management Read

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

Java SDK Sample

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