Creates a rule action based on a specified rule to forward processed messages from topics to other IoT Platform topics or supported Alibaba Cloud services.

Limits

  • Destination Alibaba Cloud services that are supported by the rule engine vary based on regions. For more information about the regions and destination cloud services that are supported by the rule engine, see Regions and zones.
  • You can create a maximum of 10 rule actions for each rule.
  • You can call this API operation to define rule actions to forward data to IoT Platform topics and Alibaba cloud services such as Datahub, Message Service, Function Compute, Table Store, and Message Queue for Apache RocketMQ. If you want to forward data to Time Series Database (TSDB) and ApsaraDB for RDS, you must use the IoT Platform console.

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 CreateRuleAction

The operation that you want to perform. Set the value to CreateRuleAction.

Configuration String Yes {"topic":"/a1POX0c****/device1/user/get","topicType":1}

The configurations of the rule action. You must specify a JSON string. The configurations for different types of rule actions are different. For more information about required syntax and examples, see the following tables.

RuleId Long Yes 100000

The ID of the rule for which you want to create an action. You can use either of the following methods to view the rule ID: 1. Log on to the IoT Platform console and choose Rules>Data Forwarding. 2. Call the ListRule operation.

Type String Yes REPUBLISH

The type of the rule action. Valid values:

  • MNS: forwards data in the topics that have been processed by the rule engine to Message Service (MNS) for message transmission.
  • FC: forwards data in the topics that have been processed by the rule engine to Function Compute for event computing.
  • REPUBLISH: forwards data in the topics that have been processed by the rule engine to another IoT Platform topic.
  • AMQP: forwards data to AMQP consumer groups.
  • OTS: forwards data in the topics that have been processed by the rule engine to Table Store for NoSQL data storage.
Note
  • Rules of the binary data format (the DataType parameter is set toBINARY) do not support forwarding data to Table Store.
  • Destination Alibaba Cloud services that are supported by the rule engine vary based on regions. For more information about the regions and destination cloud services that are supported by the rule engine, see Regions and zones.
IotInstanceId String No iot_instc_pu****_c*-v64********

The ID of the instance. This parameter is not required for public instances. However, the parameter is required for the instances that you have purchased.

ErrorActionFlag Boolean No false

Indicates whether the rule action forwarded error operation data. Error operation data indicates that the rule engine failed to forward data from the IoT Platform topic to the destination cloud service. A data forwarding failure indicates that forwarding retries also failed. Valid values:

  • true: forwards error operation data.
  • false: forwards normal data instead of error operation data.

Default value: false.

The configurations of the REPUBLISH type

Parameter

Description

topic

The destination topic. The topic can be a pre-defined topic or custom topic. You can forward data to the following downstream topics:

/sys/${YourProductKey}/${YourDeviceName}/thing/service/property/set

/sys/${YourProductKey}/${YourDeviceName}/thing/service/${tsl.service.identifier}, where the value of the ${tsl.service.identifier} variable depends on the service that is defined in the product TSL.

topicType

The type of the topic.

0: indicates a downstream topic.

1: indicates a custom topic.

Examples


A pre-defined topic: {"topic":"/sys/a1TXXXXXWSN/xxx_cache001/thing/service/property/set","topicType":0}
A custom topic: {"topic":"/a1TXXXXXWSN/xxx_cache001/user/update","topicType":1}
			
The configurations of the OTS type

Parameter

Description

instanceName

The name of the Table Store instance that is used to receive information.

tableName

The name of the table that is used to receive information.

regionName

The name of the region in which Table Store is deployed. Example: cn-shanghai.

role

The information of the RAM role. You can grant IoT Platform the access to Table Store by assigning a RAM role to IoT Platform. The syntax of a RAM role is provided as follows:

{"roleArn":"acs:ram::6541***:role/aliyuniotaccessingotsrole","roleName": "AliyunIOTAccessingOTSRole"}

Replace 6541*** with your Alibaba Cloud account ID. You can log on to the Alibaba Cloud console and view the account ID on the Security Settings page.

AliyunIOTAccessingOTSRole indicates a service role defined in the RAM console. This role is used to grant IoT Platform the access to Table Store. You can go to the RAM Roles page of the RAM console to manage RAM roles.

primaryKeys

The list of primary keys in the destination table. For more information, see the following PrimaryKeys table.

PrimaryKeys

Parameter

Description

columnType

The data type of the primary key. Valid values:

INTEGER: integer.

STRING: string.

BINARY: binary.

columnName

The name of the primary key.

columnValue

The value of the primary key.

option

