V2.1 Search Command


Search for commands of a device and filter the results based on the search criteria.


This API is available in EnOS 2.1.0 and above.

If you need to invoke this API after performing bulk updates to relevant commands 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/commands?action=search

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.

Request Parameters (Body)

Name

Mandatory/Optional

Data Type

Description

expression

Optional

String

The query expression, which supports sql-like query. The fields that are supported include the below.

  • state: supports arithmetic operator “=”.

  • commandName.default: supports fuzzy inquiry, where locale is mandatory, such as “commandName.zh_CN” or “commandName.en_US”.

  • createTime: supports “<” and “>=” to specify the time range. The time needs to be in this format YYYY-MM-DD HH:mm:ss, for example: 2019-04-17 10:30:00.

How to use expression>>

pagination

Optional

Pagination Request Struct

Lists the paging requirements in a request. When not specified, 100 records are displayed per page by default and sorted in descending order by createTime. For optimal performance, it is recommended to have not more than 50 records per page. sorters is not supported to sort the response. 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. How does projection crop the result set>>

Response Parameters

Name

Data Type

Description

data

Array of Command Structs

The list of commands. For details, see Command Struct.

Command Struct

Name

Data Type

Description

commandId

String

The command ID.

orgId

String

The organization ID which the asset belongs to.

productKey

String

The product key.

deviceKey

String

The device key.

assetId

String

The asset ID.

createTime

String

The time when the command was invoked.

createLocaltime

String

The local time when the command was invoked.

commandType

Integer

The command type.

  • 1 = Measurement point setting

  • 2 = Service invocation

commandName

StringI18n

The command name.

timeout

Integer

The command timeout duration. Its unit is seconds and its range is [1-60]. The default value is 30.

pendingTtl

Long

The command cache duration. Its unit is seconds and its range is [ 0 - 48 * 60 * 60 ], which is 0 by default. If the pendingTtl is 0, it indicates that the commands will be executed immediately.

state

Integer

The command status, which is represented by an integer from 1-7.

  • 1 = Created

  • 2 = Canceled

  • 3 = Expired

  • 4 = Released

  • 5 = Send successfully

  • 6 = Failed

  • 7 - Response timed out

tslIdentifier

String

Command Identifier.

inputData

Map (Key is of String type and the Value is of String, Number, Array or Object type)

The input data. The key is the input parameter identifier, and the value’s data type needs to conform to the model’s definition.

outputData

Map (Key is of String type and the Value is of String, Number, Array or Object type)

The output data. The key is the output parameter identifier, and the value is the service’s output result. The value’s data type needs to conform to the model’s definition

Samples

Request Sample

url: https://{apigw-address}/connect-service/v2.1/commands?action=search&deviceKey=yourDeviceKey&productKey=yourProductKey&orgId=yourOrgId
method: POST
requestBody:
{
    "expression": {
      "state = 2"
    },
    "pagination": {
      "pageNo":1,
      "pageSize":5
    }
}

Return Sample

{
  "code": 0,
  "msg": "OK",
  "requestId": "df57e058-0d8b-4700-9e38-ef30132c155f",
  "data": [
    {
      "commandId": "2322417636630765568",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688731159,
      "createLocaltime": "2019-08-13 09:32:11",
      "commandType": 1,
      "commandName": {
        "defaultValue": "Int_value",
        "i18nValue": {
          "en_US": "Int_value"
        }
      },
      "timeout": 30,
      "pendingTtl": 100,
      "state": 2,
      "tslIdentifier": "Int_value",
      "inputData": 111,
      "outputData": null
    },
    {
      "commandId": "2322417598073053184",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688726563,
      "createLocaltime": "2019-08-13 09:32:06",
      "commandType": 2,
      "commandName": {
        "defaultValue": "service522",
        "i18nValue": {
          "en_US": "service522"
        }
      },
      "timeout": 10,
      "pendingTtl": 600,
      "state": 2,
      "tslIdentifier": "service522",
      "inputData": {
        "service_input": 555
      },
      "outputData": null
    },
    {
      "commandId": "2322417559066025984",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688721913,
      "createLocaltime": "2019-08-13 09:32:01",
      "commandType": 2,
      "commandName": {
        "defaultValue": "service522",
        "i18nValue": {
          "en_US": "service522"
        }
      },
      "timeout": 10,
      "pendingTtl": 600,
      "state": 2,
      "tslIdentifier": "service522",
      "inputData": {
        "service_input": 555
      },
      "outputData": null
    },
    {
      "commandId": "2322417537678745600",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688719363,
      "createLocaltime": "2019-08-13 09:31:59",
      "commandType": 1,
      "commandName": {
        "defaultValue": "Int_value",
        "i18nValue": {
          "en_US": "Int_value"
        }
      },
      "timeout": 10,
      "pendingTtl": 600,
      "state": 2,
      "tslIdentifier": "Int_value",
      "inputData": 111,
      "outputData": null
    },
    {
      "commandId": "2322417518334615552",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688717057,
      "createLocaltime": "2019-08-13 09:31:57",
      "commandType": 1,
      "commandName": {
        "defaultValue": "Int_value",
        "i18nValue": {
          "en_US": "Int_value"
        }
      },
      "timeout": 10,
      "pendingTtl": 600,
      "state": 2,
      "tslIdentifier": "Int_value",
      "inputData": 111,
      "outputData": null
    }
  ],
  "pagination": {
    "sortedBy": [
      {
        "field": "createDate",
        "order": "DESC"
      }
    ],
    "pageNo": 1,
    "pageSize": 5,
    "totalSize": 547
  }
}

