• 文档
• 网关与子设备
• Search Sub-Device
• V2.4 Search Sub-Device

V2.4 Search Sub-Device

搜索网关下的子设备信息。

使用此 API 前，确保已安装 EnOS 2.4 CU1 或更新版本。

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

请求格式

POST https://{apigw-address}/connect-service/v2.4/device-topos?action=searchSubDevice

请求参数（URI）

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

请求参数（Body）

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

DeviceIdentifier 结构体

备注

以下非必需字段中，必须提供 assetId，或提供 productKey + deviceKey，用于指定设备。

名称	必需/可选	数据类型	描述
assetId	可选（见上述注解）	String	资产 ID。如何获取 assetId 信息>>
productKey	可选（见上述注解）	String	设备的 product key，需与 deviceKey 一起使用。如何获取设备的三元组信息>>
deviceKey	可选（见上述注解）	String	设备的 device key，需与 productKey 一起使用。如何获取设备的三元组信息>>

响应参数

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

Device 结构体

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

错误码

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

示例

请求示例

url:https://{apigw-address}/connect-service/v2.4/device-topos?action=searchSubDevice&orgId=yourOrgId
method: POST
requestBody:
{
    "gateway":{
        "assetId":"yourAssetId"
        },
    "requireSecret": true
}

返回示例

{
        "code": 0,
        "msg": "OK",
        "requestId": "498d1c5b-7c4f-401a-a9ff-9072931bec2e",
        "data": [{
            "orgId": "yourOrgId",
            "assetId": "mAEsF3sm",
            "modelId": "AlterTest0617",
            "modelIdPath": "/AlterTest0617",
            "productKey": "yourProductKey",
            "productName": {
                "defaultValue": "AlterTest0617_Product",
                "i18nValue": {}
            },
            "productType": "Device",
            "dataFormat": "Json",
            "deviceKey": "yourDeviceKey",
            "deviceName": {
                "defaultValue": "testforCreatedevice",
                "i18nValue": {}
            },
            "deviceSecret":"EncryptedDeviceSecret1",
            "sessionKey":"EncryptedSessionKey1",
            "deviceDesc": "test for createdevice",
            "timezone": "+08:00",
            "deviceAttributes": {
                "testatt": 111111
            },
            "deviceTags": {},
            "mirrorSource": null,
            "firmwareVersion": null,
            "createTime": 1560755091998,
            "status": "inactive",
            "activeTime": 0,
            "lastOnlineTime": 0,
            "lastOfflineTime": 0,
            "measurepointLastUpdate": null,
            "eventLastUpdate": null,
            "attributeLastUpdate": null,
            "featureLastUpdate": null
        }, {
            "orgId": "yourOrgId",
            "assetId": "gVRwKQ3C",
            "modelId": "AlterTest0617",
            "modelIdPath": "/AlterTest0617",
            "productKey": "yourProductKey",
            "productName": {
                "defaultValue": "AlterTest0617_Product",
                "i18nValue": {}
            },
            "productType": "Device",
            "dataFormat": "Json",
            "deviceKey": "yourDeviceKey",
            "deviceName": {
                "defaultValue": "AlterTest0617_Product",
                "i18nValue": {}
            },
            "deviceSecret":"EncryptedDeviceSecret2",
            "sessionKey":"EncryptedSessionKey2",
            "deviceDesc": null,
            "timezone": "+10:00",
            "deviceAttributes": {},
            "deviceTags": {},
            "mirrorSource": null,
            "firmwareVersion": null,
            "createTime": 1560730295671,
            "status": "offline",
            "activeTime": 1560730567958,
            "lastOnlineTime": 1560743932166,
            "lastOfflineTime": 1560744112166,
            "measurepointLastUpdate": null,
            "eventLastUpdate": null,
            "attributeLastUpdate": null,
            "featureLastUpdate": null
        }],
        "pagination":{"sortedBy":null,"pageNo":1,"pageSize":2,"totalSize":2}}

SDK 示例

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

• Java

• Python