V2.4 Search Device¶

Search for devices based on the search criteria.

This API is only available if 2.4 Cumulative Update 1 has been applied to your environment.

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.4/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>>
requireSecret	Optional	Boolean	`true`: `deviceSecret` and `sessionKey` will be returned. Ensure that: Your service account has been granted with the required permission. If not, the returned value of `deviceSecret` and `sessionKey` will be an error. The RSA key pair has been created for the service account. Creating RSA Key Pairs >> `false` (default): `deviceSecret` and `sessionKey` will not be returned.
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, returned only when the value of `requireSecret` is `true`. The returned value will be encrypted. How to Decrypt >>
sessionKey	String	The key for encrypting and decrypting the value of `deviceSecret`, returned only when the value of `requireSecret` is `true`. The returned value will be encrypted. How to Decrypt >>
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.

Error Codes¶

Code	Message	Description
99400	Invalid arguments	One or multiple parameters are invalid.
11858	Unable to find public key	Unable to find public key for `requireSecret` due to there is no RSA key pair for the service account. Creating RSA Key Pairs >>.

Samples¶

Request Sample¶

url: https://{apigw-address}/connect-service/v2.4/devices?action=search&orgId=yourOrgId
method: POST
requestBody:
{
    "pagination": {
        "pageNo": 2,
        "pageSize": 5
    },
    "requireSecret": true,
    "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":{
                    "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 Samples¶

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

Java
Python