CreateRuleAction - IoT Platform

Limits

Destination Alibaba Cloud services that are supported by the rules engine vary based on regions. For more information about the regions and destination cloud services that are supported by the rules 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 an IoT Platform topic, AMQP consumer group, or Alibaba Cloud service. The supported Alibaba Cloud services include Message Service (MNS), Function Compute, and Tablestore. If you need to forward data to ApsaraDB RDS, you must use the IoT Platform console.
Each Alibaba Cloud account can run a maximum of 50 queries per second (QPS).

Note RAM users of an Alibaba Cloud account share the quota of the account.

Debugging

Alibaba Cloud provides OpenAPI Explorer to simplify API usage. 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	null	The configurations of the rule action. You must specify a JSON string. The configurations vary based on the types of rule actions. 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 log on to the IoT Platform console, and choose Rules > Data Forwarding to view the rule ID. You can also call the ListRule operation and view the rule ID in the response.
Type	String	Yes	REPUBLISH	The type of the rule action. Valid values: REPUBLISH: forwards topic data that is processed by the rules engine to another IoT Platform topic. AMQP: forwards data to an AMQP consumer group. MNS: forwards data that is processed by the rules engine to Message Service (MNS). FC: forwards topic data that is processed by the rules engine to Function Compute for event computing. OTS: forwards data that is processed by the rules engine to OTS for NoSQL data storage. Note If you set the DataType parameter to BINARY, rules are created in the binary format. These rules cannot be used to forward data to Tablestore.
IotInstanceId	String	No	iot-cn-0pp1n8t****	The ID of the instance. You can view the instance ID on the Overview page in the IoT Platform console. Notice If your instance has an ID, you must configure this parameter. If you do not set this parameter, the call fails. If your instance has no Overview page or ID, you do not need to set this parameter. For more information, see Overview.
ErrorActionFlag	Boolean	No	false	Specifies whether the rule action forwards error operation data. Error operation data is generated when the rules engine failed to forward data from the IoT Platform topic to the destination cloud service. A data forwarding failure indicates that forwarding retries also fail. 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. You can specify a Thing Specification Language (TSL) communication topic or a custom topic. You can forward data to the following downstream TSL communication topics: `/sys/${YourProductKey}/${YourDeviceName}/thing/service/property/set/sys/${YourProductKey}/${YourDeviceName}/thing/service/${tsl.service.identifier}` Replace the ${tsl.service.identifier} variable with a service identifier that is defined in the TSL model.
topicType	The type of the topic. Valid values: 0: a downstream TSL communication topic. 1: a custom topic.

Examples


A system 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 DATAHUB type


Parameter	Description
projectName	The name of the DataHub project that is used to receive data.
topicName	The name of the DataHub topic that is used to receive data.
regionName	The code of the region in which DataHub is deployed. Example: cn-shanghai.
role	The information about the RAM role. You can grant IoT Platform the access to DataHub by assigning a service role to IoT Platform. The syntax of a RAM role: `{"roleArn":"acs:ram::6541*:role/aliyuniotaccessingdatahubrole","roleName": "AliyunIOTAccessingDataHubRole"}` Replace `6541*` with your Alibaba Cloud ID. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page. `AliyunIOTAccessingDataHubRole` indicates a service-linked role that is defined in RAM. This role is used to grant IoT Platform the access to DataHub. You can go to the RAM Roles page of the RAM console to manage RAM roles.
schemaVals	The schema of DataHub. For more information, see the following SchemaVals table.

schemaVals


Parameter	Description
name	The name of the column.
value	The value of the column.
type	The data type of the column. Valid values: BIGINT: big integer DOUBLE: double-precision float BOOLEAN: Boolean. TIMESTAMP: timestamp. STRING: string. DECIMAL: decimal.

Example


{
    "schemaVals": [
        {
            "name": "devicename",
            "value": "${deviceName}",
            "type": "STRING"
        },
        {
            "name": "msgtime",
            "value": "${msgTime}",
            "type": "TIMESTAMP"
        }
    ],
    "role": {
        "roleArn": "acs:ram::6541***:role/aliyuniotaccessingdatahubrole",
        "roleName": "AliyunIOTAccessingDataHubRole"
    },
    "projectName": "iot_datahub_stream",
    "topicName": "device_message",
    "regionName": "cn-shanghai"
}

The configurations of the OTS type


