• 文档
• 设备
• Search Device
• V2.4 Search Device

V2.4 Search Device

查询设备信息。

使用此 API 前，确保已安装 EnOS 2.4 CU1 或更新版本。 如果你在使用 API 批量更新相关设备信息后调用当前 API，建议两次调用间隔 2 秒左右，以免获取到未更新数据。

请求格式

POST https://{apigw-address}/connect-service/v2.4/devices?action=search

请求参数（URI）

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

请求参数（Body）

名称	必需/可选	数据类型	描述
expression	可选	String	查询表达式，目前支持的字段有 deviceAttributes、 deviceTags、modelId、productKey、productType、firmwareVersion、deviceName、deviceKey、assetId 和 status。字段之间支持逻辑运算符 and、or。EnOS Edge 仅支持 assetId 字段，算术运算符仅支持 in。 deviceAttributes：支持算术运算符 =、exists、not exists、in。使用该参数查询，需要通过 deviceAttributes.attributeId 的形式来指定具体参与查询表达式的属性。例如 “deviceAttributes.temperature” = 35.5。 deviceTags：支持算术运算符 =、!=、exists、not exists、in。使用该参数查询，需要通过 deviceTags.keyName 的形式来指定具体参与查询表达式的键的名称。例如 “deviceTags.Region” = “China”。 modelId：支持算术运算符 =、!=、in。 productKey、 deviceKey、 assetId：支持算术运算符 =、in。 productType：支持算术运算符 =，有效取值为：Device、Gateway。 firmwareVersion：支持算术运算符 = 和 in。 deviceName：支持指定语言模糊查询： deviceName like 'xxx'：模糊查询 default、中文和英文名称。 deviceName.default like 'xxx'：模糊查询默认名称。 deviceName.zh_CN like 'xxx'：模糊查询中文名称，不存在中文名称时模糊查询 default 名称。 deviceName.en_US like 'xxx'：模糊查询英文名称，不存在英文名称时模糊查询 default 名称。 status：支持算术运算符 =、in，有效取值为：inactive、online、offline、disable、mirror。 如何使用查询表达式>>
requireSecret	可选	Boolean	true：返回 deviceSecret 和 sessionKey。需确保： 服务账号已被授予对应的 操作权限。若无权限，deviceSecret 和 sessionKey 返回的值将提示错误。 已为服务帐号创建 RSA 密钥对。创建 RSA 密钥对 >> false （默认）：不返回 deviceSecret 和 sessionKey。
pagination	可选	Pagination 请求结构体	随机分页。如未指定，默认每页 10 条。每页最大记录数为 1,000 条，但为获得最佳性能，建议每页不超过 50 条。EnOS Edge 单页最大上限为 3,000 条。不支持使用 sorters 参数对结果进行排序，查询结果按照 createTime，最近创建的靠前排列。EnOS Edge 不支持自定义排序，默认按照 assetId 字段升序对结果进行排序。Pagination 请求结构体>>
projection	可选	Projection 结构体	指定对返回结果的裁剪。对于符合条件的搜索仅返回符合条件的字段，不设置则默认返回全部字段。EnOS Edge 不支持多层字段的裁剪，只取最外层字段。Projection 参数如何对结果集做裁剪>>
populateLastUpdateInfo	可选	Boolean	true：返回 measurepointLastUpdate、eventLastUpdate、attributeLastUpdate 和 featureLastUpdate 参数。 false （默认）：不返回 measurepointLastUpdate、eventLastUpdate、attributeLastUpdate 和 featureLastUpdate 参数。

响应参数

名称	数据类型	描述
data	Device 结构体数组	有关 Device 结构体的定义，参见 Device 结构体。

Device 结构体

