All Products
Search
Document Center

IoT Platform:CreateRule

Last Updated:Sep 15, 2023

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.