V2.1 Search Device Upgrade¶

查询设备的固件信息及升级状态。

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

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

操作权限¶

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

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

请求格式¶

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

请求参数（URI）¶

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

请求参数（Body）¶

名称

必需/可选

数据类型

描述

expression

可选

String

查询表达式，支持类 SQL 的查询。目前支持查询的字段是 productKey 、 firmwareVersion 、 isUpgrading 。

productKey firmwareVersion 支持等于（=）、in 运算符。
isUpgrading 支持等于（=）运算符。

pagination

可选

Pagination 请求结构体

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

响应参数¶

名称	数据类型	描述
data	DeviceFirmware 结构体数组	设备的固件的详情列表，DeviceFirmware 结构体的结构参见下表。

DeviceFirmware 结构体¶

名称	数据类型	描述
orgId	String	资产所属的组织 ID。
assetId	String	资产的 ID。
productKey	String	设备的 product key。如何获取设备的 productKey 信息>>
deviceKey	String	设备的 Device Key。如何获取设备的 deviceKey 信息>>
firmwareVersion	String	设备的固件版本
isUpgrading	Boolean	设备固件升级的状态。 `true` 表示正在升级。 `false` 表示升级已经结束，有可能是升级成功，也有可能升级失败。

错误码¶

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

示例¶

请求示例¶

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

返回示例¶

{
    "code":0,
    "msg":"OK",
    "requestId":"7bd0040b-63c6-4173-b764-d2e8d6642dd3",
    "data":[
        {
            "orgId":"o15475466766371",
            "assetId":"rFFJ6j53",
            "productKey":"8UhOTwV5",
            "deviceKey":"WnszKfi8NU",
            "firmwareVersion":"7777",
            "isUpgrading":false
        },
        {
            "orgId":"o15475466766371",
            "assetId":"qOE2FZb5",
            "productKey":"BXwU4kMk",
            "deviceKey":"ota-device2",
            "firmwareVersion":"2.0",
            "isUpgrading":true
        },
        {
            "orgId":"o15475466766371",
            "assetId":"kYK5nVJv",
            "productKey":"8UhOTwV5",
            "deviceKey":"bCUsvJvEBT",
            "firmwareVersion":"2020.01",
            "isUpgrading":false
        },
        {
            "orgId":"o15475466766371",
            "assetId":"VeHlM7wW",
            "productKey":"8UhOTwV5",
            "deviceKey":"1HshYDJ3wf",
            "firmwareVersion":"2020.01",
            "isUpgrading":false
        },
        {
            "orgId":"o15475466766371",
            "assetId":"TGEIuAWG",
            "productKey":"8UhOTwV5",
            "deviceKey":"bfb1EcjaKG",
            "firmwareVersion":"7.7",
            "isUpgrading":false
        }
    ],
    "pagination":{
        "sortedBy":null,
        "pageNo":1,
        "pageSize":5,
        "totalSize":9
    }
}

SDK 示例¶

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

Java
Python