Modify a Rule
Function
This API is used by an application to modify the configuration of a specific rule 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
PUT /v5/iot/{project_id}/rules/{rule_id}
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. |
rule_id |
Yes |
String |
Parameter description: unique rule ID, which is allocated by the platform during rule creation. Value: The value can contain a maximum of 32 characters. Only letters and digits are allowed. |
Request 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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
name |
Yes |
String |
Parameter description: rule name. |
description |
No |
String |
Parameter description: rule description. |
condition_group |
Yes |
ConditionGroup object |
Parameter description: condition group of a rule, including simple and complex rules. |
actions |
Yes |
Array of RuleAction objects |
Parameter description: action list of the rule. A maximum of 10 actions can be configured for a rule. |
rule_type |
Yes |
String |
Parameter description: rule type. Options:
|
status |
No |
String |
Parameter description: rule status. The default value is active. Options:
|
app_id |
No |
String |
Parameter description: 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. Value: The value can contain a maximum of 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. |
device_side |
No |
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
conditions |
No |
Array of RuleCondition objects |
Parameter description: condition list of the rule. A maximum of 10 conditions can be configured for a rule. |
logic |
No |
String |
Parameter description: logical relationship between multiple conditions of the rule. The default value is and. Options:
|
time_range |
No |
TimeRange object |
Parameter description: validity period of a condition. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
type |
Yes |
String |
Parameter description: type of the rule condition. Options:
|
device_property_condition |
No |
DeviceDataCondition object |
Parameter description: details of the device data condition. This parameter is mandatory when type is set to DEVICE_DATA. |
simple_timer_condition |
No |
SimpleTimerType object |
Parameter description: details of the simple timing condition. This parameter is mandatory when type is set to SIMPLE_TIMER. |
daily_timer_condition |
No |
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 |
No |
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
device_id |
No |
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 |
No |
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 |
No |
Array of PropertyFilter objects |
Data filter criteria. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
path |
Yes |
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 |
Yes |
String |
Parameter description: data comparison operator. Options: >, <, >=, <=, =, in (match in specified values), and between (value range). |
value |
No |
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 |
No |
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 |
No |
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
trigger |
No |
String |
Parameter description: rule triggering judgment policy. The default value is pulse. Options:
|
event_valid_time |
No |
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
start_time |
Yes |
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 |
Yes |
Integer |
Parameter description: interval for triggering the rule, in seconds. |
repeat_count |
Yes |
Integer |
Parameter description: number of times that a rule is triggered. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
time |
Yes |
String |
Parameter description: time when a rule is triggered. The value is in the format of HH:MM. |
days_of_week |
No |
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
device_id |
No |
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 |
No |
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 |
No |
Array of strings |
Parameter description: status list. This parameter must be carried for a device status condition. Options:
|
duration |
No |
Integer |
Duration: device status duration. Value range: 0–60 (minutes). |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
start_time |
Yes |
String |
Parameter description: start time for rule triggering. The value is in the format of HH:mm. |
end_time |
Yes |
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 |
No |
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
type |
Yes |
String |
Parameter description: rule action type. Device-side rules support only DEVICE_CMD. Options:
|
device_command |
No |
ActionDeviceCommand object |
Content of the device command message to deliver. This parameter is mandatory when type is set to DEVICE_CMD. |
smn_forwarding |
No |
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 |
No |
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
device_id |
No |
String |
Parameter description: ID of the device that the command is delivered to.
|
cmd |
Yes |
CMD object |
Parameter description: command to deliver. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
command_name |
Yes |
String |
Parameter description: command name, which is defined in the product model associated with the device. |
command_body |
Yes |
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"}}.
|
service_id |
Yes |
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 |
No |
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 |
No |
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 |
No |
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.
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
region_name |
Yes |
String |
Parameter description: region where the SMN service is deployed. |
project_id |
Yes |
String |
Parameter description: ID of the project to which the SMN service belongs. |
theme_name |
Yes |
String |
Parameter description: SMN topic name. |
topic_urn |
Yes |
String |
Parameter description: SMN topic URN. |
message_content |
No |
String |
Parameter description: SMS or email content. |
message_template_name |
No |
String |
Parameter description: SMN template name. |
message_title |
Yes |
String |
Parameter description: SMS or email topic. The value is UTF-8 encoded and cannot exceed 521 bytes. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
name |
Yes |
String |
Parameter description: alarm name. |
alarm_status |
Yes |
String |
Parameter description: alarm status. Options:
|
severity |
Yes |
String |
Parameter description: alarm severity. Options: warning, minor, major, and critical. |
dimension |
No |
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:
|
description |
No |
String |
Parameter description: alarm description. |
Response Parameters
Status code: 200
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.
|
status |
String |
Rule status. The default value is active.
|
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. |
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:
|
time_range |
TimeRange object |
Parameter description: validity period of a condition. |
Parameter |
Type |
Description |
---|---|---|
type |
String |
Parameter description: type of the rule condition. Options:
|
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. |
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. |
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. |
Parameter |
Type |
Description |
---|---|---|
trigger |
String |
Parameter description: rule triggering judgment policy. The default value is pulse. Options:
|
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. |
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. |
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. |
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:
|
duration |
Integer |
Duration: device status duration. Value range: 0–60 (minutes). |
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. |
Parameter |
Type |
Description |
---|---|---|
type |
String |
Parameter description: rule action type. Device-side rules support only DEVICE_CMD. Options:
|
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. |
Parameter |
Type |
Description |
---|---|---|
device_id |
String |
Parameter description: ID of the device that the command is delivered to.
|
cmd |
CMD object |
Parameter description: command to deliver. |
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"}}.
|
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.
|
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. |
Parameter |
Type |
Description |
---|---|---|
name |
String |
Parameter description: alarm name. |
alarm_status |
String |
Parameter description: alarm status. Options:
|
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:
|
description |
String |
Parameter description: alarm description. |
Example Requests
Modifies the linkage rule. The rule is executed from 18:00 to 24:00 on Tuesday. When the value of visibility is less than 30, 19:00, or the specified time arrives, an alarm is generated and a command is delivered to the device.
PUT https://{endpoint}/v5/iot/{project_id}/rules/{rule_id} { "name" : "openLight", "description" : "string", "condition_group" : { "time_range" : { "days_of_week" : 2, "start_time" : "18:00", "end_time" : "23:00" }, "logic" : "or", "conditions" : [ { "device_property_condition" : { "device_id" : "07b69d78-c716-4be6-9545-869920738397", "product_id" : "074abacf-cdb1-4f52-8c88-5864e50d332c", "filters" : [ { "path" : "StreetLight/visibility", "strategy" : { "event_valid_time" : 300, "trigger" : "reverse" }, "value" : "30", "operator" : "<" } ] }, "daily_timer_condition" : { "days_of_week" : 2, "time" : "19:00" }, "type" : "DEVICE_DATA", "simple_timer_condition" : { "start_time" : "20190122T141500Z", "repeat_interval" : 1, "repeat_count" : 1 } } ] }, "actions" : [ { "device_alarm" : { "severity" : "warning", "alarm_status" : "fault", "name" : "The device property is abnormal.", "description" : "****The device property is abnormal." }, "type" : "DEVICE_CMD", "smn_forwarding" : { "message_content" : "message_content", "project_id" : "project_id", "message_title" : "message_title", "theme_name" : "theme_name", "region_name" : "region_name", "topic_urn" : "topic_urn" }, "device_command" : { "device_id" : "3a9e52d9-3ebf-4985-89e9-6d2396748a2f", "cmd" : { "buffer_timeout" : 0, "mode" : "string", "response_timeout" : 1800, "command_body" : { "value" : 0 }, "service_id" : "Switch", "command_name" : "SET_LIGHT_SWITCH" } } } ], "rule_type" : "DEVICE_LINKAGE", "status" : "string", "app_id" : "string" }
Example Responses
Status code: 200
OK
{ "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" : "20221017T025425Z" }
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.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot