V2.1 Search Device

Search for devices based on the search criteria.


This API is available in EnOS 2.1.0 and above. Version 2.4 has been added and it is recommended to use V2.4 Search Device.

If you need to invoke this API after performing bulk updates to relevant devices using other APIs, it is recommended to wait for about 2 seconds to avoid obtaining unupdated data.

Request Format

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

Request Parameters (URI)

Name

Location (Path/Query)

Mandatory/Optional

Data Type

Description

orgId

Query

Mandatory

String

The organization ID which the asset belongs to. How to get orgId>>

Request Parameters (Body)

Name

Mandatory/Optional

Data Type

Description

expression

Optional

String

The query expression, which supports deviceAttributes, deviceTags,``modelId``,``productKey``,``productType``,``firmwareVersion``,``deviceName``,``deviceKey``,``assetId``, and status. The supported logic operators are “and” and “or”. EnOS Edge only supports the assetId field and the “in” operator.

  • deviceAttributes: supports operators “=”, “exists”, “not exists”, and “in”. To use this parameter in a query, you need to use the format deviceAttributes.attributeId to specify an attribute. For example, “deviceAttributes.temperature”=35.5.

  • deviceTags: supports operators “=”, “!=”, “exists”, “not exists”, and “in”. To use this parameter in a query, you need to use the format deviceTags.keyName to specify the key of a tag. For example, “deviceTags.Region” = “China”.

  • modelId: supports operators “=”, “!=”, and “in”.

  • productKey , deviceKey , and assetId: support operators “=” and “in”.

  • productType: supports operator “=”, valid values are: “Device” and “Gateway”.

  • firmwareVersion: supports operators “=” and “in”.

  • deviceName: supports fuzzy inquiry of the specified language:

    • deviceName like 'xxx': fuzzy inquiry of the default name, Chinese name, and English name.

    • deviceName.default like 'xxx': fuzzy inquiry of the default name.

    • deviceName.zh_CN like 'xxx': fuzzy inquiry of the Chinese name. If no Chinese name exists, fuzzy inquiry of default name.

    • deviceName.en_US like 'xxx': fuzzy inquiry of the English name. If no English name exists, fuzzy inquiry of default name.

  • status: supports operators “=” and “in”, valid values are: “inactive”, “online”, “offline”, “disable”, and “mirror”.

How to use expression>>

pagination

Optional

Pagination Request Struct

Lists the paging requirements in a request. When not specified, 10 records are displayed per page by default and sorted in descending order by createTime. The maximum records per page is 1,000, but for optimal performance, it is recommended to have not more than 50 records per page. The maximum records per page for EnOS Edge is 3,000. sorters is not supported to sort the response. Customizing order is not supported by EnOS Edge, where the results will be sorted in ascending order by assetId. For more details, see Pagination Request Struct.

projection

Optional

Projection Struct

Enables you to crop the data result set returned in the request if needed. Only the specified fields will be returned in the data result set if this parameter is used. Otherwise all fields are returned. Cropping multi-layer fields are not supported by EnOS Edge, and only the outmost field is returned. For more details, see How does projection crop the result set?

populateLastUpdateInfo

Optional

Boolean

  • true: Returns measurepointLastUpdate, eventLastUpdate, attributeLastUpdate, and featureLastUpdate.

  • false (default): Does not return measurepointLastUpdate, eventLastUpdate, attributeLastUpdate, and featureLastUpdate.

Response Parameters

Name

Data Type

Description

data

Array of Device Structs

A list of the devices returned. For the details of a device struct, see Device Struct.

Device Struct

Name

Data Type

Description

orgId

String

The organization ID which the asset belongs to.

assetId

String

The asset ID.

modelId

String

The model ID which the asset belongs to.

modelIdPath

String

The model ID path.

productKey

String

The product key.

productName

StringI18n

The product name.

Note: This field is not supported by EnOS Edge.

productType

String

The product type.

Note: This field is not supported by EnOS Edge.

dataFormat

String

  • “Custom” represents the user-defined data type.

  • “Json” represents the JSON data type.

Note: This field is not supported by EnOS Edge.

deviceKey

String

The device key.

deviceName

StringI18n

The device name.

Note: This field is not supported by EnOS Edge.

deviceSecret

String

The device secret identifier.

deviceDesc

String

The device description.

Note: This field is not supported by EnOS Edge.

timezone

String

Timezone of the device’s location.

deviceAttributes

Map

The device attributes. The Key is the attribute ID, and the Value type depends on the attribute defined in the ThingModel.

deviceTags

Map

The device tags. (The Key and Value are of String type.)

mirrorSource

String

The device key of the mirror source.

Note: This field is not supported by EnOS Edge.

createTime

Long

The time when the device was created.

Note: This field is not supported by EnOS Edge.

status

String

The device status (online, offline, inactive, disable, or mirror)

Note: EnOS Edge only supports online or offline.

activeTime

Long

The time when the device was activated.

Note: This field is not supported by EnOS Edge.

lastOnlineTime

Long

The last online time of the device.

Note: This field is not supported by EnOS Edge.

lastOfflineTime

Long

The last offline time of the device.

Note: This field is not supported by EnOS Edge.

measurepointLastUpdate

Long

The last time when a measurement point was updated.

Note: This field is not supported by EnOS Edge.

eventLastUpdate

Long

The last time when an event was updated.

Note: This field is not supported by EnOS Edge.

attributeLastUpdate

Long

The last time when an attribute was updated.

Note: This field is not supported by EnOS Edge.

featureLastUpdate

Long

The last time when a measurement point, an event, or an attribute was updated.

Note: This field is not supported by EnOS Edge.

firmwareVersion

String

The firmware version.

Note: This field is not supported by EnOS Edge.

Samples

Request Sample

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

Return Sample

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

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

                }
            },
            "deviceSecret":"yourDeviceSecret",
            "deviceDesc":null,
            "timezone":"+09:00",
            "deviceAttributes":{

            },
            "deviceTags":{

            },
            "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":"yourDeviceSecret",
            "deviceDesc":null,
            "timezone":"+08:00",
            "deviceAttributes":{

            },
            "deviceTags":{

            },
            "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":"yourDeviceSecret",
            "deviceDesc":null,
            "timezone":"+08:00",
            "deviceAttributes":{
                "aaa":1,
                "76":0
            },
            "deviceTags":{

            },
            "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":"yourDeviceSecret",
            "deviceDesc":null,
            "timezone":"+08:00",
            "deviceAttributes":{
                "aaa":1,
                "76":0
            },
            "deviceTags":{

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

            },
            "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 Samples


You can access the SDK samples for Connection Service on GitHub: