Creates a rule action for a specified rule to forward processed data from a topic to another topic or a supported Alibaba Cloud service.

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

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 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 topic data that is processed by the rules engine to MNS
  • FC: forwards topic data that is processed by the rules engine to Function Compute for event computing
  • OTS: forwards topic data that is processed by the rules engine to Tablestore for NoSQL data storage
Note Rules of the binary data format (the DataType parameter is set to BINARY) do not support forwarding data to Tablestore.
IotInstanceId String No iot-cn-0pp1n8t****

The ID of the instance. This parameter is not required for the public instance but required for Enterprise Edition instances.

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.

topicTyp

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 account 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 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 account 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 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 of 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 account 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 role that is defined in RAM. 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 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 account 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 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 account 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 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 about common request parameters, see Common 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 request 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.