Updated on 2024-06-27 GMT+08:00

Query the Rule List

Function

This API is used by an application to query the rule list on the platform.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

GET /v5/iot/{project_id}/rules

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Parameter description: project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

app_id

No

String

Parameter description: resource space ID. This parameter is optional. If you have multiple resource spaces, you can specify this parameter to query rules in the specified resource space. If this parameter is not carried, rules in all resource spaces are queried. Value: The value can contain a maximum of 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

rule_type

No

String

Parameter description: rule type. This parameter is optional. Rules of the specified type will be returned. If this parameter is not specified, all types of rules will be returned. Options:

  • DEVICE_LINKAGE: cloud linkage rule.

  • DEVICE_SIDE: Device-side rule.

limit

No

Integer

Parameter description: number of records to display on each page. Value: The value is an integer ranging from 1 to 50. The default value is 10.

Minimum: 1

Maximum: 50

Default: 10

marker

No

String

Parameter description: ID of the last record in the previous query. The value is returned by the platform during the previous query. Records are queried in descending order of record IDs (the marker value). A newer record will have a larger ID. If marker is specified, only the records whose IDs are smaller than marker are queried. If marker is not specified, the query starts from the record with the largest ID, that is, the latest record. If all data needs to be queried in sequence, this parameter must be filled with the value of marker returned in the last query response each time. Value: The value is a string of 24 hexadecimal characters. The default value is ffffffffffffffffffffffff.

Default: ffffffffffffffffffffffff

offset

No

Integer

Parameter description: If offset is set to N, the query starts from the N+1 record after the last record in the previous query. The value is an integer ranging from 0 to 500. The default value is 0. If offset is set to 0, the output starts from the first record after the last record in the previous query. To ensure API performance, you can use this parameter together with marker to turn pages. For example, if there are 50 records on each page, you can directly specify offset to jump to the specified page within page 1 and 11. If you want to view records displayed on pages 12 to 22, you need to use the marker value returned on page 11 as the marker value for the next query. Value: The value is an integer ranging from 0 to 500. The default value is 0.

Minimum: 0

Maximum: 500

Default: 0

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

Parameter description: user token. You can obtain the token by calling the IAM API Obtaining a User Token Through Password Authentication. In the returned response header, X-Subject-Token is the desired user token. For details about how to obtain the token, see Token Authentication.

Instance-Id

No

String

Parameter description: instance ID. Unique identifier of each instance in the physical multi-tenant scenario. Mandatory for professional editions and recommended in other cases. Log in to the IoTDA console and choose Overview in the navigation pane to view the instance ID. For details, see Viewing Instance Details.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

marker

String

ID of the last record in this query, which can be used in the next query.

count

Long

Total number of records that meet the query conditions.

rules

Array of RuleResponse objects

Rule list.

Table 5 RuleResponse

Parameter

Type

Description

rule_id

String

Rule ID.

Maximum: 128

name

String

Rule name.

Minimum: 1

Maximum: 128

description

String

Rule description.

Maximum: 256

condition_group

ConditionGroup object

Condition group of a rule, including simple and complex rules.

actions

Array of RuleAction objects

Action list of the rule. A maximum of 10 actions can be configured for a rule.

rule_type

String

Rule type.

  • DEVICE_LINKAGE: cloud linkage rule.

  • DEVICE_SIDE: Device-side rule.

status

String

Rule status. The default value is active.

  • active: activated.

  • inactive: not activated.

app_id

String

Resource space ID. This parameter is optional. If you have multiple resource spaces, you can use this parameter to specify the resource space to which the rule to create will belong. If this parameter is not specified, the rule to create will belong to the default resource space.

edge_node_ids

Array of strings

List of edge node IDs.

last_update_time

String

UTC time when the rule was last updated. The value is in the format of yyyyMMdd'T'HHmmss'Z'.

device_side

DeviceSide object

Parameter description: information of devices to which the device-side rule is delivered. This parameter is mandatory when rule_type is set to DEVICE_SIDE.

Table 6 ConditionGroup

Parameter

Type

Description

conditions

Array of RuleCondition objects

Parameter description: condition list of the rule. A maximum of 10 conditions can be configured for a rule.

logic

String

