V2.1 Search OTA Job¶

搜索 OTA job 信息。

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

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

操作权限¶

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

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

请求格式¶

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

请求参数（URI）¶

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

请求参数（Body）¶

名称

必需/可选

数据类型

描述

expression

可选

String

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

productKey、firmwareId 和 firmwareVersion：= 和 in。

type 和 status：=

firmwareName 和 name 支持指定语言模糊查询：

firmwareName like 'xxx' 和 name like 'xxx'：模糊查询 default、中文和英文名称。

firmwareName.defaultValue like 'xxx' 和 name.defaultValue like 'xxx'：模糊查询默认名称。

firmwareName.zh_CN like 'xxx' 和 name.zh_CN like 'xxx'：模糊查询中文名称，不存在中文名称时模糊查询 default 名称。

firmwareName.en_US like 'xxx' 和 name.en_US like 'xxx'：模糊查询英文名称，不存在英文名称时模糊查询 default 名称。

pagination

可选

Pagination 请求结构体

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

响应参数¶

备注

对于旧版固件文件，返回产品信息。对于新版固件文件，不返回产品信息。

名称	数据类型	描述
data	JobInfo 结构体数组	查询到的 OTA job 详情。其结构体参见 JobInfo 结构体。

JobInfo 结构体 ¶

名称	数据类型	描述
orgId	String	组织 ID。
productKey	String	设备的 Product key。
jobId	String	OTA Job ID。
name	StringI18n	Job 名称。
firmwareId	String	固件 ID。
firmwareVersion	String	固件版本。
firmwareName	StringI18n	固件名称。
type	String	任务类型。 `verify`：固件验证 job。 `upgrade`：固件升级 job。
enableUpgradeRequest	Boolean	是否允许设备主动请求升级。
upgradePolicy	String	升级策略。 `snapshot`：快照式升级 `incremental`：增量式升级其含义参见升级策略。
upgradeScope	UpgradeScope 结构体	待升级的设备及其固件版本号等信息，待升级的设备及版本号等信息，其结构参见 UpgradeScope 结构体。
upgradeTimeout	Long	升级超时时间，当 OTA task 进入 `upgrading` 状态时开始计算。单位是秒。你可以使用 Search OTA Task 来查询 OTA task 的状态。
retryPolicy	RetryPolicy 结构体	失败 OTA 任务重试的策略，其结构参见 RetryPolicy 结构体。
schedulePolicy	SchedulePolicy 结构体	OTA 任务调度的策略，其结构参见 SchedulePolicy 结构体。
maximumConcurrency	Integer	升级任务最大并发量。
status	String	任务状态。 `started` ：已启动 `stopped` ：已停止
createTime	Long	任务的创建时间。

UpgradeScope 结构体 ¶

名称	数据类型	描述
type	String	待升级设备的范围。有以下可选值： `total` : 所有的固件版本号为 `versionNumbers` 中指定的版本号的设备 `partial` : 固件版本号为 `versionNumbers` 中指定的版本号的设备的其中一部分。升级任务可以通过结构体内的 `deviceKeys` `attributes` `tags` `assetTrees` 中的某一个参数来具体指定升级哪些设备，固件验证任务则只能通过 `deviceKeys` 指定验证哪些设备。
versionNumbers	String 数组	待升级的固件版本号列表。
deviceKeys	String 数组	指定固件待验证或升级的设备的 Device Key。只能通过 `deviceKeys` `attributes` `tags` `assetTrees` 其中一个参数来指定设备。
attributes	Map（Key 为 String，Value 为 Object 数组）	指定具有特定属性和属性值的设备加入固件验证或升级。只能通过 `deviceKeys` `attributes` `tags` `assetTrees` 其中一个参数来指定设备。
tags	Map（Key 为 String，Value 为 String 数组）	指定具有特定标签和标签值的设备加入固件验证或升级。只能通过 `deviceKeys` `attributes` `tags` `assetTrees` 其中一个参数来指定设备。
assetTrees	AssetTreeScope 结构体	指定资产树里的设备加入固件验证或升级。只能通过 `deviceKeys` `attributes` `tags` `assetTrees` 其中一个参数来指定设备。其结构参见 AssetTreeScope 结构体。

AssetTreeScope 结构体 ¶

名称	数据类型	描述
treeId	String	资产树 ID。
includedNodes	String Array	资产树中的节点，由资产的 asset ID 识别。一个节点代表其自身及所有子节点，留空代表整棵树。

RetryPolicy 结构体 ¶

名称	数据类型	描述
enableRetry	Boolean	是否开启失败重试。
retryInterval	Integer	失败后自动重试间隔时间（秒）。
retryCount	Integer	最大自动重试次数。

SchedulePolicy 结构体 ¶

名称	数据类型	描述
isRepeatDaily	Boolean	任务是否每日重复。
startTimestamp	Long	开始调度时间的 13 位时间戳。
endTimestamp	Long	结束调度时间的 13 位时间戳。
timezoneOffsetInMinutes	Integer	时区偏移量，单位：分钟。

错误码¶

代码	错误信息	描述
99400	Do not allow operator op =, allowed op [like]	查询 `expression` 的语法不支持查询方式。

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

示例¶

请求示例¶

url: https://{apigw-address}/connect-service/v2.1/ota-jobs?action=search&orgId=yourOrgId
method: POST
requestBody:
//例 1
{
    "expression":"productKey='yourProductKey'",
    "pagination":{
        "pageNo":1,
        "pageSize":5
    }
}

//例 2
{
    "expression": "firmwareName like 'firmware1'",
    "pagination": {
        "pageNo": 1,
        "pageSize": 5
    }
}

//例 3
{
    "expression": "name like 'name' and firmwareName like 'firmware1'"
}

返回示例¶

{
    "code":0,
    "msg":"OK",
    "requestId":"99344e67-c79b-46bd-91d1-3ce3503ae769",
    "data":[
        {
            "orgId":"yourOrgId",
            "productKey":"yourProductKey",
            "jobId":"yourJobId",
            "name":{
                "defaultValue":"name",
                "i18nValue":{
                  "en_US":"name",
                  "zh_CN":"中文名",
                  "es_ES":"nombre",
                  "ja_JP":"名前"
        }
            },
            "firmwareId":"5ed0dd4a646542001b3d113f",
            "firmwareVersion":"1.1.0",
            "firmwareName":{
                "defaultValue":"firmware1",
                "i18nValue":{

                }
            },
            "type":"upgrade",
            "enableUpgradeRequest":true,
            "upgradePolicy":null,
            "upgradeScope":{
                "type":"total",
                "versionNumbers":[
                    "1.0"
                ],
                "deviceKeys":null,
                "attributes":null,
                "tags":null,
                "assetTrees":null
            },
            "upgradeTimeout":7200,
            "startSchedule":null, //deprecated
            "endSchedule":null, //deprecated
            "status":"started",
            "createTime":1591171274788
        }
    ],
    "pagination":{
        "sortedBy":null,
        "pageNo":1,
        "pageSize":5,
        "totalSize":1
    }
}

SDK 示例¶

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

Java
Python