Indicates whether the primary key is an auto-increment column. Valid values: AUTO_INCREMENT and null. The primary key is an auto-increment column if the columnType and option parameter is set to INTEGER and AUTO_INCREMENT, respectively.

Example


{
    "instanceName": "testaaa",
    "tableName": "tt",
    "primaryKeys": [
        {
            "columnType": "STRING",
            "columnName": "ttt",
            "columnValue": "${tt}",
            "option": ""
        },
        {
            "columnType": "INTEGER",
            "columnName": "id",
            "columnValue": "",
            "option": "AUTO_INCREMENT"
        }
    ],
    "regionName": "cn-shanghai",
    "role": {
        "roleArn": "acs:ram::5645***:role/aliyuniotaccessingotsrole",
        "roleName": "AliyunIOTAccessingOTSRole"
    }
}
			
The configurations of the MNS type

Parameter

Description

themeName

The name of the MNS topic that is used to receive information.

regionName

The name of the region in which MNS is deployed. Example: cn-shanghai.

role

The information of the RAM role. You can grant IoT Platform the access to MNS by assigning a RAM role to IoT Platform. The syntax of a RAM role is provided as follows:

{"roleArn":"acs:ram::6541***:role/aliyuniotaccessingmnsrole","roleName": "AliyunIOTAccessingMNSRole"}

Replace 6541*** with your Alibaba Cloud account ID. You can log on to the Alibaba Cloud console and view the account ID on the Security Settings page.

AliyunIOTAccessingMNSRole indicates a service role defined in the RAM console. This role is used to grant IoT Platform the access to MNS. You can go to the RAM Roles page of the RAM console to manage RAM roles.

Example


{
    "themeName": "mns-test-topic1",
    "regionName": "cn-shanghai",
    "role": {
        "roleArn": "acs:ram::5645***:role/aliyuniotaccessingmnsrole",
        "roleName": "AliyunIOTAccessingMNSRole"
    }
}
			
The configurations of the FC type

Parameter

Description

functionName

The name of the function that is used to receive information.

serviceName

The name of the service that is used to receive information.

regionName

The name of the region in which Function Compute is deployed. Example: cn-shanghai.

role

The information of the RAM role. You can grant IoT Platform the access to Function Compute by assigning a RAM role to IoT Platform. The syntax of a RAM role is provided as follows:

{"roleArn":"acs:ram::6541***:role/aliyuniotaccessingfcrole","roleName": "AliyunIOTAccessingFCRole"}

Replace 6541*** with your Alibaba Cloud account ID. You can log on to the Alibaba Cloud console and view the account ID on the Security Settings page.

AliyunIOTAccessingFCRole is the service role specified in the RAM console. This role is used to grant IoT Platform the access to Function Compute. You can go to the RAM Roles page of the RAM console to manage RAM roles.

Example


{
    "regionName": "cn-shanghai",
    "role": {
        "roleArn": "acs:ram::5645***:role/aliyuniotaccessingfcrole",
        "roleName": "AliyunIOTAccessingFCRole"
    },
    "functionName": "weatherForecast",
    "serviceName": "weather"
}
			
The configurations of the AMQP type

Parameter

Description

groupId

The ID of the consumer group.

Example


{
    "groupId":"ZTh1JmyLGuZcUfv44p4z00****"
}
			

In addition to the preceding exclusive request parameters, you must specify common request parameters when calling this API operation. For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Example Description
ActionId Long 10003

The ID that is generated by the rule engine for the rule action if the call was successful. This parameter uniquely identifies an action.

Note Secure the information for future reference. When calling API operations related to rule actions, you may require the corresponding rule action IDs.
Code String iot.system.SystemException

The error code returned if the call failed. For more information about error codes, see Error codes.

ErrorMessage String A system exception occurred.

The error message returned if the call failed.

RequestId String 21D327AF-A7DE-4E59-B5D1-ACAC8C024555

The globally unique ID that is generated by Alibaba Cloud for the request.

Success Boolean true

Indicates whether the call was successful. true indicates that the call was successful. false indicates that the call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=CreateRuleAction
&RuleId=100000
&Type=REPUBLISH
&Configuration={"topic":"/a1POX0c****/device1/user/get","topicType":1}
&<Common request parameters>

Sample success responses

XML format

<CreateRuleActionResponse>
      <RequestId>21D327AF-A7DE-4E59-B5D1-ACAC8C024555</RequestId>
      <ActionId>10003</ActionId>
      <Success>true</Success>
</CreateRuleActionResponse>

JSON format

{
    "RequestId": "21D327AF-A7DE-4E59-B5D1-ACAC8C024555",
    "ActionId": 10003,
    "Success": true
}

Error codes.

For a list of error codes, visit the API Error Center.