Parameter description: logical relationship between multiple conditions of the rule. The default value is and. Options:

  • and: All of the conditions are judged.

  • or: One of the conditions is judged.

time_range

TimeRange object

Parameter description: validity period of a condition.

Table 7 RuleCondition

Parameter

Type

Description

type

String

Parameter description: type of the rule condition. Options:

  • DEVICE_DATA: device property data condition.

  • SIMPLE_TIMER: simple timing condition.

  • DAILY_TIMER: daily scheduled condition.

  • DEVICE_LINKAGE_STATUS: device status condition.

device_property_condition

DeviceDataCondition object

Parameter description: details of the device data condition. This parameter is mandatory when type is set to DEVICE_DATA.

simple_timer_condition

SimpleTimerType object

Parameter description: details of the simple timing condition. This parameter is mandatory when type is set to SIMPLE_TIMER.

daily_timer_condition

DailyTimerType object

Parameter description: details of the daily scheduled condition. This parameter is mandatory when type is set to DAILY_TIMER.

device_linkage_status_condition

DeviceLinkageStatusCondition object

Parameter description: details of the device status condition. This parameter is mandatory when rule_type is set to DEVICE_LINKAGE and type is set to DEVICE_LINKAGE_STATUS.

Table 8 DeviceDataCondition

Parameter

Type

Description

device_id

String

Parameter description: device ID. The ID is unique and is allocated by the platform during device registration. If this parameter is specified, device property triggering is based on the specified device. This parameter and product_id cannot be both empty. If this parameter and product_id are both specified, the value of this parameter is used for filtering. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

product_id

String

Parameter description: unique ID of the product associated with the device. The value is allocated by the platform after the product is created. For details, see Creating a Product. If this parameter is specified and device_id is empty, all devices of the product are matched for device property triggering. This parameter and device_id cannot be both empty.

Maximum: 128

filters

Array of PropertyFilter objects

Data filter criteria.

Table 9 PropertyFilter

Parameter

Type

Description

path

String

Parameter description: path of the device properties. The value is in the format of [service_id]/DataProperty. For example, the path of the door sensor status is DoorWindow/status.

Maximum: 128

operator

String

Parameter description: data comparison operator. Options: >, <, >=, <=, =, in (match in specified values), and between (value range).

value

String

Parameter description: rvalue of the data comparison expression. When this parameter is used together with the data comparison operator between, the rvalue indicates the minimum value and maximum value, which are separated by commas (,). For example, 20,30 indicates that the value is greater than or equal to 20 and less than 30.

Maximum: 64

in_values

Array of strings

Parameter description: When operator is set to in, this parameter is used to transfer the rvalue of the comparison expression. Up to 20 values are allowed.

Maximum: 128

strategy

Strategy object

Parameter description: rule triggering policy, which is used to determine whether the last data meets the conditions. If rule_type is set to DEVICE_LINKAGE, either this parameter must be specified. This parameter is not supported by device-side rules.

Table 10 Strategy

Parameter

Type

Description

trigger

String

Parameter description: rule triggering judgment policy. The default value is pulse. Options:

  • pulse: If the reported data meets conditions, the rule is triggered and the previous data is not judged.

  • reverse: When the data reported this time meets the conditions, the rule is triggered even if the data reported last time does not meet the conditions.

event_valid_time

Integer

Parameter description: validity period of the device data, in seconds. The time when the device data is generated is the same as the value of eventTime in the reported data.

Minimum: -1

Table 11 SimpleTimerType

Parameter

Type

Description

start_time

String

Parameter description: start time for rule triggering. The UTC time is used. The value is in the format of yyyyMMdd'T'HHmmss'Z'.

Maximum: 128

repeat_interval

Integer

Parameter description: interval for triggering the rule, in seconds.

Minimum: 1

Maximum: 31536000

repeat_count

Integer

Parameter description: number of times that a rule is triggered.

Minimum: 1

Maximum: 9999

Table 12 DailyTimerType

Parameter

Type

Description

time

String

Parameter description: time when a rule is triggered. The value is in the format of HH:MM.

Maximum: 128

days_of_week

String

Parameter description: list of days in a week. Days are separated by commas (,). The value 1 indicates Sunday, the value 2 indicates Monday, and the rest can be deduced by analogy. By default, every day is included.

