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

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.
name	String	Rule name.
description	String	Rule description.
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.
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.
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.
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.
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.

**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'.
repeat_interval	Integer	Parameter description: interval for triggering the rule, in seconds.
repeat_count	Integer	Parameter description: number of times that a rule is triggered.

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

**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.
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.
duration	Integer	Duration: device status duration. Value range: 0–60 (minutes).

**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.
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.
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.
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.
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.
project_id	String	Parameter description: ID of the project to which the SMN service belongs.
theme_name	String	Parameter description: SMN topic name.
topic_urn	String	Parameter description: SMN topic URN.
message_content	String	Parameter description: SMS or email content.
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.
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.

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

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

{
  "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"
  } ]
}