名称	数据类型	描述
orgId	String	资产所属的组织 ID。
assetId	String	资产 ID。
modelId	String	资产所属模型 ID。
modelIdPath	String	模型 ID 的路径。
productKey	String	Product Key。
productName	StringI18n	产品名称。 注：EnOS Edge 不支持返回该字段。
productType	String	产品类型。 注：EnOS Edge 不支持返回该字段。
dataFormat	String	数据格式。Custom 表示支持用户自定义数据格式，Json 表示只支持 EnOS 设备协议格式。 注：EnOS Edge 不支持返回该字段。
deviceKey	String	Device Key。
deviceName	StringI18n	设备名称。 注：EnOS Edge 不支持返回该字段。
deviceSecret	String	设备连接密钥，仅当 requireSecret 为 true 时返回。返回值已经过加密处理。如何解密 Device Secret >>
sessionKey	String	配合解密 deviceSecret 的参数，仅当 requireSecret 为 true 时返回。返回值已经过加密处理。
deviceDesc	String	设备描述。 注：EnOS Edge 不支持返回该字段。
timezone	String	设备所在时区。
deviceAttributes	Map（Key 和 Value 为 string）	设备的属性。
deviceTags	Map（Key 和 Value 为 string）	设备的标签。
mirrorSource	String	镜像源设备的 device key。 注：EnOS Edge 不支持返回该字段。
createTime	Long	设备的创建时间。 注：EnOS Edge 不支持返回该字段。
status	String	设备的状态（online、offline、inactive、disable 或 mirror）。 注：EnOS Edge 仅支持 online 或 offline。
activeTime	Long	设备的激活时间。 注：EnOS Edge 不支持返回该字段。
lastOnlineTime	Long	设备最后一次上线时间。 注：EnOS Edge 不支持返回该字段。
lastOfflineTime	Long	设备最后一次离线时间。 注：EnOS Edge 不支持返回该字段。
measurepointLastUpdate	Long	设备测点最近一次更新的时间。 注：EnOS Edge 不支持返回该字段。
eventLastUpdate	Long	设备事件最近一次更新的时间。 注：EnOS Edge 不支持返回该字段。
attributeLastUpdate	Long	设备属性最近一次更新的时间。 注：EnOS Edge 不支持返回该字段。
featureLastUpdate	Long	设备最近一次更新的时间，以上述三个时间（ measurepointLastUpdate 、 eventLastUpdate 、 attributeLastUpdate ）里最近的时间为准。 注：EnOS Edge 不支持返回该字段。
firmwareVersion	String	固件版本号。 注：EnOS Edge 不支持返回该字段。

错误码

代码	错误信息	描述
99400	Invalid arguments	参数错误。
11858	Unable to find public key	由于应用的服务帐号未创建 RSA 密钥对，无法获取 RSA 公钥，因此无法请求 requireSecret。请先为服务帐号 创建 RSA 密钥对。

示例

请求示例

url:https://{apigw-address}/connect-service/v2.4/devices?action=search&orgId=yourOrgId
method: POST
requestBody:
{
    "expression": "assetId = 'yourAssetId'",
    "pagination":{
        "pageNo":2,
        "pageSize":5
    },
    "requireSecret": true,
    "populateLastUpdateInfo": true
}

返回示例