Maximum: 128

Table 13 DeviceLinkageStatusCondition

Parameter

Type

Description

device_id

String

Parameter description: device ID. The ID is unique and is allocated by the platform during device registration. If this parameter is specified, device status triggering is based on the specified device. This parameter and product_id cannot be both empty. If this parameter and product_id are both specified, the value of this parameter is used for filtering. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

product_id

String

Parameter description: unique ID of the product associated with the device. The value is allocated by the platform after the product is created. For details, see Creating a Product. If this parameter is specified and device_id is empty, all devices of the product are matched for device status triggering. This parameter and device_id cannot be both empty.

Maximum: 128

status_list

Array of strings

Parameter description: status list. This parameter must be carried for a device status condition. Options:

  • ONLINE: The device is online.

  • OFFLINE: The device is offline.

Maximum: 128

duration

Integer

Duration: device status duration. Value range: 0–60 (minutes).

Minimum: 0

Maximum: 60

Default: 0

Table 14 TimeRange

Parameter

Type

Description

start_time

String

Parameter description: start time for rule triggering. The value is in the format of HH:mm.

end_time

String

Parameter description: end time for rule triggering. The value is in the format of HH:mm. If the end time is the same as the start time, the rule is triggered at any time of a day.

days_of_week

String

Parameter description: list of days in a week. Days are separated by commas (,). The value 1 indicates Sunday, the value 2 indicates Monday, and the rest can be deduced by analogy. By default, every day is included. The date in the week list indicates the start date.

Table 15 RuleAction

Parameter

Type

Description

type

String

Parameter description: rule action type. Device-side rules support only DEVICE_CMD. Options:

  • DEVICE_CMD: delivering a device command message.

  • SMN_FORWARDING: sending an SMN message.

  • DEVICE_ALARM: reporting a device alarm. This type can only be selected when condition contains DEVICE_DATA. The action of this type must be unique.

device_command

ActionDeviceCommand object

Content of the device command message to deliver. This parameter is mandatory when type is set to DEVICE_CMD.

smn_forwarding

ActionSmnForwarding object

Structure of the SMN message to send. This parameter is mandatory when rule_type is set to DEVICE_LINKAGE and type is set to SMN_FORWARDING.

device_alarm

ActionDeviceAlarm object

Content of the device alarm message to report. This parameter is mandatory when rule_type is set to DEVICE_LINKAGE and type is set to DEVICE_ALARM.

Table 16 ActionDeviceCommand

Parameter

Type

Description

device_id

String

Parameter description: ID of the device that the command is delivered to.

  • When a device data rule is created, if device_id is empty, the command is delivered to the device for which the rule is triggered.

  • This parameter cannot be left empty when a scheduled rule is created. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

cmd

CMD object

Parameter description: command to deliver.

Table 17 CMD

Parameter

Type

Description

command_name

String

Parameter description: command name, which is defined in the product model associated with the device.

Maximum: 128

command_body

Object

Parameter description: command parameter in JSON format. An example command delivered to an LwM2M device is {"value":"1"}, which is a key-value pair. Each key is a paraName parameter in commands in the product model. An example command delivered to an MQTT device is {"header": {"mode": "ACK","from": "/users/testUser","method": "SET_TEMPERATURE_READ_PERIOD","to":"/devices/{device_id}/services/{service_id}"},"body": {"value" : "1"}}.

  • mode: indicates whether the device needs to reply an acknowledgment message after receiving a command. The default value is ACK. This parameter is mandatory. ACK indicates that an acknowledgment message must be replied. NOACK indicates that no acknowledgment message is required. Other values are invalid.

  • from: indicates the address of the command sender. This parameter is optional. The formats of requests initiated by the application, application server, and IoT platform are /users/{userId}, /{serviceName}, and /cloud/{serviceName}, respectively.

  • to: indicates the address of the command receiver. The value is in the format of /devices/{device_id}/services/{service_id}. This parameter is optional.

  • method: indicates the command name defined in the product model. This parameter is optional.

  • body: indicates the message body of the command. The value consists of key-value pairs. Each key is a paraName parameter in commands in the product model. This parameter optional. The specific format depends on the application and device.

service_id

String