Sample 2

Request Sample

url: https://apigw-address/connect-service/v2.1/commands?action=search&deviceKey=zm_mqtt&productKey=bXuuAiku&orgId=yourOrgId
method: POST
requestBody:
{
  "expression": "commandName.zh_CN like \"Int_value\" AND createTime >= \"2019-08-13 09:00:00\"",
  "pagination": {
    "pageNo": 1,
    "pageSize": 5
  }
}

Return Sample

{
  "code": 0,
  "msg": "OK",
  "requestId": "051ab2c9-5de4-4c05-9731-042475234267",
  "data": [
    {
      "commandId": "2322417698664521728",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688738554,
      "createLocaltime": "2019-08-13 09:32:18",
      "commandType": 1,
      "commandName": {
        "defaultValue": "Int_value",
        "i18nValue": {
          "en_US": "Int_value"
        }
      },
      "timeout": 30,
      "pendingTtl": 0,
      "state": 6,
      "tslIdentifier": "Int_value",
      "inputData": 111,
      "outputData": null
    },
    {
      "commandId": "2322417676665921536",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688735932,
      "createLocaltime": "2019-08-13 09:32:15",
      "commandType": 1,
      "commandName": {
        "defaultValue": "Int_value",
        "i18nValue": {
          "en_US": "Int_value"
        }
      },
      "timeout": 30,
      "pendingTtl": 0,
      "state": 6,
      "tslIdentifier": "Int_value",
      "inputData": 111,
      "outputData": null
    },
    {
      "commandId": "2322417636630765568",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688731159,
      "createLocaltime": "2019-08-13 09:32:11",
      "commandType": 1,
      "commandName": {
        "defaultValue": "Int_value",
        "i18nValue": {
          "en_US": "Int_value"
        }
      },
      "timeout": 30,
      "pendingTtl": 100,
      "state": 2,
      "tslIdentifier": "Int_value",
      "inputData": 111,
      "outputData": null
    },
    {
      "commandId": "2322417537678745600",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688719363,
      "createLocaltime": "2019-08-13 09:31:59",
      "commandType": 1,
      "commandName": {
        "defaultValue": "Int_value",
        "i18nValue": {
          "en_US": "Int_value"
        }
      },
      "timeout": 10,
      "pendingTtl": 600,
      "state": 2,
      "tslIdentifier": "Int_value",
      "inputData": 111,
      "outputData": null
    },
    {
      "commandId": "2322417518334615552",
      "orgId": "yourOrgId",
      "productKey": "yourProductKey",
      "deviceKey": "yourDeviceKey",
      "assetId": "sxH2DD6f",
      "createTime": 1565688717057,
      "createLocaltime": "2019-08-13 09:31:57",
      "commandType": 1,
      "commandName": {
        "defaultValue": "Int_value",
        "i18nValue": {
          "en_US": "Int_value"
        }
      },
      "timeout": 10,
      "pendingTtl": 600,
      "state": 2,
      "tslIdentifier": "Int_value",
      "inputData": 111,
      "outputData": null
    }
  ],
  "pagination": {
    "sortedBy": [
      {
        "field": "createDate",
        "order": "DESC"
      }
    ],
    "pageNo": 1,
    "pageSize": 5,
    "totalSize": 6
  }
}

SDK Samples


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