{
    "code":0,
    "msg":"OK",
    "requestId":"59ecd409-7baa-4726-ba10-c0bde35ffb09",
    "data":[
        {
            "orgId":"yourOrgId",
            "assetId":"yourAssetId",
            "modelId":"lxctimelooker",
            "modelIdPath":"/lxctimelooker",
            "productKey":"yourProductKey",
            "productName":{
                "defaultValue":"lxcpro",
                "i18nValue":{
                    "zh_CN": null,
                    "en_ES": null,
                    "ja_JP": null,
                    "en_US": null
                }
            },
            "productType":"Device",
            "dataFormat":"Json",
            "deviceKey":"yourDeviceKey",
            "deviceName":{
                "defaultValue":"time2dev11",
                "i18nValue":{

                }
            },
            "deviceSecret":"EncryptedDeviceSecret1",
            "sessionKey":"EncryptedSessionKey1",
            "deviceDesc":null,
            "timezone":"+09:00",
            "deviceAttributes":{
                "invType": 0,
                "Capacity": 123.0
            },
            "deviceTags":{

            },
            "mirrorSource": null,
            "firmwareVersion": null,
            "createTime":1558421750575,
            "status":"offline",
            "activeTime":1558482329972,
            "lastOnlineTime":1560743915454,
            "lastOfflineTime":1560744095454,
            "measurepointLastUpdate":null,
            "eventLastUpdate":null,
            "attributeLastUpdate":null,
            "featureLastUpdate":null,
            "firmwareVersion": "2.2"
        },
        {
            "orgId":"yourOrgId",
            "assetId":"Fi0HQ8FO",
            "modelId":"AlterTest0615",
            "modelIdPath":"/AlterTest0615",
            "productKey":"yourProductKey",
            "productName":{
                "defaultValue":"AlterTest0615_Product",
                "i18nValue":{

                }
            },
            "productType":"Device",
            "dataFormat":"Json",
            "deviceKey":"yourDeviceKey",
            "deviceName":{
                "defaultValue":"AlterTest0615",
                "i18nValue":{

                }
            },
            "deviceSecret":"EncryptedDeviceSecret2",
            "sessionKey":"EncryptedSessionKey2",
            "deviceDesc":null,
            "timezone":"+08:00",
            "deviceAttributes":{

            },
            "deviceTags":{

            },
            "mirrorSource": null,
            "firmwareVersion": null,
            "createTime":1560564762147,
            "status":"offline",
            "activeTime":1560564838673,
            "lastOnlineTime":1560743931247,
            "lastOfflineTime":1560743931712,
            "measurepointLastUpdate":null,
            "eventLastUpdate":null,
            "attributeLastUpdate":null,
            "featureLastUpdate":null,
            "firmwareVersion": "2.2"
        },
        {
            "orgId":"yourOrgId",
            "assetId":"6FytqleL",
            "modelId":"AlterTest0614",
            "modelIdPath":"/AlterTest0614",
            "productKey":"yourProductKey",
            "productName":{
                "defaultValue":"AlterTest0614_Product",
                "i18nValue":{

                }
            },
            "productType":"Device",
            "dataFormat":"Json",
            "deviceKey":"yourDeviceKey",
            "deviceName":{
                "defaultValue":"AlterTest0614",
                "i18nValue":{

                }
            },
            "deviceSecret":"EncryptedDeviceSecret3",
            "sessionKey":"EncryptedSessionKey3",
            "deviceDesc":null,
            "timezone":"+08:00",
            "deviceAttributes":{
                "aaa":1,
                "76":0
            },
            "deviceTags":{

            },
            "mirrorSource": null,
            "firmwareVersion": null,
            "createTime":1560493341919,
            "status":"offline",
            "activeTime":1560493435761,
            "lastOnlineTime":1560743930253,
            "lastOfflineTime":1560743930346,
            "measurepointLastUpdate":null,
            "eventLastUpdate":null,
            "attributeLastUpdate":null,
            "featureLastUpdate":null,
            "firmwareVersion": "2.2"
        },
        {
            "orgId":"yourOrgId",
            "assetId":"yourAssetId",
            "modelId":"yourModelId",
            "modelIdPath":"yourModelIdPath",
            "productKey":"yourProductKey",
            "productName":{
                "defaultValue":"AlertTest0613_Product",
                "i18nValue":{

                }
            },
            "productType":"Device",
            "dataFormat":"Json",
            "deviceKey":"yourDeviceKey",
            "deviceName":{
                "defaultValue":"AlertTest0613",
                "i18nValue":{

                }
            },
            "deviceSecret":"EncryptedDeviceSecret4",
            "sessionKey":"EncryptedSessionKey4",
            "deviceDesc":null,
            "timezone":"+08:00",
            "deviceAttributes":{
                "aaa":1,
                "76":0
            },
            "deviceTags":{

            },
            "mirrorSource": null,
            "firmwareVersion": null,
            "createTime":1560389949661,
            "status":"offline",
            "activeTime":1560390227903,
            "lastOnlineTime":1560743916848,
            "lastOfflineTime":1560743929003,
            "measurepointLastUpdate":null,
            "eventLastUpdate":null,
            "attributeLastUpdate":null,
            "featureLastUpdate":null,
            "firmwareVersion": "2.2"
        },
        {
            "orgId":"yourOrgId",
            "assetId":"yourAssetId",
            "modelId":"yourModelId",
            "modelIdPath":"yourModelIdPath",
            "productKey":"yourProductKey",
            "productName":{
                "defaultValue":"zccp-----1",
                "i18nValue":{

                }
            },
            "productType":"Device",
            "dataFormat":"Json",
            "deviceKey":"yourDeviceKey",
            "deviceName":{
                "defaultValue":"zccp-----222",
                "i18nValue":{

                }
            },
            "deviceSecret":"EncryptedDeviceSecret5",
            "sessionKey":"EncryptedSessionKey5",
            "deviceDesc":null,
            "timezone":"+08:00",
            "deviceAttributes":{
                "timestamp1":1,
                "float1":1.0,
                "bool11":false,
                "int1":1,
                "string1":"1",
                "double1":1.0,
                "12221":false,
                "array1":[
                    1
                ],
                "stuct1":{
                    "int11":1
                },
                "file1":"ftp://a.com/demo.txt",
                "enum":1,
                "dete1":"2019-05-06"
            },
            "deviceTags":{

            },
            "mirrorSource": null,
            "firmwareVersion": null,
            "createTime":1559294746435,
            "status":"inactive",
            "activeTime":0,
            "lastOnlineTime":0,
            "lastOfflineTime":0,
            "measurepointLastUpdate":null,
            "eventLastUpdate":null,
            "attributeLastUpdate":null,
            "featureLastUpdate":null,
            "firmwareVersion": "2.2"
        }
    ],
    "pagination":{
        "sortedBy":null,
        "pageNo":2,
        "pageSize":5,
        "totalSize":6511
    }
}

SDK 示例

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

• Java

• Python