Parameter	Description
instanceName	The name of the Tablestore instance that is used to receive data.
tableName	The name of the table that is used to receive data.
regionName	The code of the region in which Tablestore is deployed. Example: cn-shanghai.
role	The information about the RAM role. You can grant IoT Platform the access to Tablestore by assigning a service role to IoT Platform. The syntax of a RAM role: `{"roleArn":"acs:ram::6541*:role/aliyuniotaccessingotsrole","roleName": "AliyunIOTAccessingOTSRole"}` Replace `6541*` with your Alibaba Cloud ID. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page. `AliyunIOTAccessingOTSRole` indicates a service-linked role that is defined in RAM. This role is used to grant IoT Platform the access to Tablestore. 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	Specifies whether the primary key is an auto-increment column. You can set the parameter to AUTO_INCREMENT or leave it empty. The primary key is an auto-increment column if the columnType and option parameters are respectively set to INTEGER and AUTO_INCREMENT.

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 data.
regionName	The code of the region in which MNS is deployed. Example: cn-shanghai.
role	The information about the RAM role. To grant IoT Platform the access to MNS, you can assign a service role to IoT Platform. The syntax of a RAM role: `{"roleArn":"acs:ram::6541*:role/aliyuniotaccessingmnsrole","roleName": "AliyunIOTAccessingMNSRole"}` Replace `6541*` with your Alibaba Cloud ID. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page. `AliyunIOTAccessingMNSRole` indicates a service-linked role that is defined in RAM. This role is used to grant IoT Platform 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 data.
serviceName	The name of the service that is used to receive data.
regionName	The code of the region in which Function Compute is deployed. Example: cn-shanghai.
role	The information about the RAM role. You can grant IoT Platform the access to Function Compute by assigning a service role to IoT Platform. The syntax of a RAM role: `{"roleArn":"acs:ram::6541*:role/aliyuniotaccessingfcrole","roleName": "AliyunIOTAccessingFCRole"}` Replace `6541*` with your Alibaba Cloud ID. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page. `AliyunIOTAccessingFCRole` indicates a service-linked role that is defined in RAM. 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 ONS type

Note You must call the SDK or use the console of Message Queue for Apache RocketMQ to grant IoT Platform the access to the service. IoT Platform must be authorized to publish messages to Message Queue for Apache RocketMQ. Then, you can create a rule action to forward data to the service.


Parameter	Description
instanceId	The ID of the Message Queue for Apache RocketMQ instance that is used to receive data.
topic	The name of the Message Queue for Apache RocketMQ topic that is used to receive data.
regionName	The code of the region in which Message Queue for Apache RocketMQ is deployed. Example: cn-shanghai. To forward data over the Internet in the same zone, you can use a common Message Queue for Apache RocketMQ instance. To forward data across zones, you must use a Message Queue for Apache RocketMQ Platinum Edition instance.
tag	Optional. The tag. The tag cannot exceed 128 bytes in length.
role	The information about the RAM role. You can grant IoT Platform the access to Message Queue for Apache RocketMQ by assigning a service role to IoT Platform. The syntax of a RAM role: `{"roleArn":"acs:ram::6541*:role/aliyuniotaccessingonsrole","roleName": "AliyunIOTAccessingONSRole"}` Replace `6541*` with your Alibaba Cloud ID. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page. `AliyunIOTAccessingONSRole` indicates a service-linked role that is defined in RAM. This role is used to grant IoT Platform the access to Message Queue for Apache RocketMQ. You can go to the RAM Roles page of the RAM console to manage RAM roles.

Example


{
    "instanceId": "MQ_INST_123157908552****_XXXXXX"
    "topic": "aliyun-iot-XXXXX",
    "regionName": "cn-hangzhou",
    "role": {
        "roleArn": "acs:ram::6541***:role/aliyuniotaccessingonsrole",
        "roleName": "AliyunIOTAccessingONSRole"
    }
}

The configurations of the AMQP type


Parameter	Description
groupId	The ID of the consumer group.

Example


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

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

Response parameters


Parameter	Type	Example	Description
ActionId	Long	10003	The ID of the action. The action ID is generated by the rules engine if the call is successful. Note Secure the information for future reference. When you call an operation that is related to the rule action, you must provide the action ID.
Code	String	iot.system.SystemException	The error code returned if the call fails. For more information, see Error codes.
ErrorMessage	String	A system exception occurred.	The error message returned if the call fails.
RequestId	String	21D327AF-A7DE-4E59-B5D1-ACAC8C024555	The ID of the request.
Success	Boolean	true	Indicates whether the call was successful. true: The call was successful. false: 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.