Parameter description: ID of the device service that the device command belongs to, which is defined in the product model associated with the device.

Maximum: 64

buffer_timeout

Integer

Parameter description: duration for the platform to cache a device command before delivering it to the device, in seconds. After the duration elapses, the platform does not deliver this command. The default value is 172800 (48 hours). If buffer_timeout is set to 0, the command is delivered to the device immediately regardless of the command delivery mode set on the platform.

Minimum: 0

Maximum: 31536000

Default: 172800

response_timeout

Integer

Parameter description: validity period of a command response, in seconds. If the platform does not receive a response to a command within the time specified by response_timeout, the command times out. The default value is 1800.

Minimum: 1

Maximum: 31536000

Default: 1800

mode

String

Parameter description: mode in which device commands are delivered. This parameter is valid only when the value of buffer_timeout is greater than 0.

  • ACTIVE: The platform directly delivers commands to devices.

  • PASSIVE: After creating a device command, the platform caches the command. When the device goes online or the execution result of the previous command is reported, the platform delivers this command.

Table 18 ActionSmnForwarding

Parameter

Type

Description

region_name

String

Parameter description: region where the SMN service is deployed.

Maximum: 256

project_id

String

Parameter description: ID of the project to which the SMN service belongs.

theme_name

String

Parameter description: SMN topic name.

Maximum: 256

topic_urn

String

Parameter description: SMN topic URN.

Maximum: 256

message_content

String

Parameter description: SMS or email content.

Maximum: 1024

message_template_name

String

Parameter description: SMN template name.

message_title

String

Parameter description: SMS or email topic. The value is UTF-8 encoded and cannot exceed 521 bytes.

Table 19 ActionDeviceAlarm

Parameter

Type

Description

name

String

Parameter description: alarm name.

Maximum: 256

alarm_status

String

Parameter description: alarm status. Options:

  • fault: The alarm is reported.

  • recovery: The alarm is cleared.

severity

String

Parameter description: alarm severity. Options: warning, minor, major, and critical.

dimension

String

Parameter description: Alarm dimension, which is used together with the alarm name and alarm severity to identify an alarm. Alarms of the user dimension are used by default. Alarms of the device and resource space dimensions are supported. Options:

  • device: device dimension.

  • app: resource space dimension.

description

String

Parameter description: alarm description.

Maximum: 256

Table 20 DeviceSide

Parameter

Type

Description

device_ids

Array of strings

** Parameter description**: IDs of target devices to which the device-side rule is delivered. A unique device ID is allocated by the platform during device registration.

Maximum: 128

Example Requests

Queries linkage rules of a specified resource space in a list.

GET https://{endpoint}/v5/iot/{project_id}/rules?app_id={app_id}&limit={limit}&marker={marker}&offset={offset}

Example Responses

Status code: 200

OK

{
  "marker" : "6336a282cda07a01f7ac5d11",
  "count" : 1,
  "rules" : [ {
    "rule_id" : "5eb3628d017d9105d0cf9aec",
    "name" : "openLight",
    "condition_group" : {
      "conditions" : [ {
        "type" : "DEVICE_DATA",
        "device_property_condition" : {
          "device_id" : "07b69d78-c716-4be6-9545-869920738397",
          "filters" : [ {
            "path" : "StreetLight/visibility",
            "operator" : "<",
            "value" : "30",
            "strategy" : {
              "trigger" : "reverse",
              "event_valid_time" : 300
            }
          } ]
        }
      } ],
      "logic" : "and"
    },
    "actions" : [ {
      "type" : "DEVICE_CMD",
      "device_command" : {
        "device_id" : "3a9e52d9-3ebf-4985-89e9-6d2396748a2f",
        "cmd" : {
          "command_name" : "SET_LIGHT_SWITCH",
          "command_body" : {
            "value" : 0
          },
          "service_id" : "Switch",
          "buffer_timeout" : 0,
          "response_timeout" : 1800
        }
      }
    } ],
    "rule_type" : "DEVICE_LINKAGE",
    "status" : "active",
    "app_id" : "9562bf8541e44361b6ae3a7e9fbe1144",
    "last_update_time" : "20221017T023727Z"
  } ]
}

Status Codes

Status Code

Description

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

Error Codes

See Error Codes.