V2.4 Get Device


Get the information of a device.


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


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

Request Parameters (URI)


Note

Use one of the following methods to specify the device:

  • Include assetId in the request

  • Include productKey + deviceKey in the request


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>>

assetId

Query

Optional (See Note above)

String

The asset ID. How to get assetId>>

productKey

Query

Optional (See Note above)

String

The product key. To be used with deviceKey.

deviceKey

Query

Optional (See Note above)

String

The device key. To be used with productKey.

requireSecret

Query

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.

Response Parameters

Name

Data Type

Description

data

Device Struct

The returned results of the device information. For more details, 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.

productType

String

The product type.

dataFormat

String

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

  • “Json” represents the JSON data type.

deviceKey

String

The device key.

deviceName

StringI18n

The device name.

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.

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.

createTime

Long

The time when the device was created.

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.

lastOnlineTime

Long

The last online time of the device.

lastOfflineTime

Long

The last offline time of the device.

measurepointLastUpdate

Long

The last time when a measurement point was updated.

eventLastUpdate

Long

The last time when an event was updated.

attributeLastUpdate

Long

The last time when an attribute was updated.

featureLastUpdate

Long

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

firmwareVersion

String

The firmware version.

Error Codes

Code

Message

Description

11404

Device cannot be found

The assetId, productKey, and/or deviceKey used to specify the device does not exist.

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=get&orgId=yourOrgId&assetId=yourAssetId&requireSecret=true
method: GET

Return Sample


{
    "code": 0,
    "msg": "OK",
    "requestId": "835a5cc4-4487-4bf2-961a-55bc0ee77d02",
    "data": {
        "orgId": "yourOrgId",
        "assetId": "yourAssetId",
        "modelId": "yourModelId",
        "modelIdPath": "yourModelIdPath",
        "productKey": "yourProductKey",
        "productName": {
            "defaultValue": "test_product_name",
            "i18nValue": {}
        },
        "productType": "Device",
        "dataFormat": "Json",
        "deviceKey": "yourDeviceKey",
        "deviceName": {
            "defaultValue": "testforname",
            "i18nValue": {}
        },
        "deviceSecret":"EncryptedDeviceSecret",
    "sessionKey":"EncryptedSessionKey",
        "deviceDesc": "test for undatedevice",
        "timezone": "+08:00",
        "deviceAttributes": {
            "int11": 617
        },
        "deviceTags": {
            "test": "test for tags"
        },
        "mirrorSource": "mirrorSourceAssetId",
        "createTime": 1557905107199,
        "status": "offline",
        "activeTime": 1557909526473,
        "lastOnlineTime": 1560743931658,
        "lastOfflineTime": 1560744111658,
        "measurepointLastUpdate": 1565875705704,
        "eventLastUpdate": 1565875705856,
        "attributeLastUpdate": 1547793776699,
        "featureLastUpdate": 1565875705856,
        "firmwareVersion": "2.2"
    }
}

SDK Samples


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