V2.1 Search Sub-Device¶

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

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

当前 API 支持在 EnOS 2.1.0 及以上环境中使用，并已新增 V2.4 版本。推荐使用最新版本，参见 V2.4 Search Sub-Device。

请求格式¶

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

请求参数（URI）¶

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

请求参数（Body）¶

名称	必需/可选	数据类型	描述
gateway	必需	DeviceIdentfier 结构体	需要添加子设备的网关信息，其结构参见 DeviceIdentfier 结构体。
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。如何获取设备的 productKey 信息>>
productName	StringI18n	产品名称。
productType	String	产品类型。
dataFormat	String	数据格式。Custom 表示支持用户自定义数据格式，Json 表示只支持 EnOS 设备协议格式。
deviceKey	String	Device Key。如何获取设备的 deviceKey 信息>>
deviceName	StringI18n	设备名称。
deviceSecret	String	设备的 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 指定的设备不是网关。

示例¶

请求示例¶

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

返回示例¶

{
        "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": "yourDeviceSecret",
            "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": "yourDeviceSecret",
            "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