CreateRule - IoT Platform

Creates a data forwarding rule for a specific topic.

Usage notes

When you call this operation, you must specify ProductKey in the request.

QPS limits

You can call this API operation up to 50 times per second per account.

Note

The Resource Access Management (RAM) users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter	Type	Required	Example	Description
Action	String	Yes	CreateRule	The operation that you want to perform. Set the value to CreateRule.
Name	String	Yes	iot_test1	The name of the data forwarding rule. The rule name must be 1 to 30 characters in length, and can contain letters, digits, underscores (_), and hyphens (-).
IotInstanceId	String	No	iot-cn-0pp1n8t****	The instance ID. You can view the instance ID on the Overview tab of the IoT Platform console. Important You must specify this parameter if your instance has an ID. Otherwise, the call fails. If the Overview tab or instance ID is not displayed in the IoT Platform console, you do not need to specify this parameter. For more information about instances, see Overview.
Select	String	No	deviceName() as deviceName, items.Humidity.value as Humidity, items.Temperature.value as Temperature	The SQL SELECT statement that you want to execute. For more information, see SQL statements. Note This parameter specifies the fields in SELECT statements. For example, if the SELECT statement is `SELECT a,b,c`, set this parameter to `a,b,c`.
ShortTopic	String	No	+/thing/event/property/post	The topic to which this rule is applied. The format is `${deviceName}/topicShortName`. `${deviceName}` specifies the name of the device, and `topicShortName` specifies the short name of the topic. For basic communication topics or Thing Specification Language (TSL)-based communication topics, the format is `${deviceName}/topicShortName`. You can replace `${deviceName}` with the `+` wildcard character. The wildcard character indicates that the topic applies to all devices under the product. Valid values of `topicShortName`: `/thing/event/property/post`: submits the property data of a device. `/thing/event/${tsl.event.identifier}/post`: submits the event data of a device. `${tsl.event.identifier}` specifies the identifier of an event in the TSL model. `/thing/lifecycle`: submits device lifecycle changes. `/thing/downlink/reply/message`: submits the response of a device to a request from IoT Platform. `/thing/list/found`: submits the data when a gateway detects a new sub-device. `/thing/topo/lifecycle`: submits device topology changes. `/thing/event/property/history/post`: submits the historical property data of a device. `/thing/event/${tsl.event.identifier}/history/post`: submits the historical event data of a device. `${tsl.event.identifier}` specifies the identifier of an event in the TSL model. `/ota/upgrade`: submits the over-the-air (OTA) update status of a device. `/ota/version/post`: submits OTA module versions. `/thing/deviceinfo/update`: submits device tag changes. `/edge/driver/${driver_id}/point_post`: submits pass-through data from Link IoT Edge. `${driver_id}` specifies the ID of the driver that a device uses to access Link IoT Edge. For the topic that is used to submit the status of OTA update batches, the format is `${packageId}/${jobId}/ota/job/status`. This topic belongs to the basic communication topics. `${packageId}` specifies the package ID. `${jobId}` specifies the update batch ID. For custom topics, an example is `${deviceName}/user/get`. You can call the QueryProductTopic operation to view all custom topics of the product. When you specify a custom topic, you can use the `+` and `#` wildcard characters. You can replace `${deviceName}` with the `+` wildcard character. The wildcard character specifies that the topic applies to all devices in the product. You can replace the fields that follow ${deviceName} with `/user/#`. The `#` wildcard specifies that the topic applies to all fields that follow`/user`. For more information about how to use wildcard characters, see Use custom topics. For topics that are used to submit device status changes, the format is `${deviceName}`. You can use the `+` wildcard character. In this case, the status changes of all devices under the product are submitted.
Where	String	No	Temperature>35	The condition that is used to trigger the rule. For more information about the rule, see SQL statements. Note This parameter specifies the fields in the WHERE clause. For example, if the WHERE statement is `WHERE a > 10`, set this parameter to `a>10`.
ProductKey	String	No	a1T27vz****	The ProductKey of the product to which the rule applies.
RuleDesc	String	No	rule test	The description of the rule. The description can be up to 100 characters in length.
DataType	String	No	JSON	The format of the data that is processed based on the rule. The value of this parameter must be consistent with the format of the device data that you want to process. Valid values: JSON (default): JSON data. BINARY: binary data. Note If you set this parameter to BINARY, you cannot set TopicType to 0 and cannot forward data to Tablestore and ApsaraDB RDS.
TopicType	Integer	No	1	0: the basic communication topic or TSL-based communication topic that is described in ShortTopic. The topic that is used to submit the status of OTA update batches belongs to the basic communication topics. 1: the custom topic. 2: the topic that is used to submit device status changes. The topic is expressed in the following complete format: `/as/mqtt/status/${productKey}/${deviceName}`.
ResourceGroupId	String	No	rg-acfmxazb4ph****	The resource group ID. Important IoT Platform supports only resource group management by instance. ResourceGroupId does not take effect. You no longer need to specify this parameter. The resource group that you specified when you called this operation before is still valid.
Topic	String	No	/sys/g18l***/device1/thing/event/property/post	The complete topic to which the rule applies. If you specify this parameter, you do not need to specify ShortTopic and TopicType.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information about common request parameters, see Common parameters.

Note

To enable a rule, you must specify ProductKey, ShortTopic, and Select.

Response parameters

Parameter	Type	Example	Description
Code	String	iot.system.SystemException	The error code returned if the request failed. For more information, see Error codes.
ErrorMessage	String	A system exception occurred.	The error message returned if the request failed.
RequestId	String	E4C0FF92-2A86-41DB-92D3-73B60310D25E	The request ID.
RuleId	Long	100000	The rule ID. If the request was successful, the rules engine generates a rule ID for the rule. Note Keep the rule ID confidential. You may need to provide the rule ID if you want to call rule-related operations.
Success	Boolean	true	Indicates whether the request was successful. Valid values: true false

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=CreateRule
&Name=iot_test1
&ProductKey=a1T27vz****
&ShortTopic=+/thing/event/property/post
&Select=deviceName() as deviceName, items.Humidity.value as Humidity, items.Temperature.value as Temperature
&RuleDesc=rule test
&DataType=JSON
&Where=Temperature>35
&TopicType=1
&<Common request parameters>

Sample success responses

XML format

<CreateRuleResponse>
      <RequestId>E4C0FF92-2A86-41DB-92D3-73B60310D25E</RequestId>
      <RuleId>100000</RuleId>
      <Success>true</Success>
</CreateRuleResponse>

JSON format

{
  "RequestId": "E4C0FF92-2A86-41DB-92D3-73B60310D25E", 
  "RuleId": 100000, 
  "Success": true
}

Error codes

For a list of error codes, see Service error codes.