Create a Rule Action

Function

This API is used by an application to create a rule action on the IoT platform.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

POST /v5/iot/{project_id}/routing-rule/actions

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Parameter description: project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	Parameter description: user token. You can obtain the token by calling the IAM API Obtaining a User Token Through Password Authentication. X-Subject-Token in the response header returned by the API is the desired user token. For details about how to obtain the token, see Token Authentication.
Instance-Id	No	String	Parameter description: instance ID. This parameter is required only when the API is called from the management plane in the physical multi-tenant scenario. You can log in to the IoTDA console and choose Overview in the navigation pane to view the instance ID.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
rule_id	Yes	String	Parameter description: unique ID of a rule triggering condition. The value is allocated by the platform during rule creation. Value: The value can contain a maximum of 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
channel	Yes	String	Parameter description: type of the rule action. Options: HTTP_FORWARDING: HTTP service message forwarding. DIS_FORWARDING: DIS service message forwarding. OBS_FORWARDING: OBS service message forwarding. AMQP_FORWARDING: AMQP service message forwarding. DMS_KAFKA_FORWARDING: Kafka message forwarding. INFLUXDB_FORWARDING: InfluxDB message forwarding. MYSQL_FORWARDING: MySQL message forwarding. FUNCTIONGRAPH_FORWARDING: FunctionGraph message forwarding.
channel_detail	Yes	ChannelDetail object	Parameter description: channel parameters.

**Table 4** ChannelDetail
Parameter	Mandatory	Type	Description
http_forwarding	No	HttpForwarding object	Parameter description: HTTP server message forwarding. This parameter is mandatory when channel is set to HTTP_FORWARDING.
dis_forwarding	No	DisForwarding object	Parameter description: DIS service message forwarding. This parameter is mandatory when channel is set to DIS_FORWARDING.
obs_forwarding	No	ObsForwarding object	Parameter description: OBS service message forwarding. This parameter is mandatory when channel is set to OBS_FORWARDING.
amqp_forwarding	No	AmqpForwarding object	Parameter description: AMQP service message forwarding. This parameter is mandatory when channel is set to AMQP_FORWARDING.
dms_kafka_forwarding	No	DmsKafkaForwarding object	Parameter description: Kafka message forwarding. This parameter is mandatory when channel is set to DMS_KAFKA_FORWARDING.
mysql_forwarding	No	MysqlForwarding object	Parameter description: MySQL message forwarding. This parameter is mandatory when channel is set to MYSQL_FORWARDING.
influxdb_forwarding	No	InfluxDBForwarding object	Parameter description: InfluxDB forwarding configuration parameters. This parameter is mandatory when channel is set to INFLUXDB_FORWARDING.
functiongraph_forwarding	No	FunctionGraphForwarding object	Parameter description: FunctionGraph service message forwarding. This parameter is mandatory when channel is set to FUNCTIONGRAPH_FORWARDING.

**Table 5** HttpForwarding
Parameter	Mandatory	Type	Description
url	Yes	String	Parameter description: IP address of the HTTP server for receiving data that meets the rule triggering condition. HTTP is an insecure non-encrypted data transmission mode. You are advised to use HTTPS, which is more secure.
cert_id	No	String	Parameter description: certificate ID. For details about how to obtain a certificate ID, see step 3 in Loading the CA Certificate.
cn_name	No	String	Parameter description: If sni_enable is set to true, this parameter is mandatory and the value is the domain name of the server certificate, for example, domain:8443. If sni_enable is set to false, this parameter is left blank by default.
sni_enable	No	Boolean	Parameter description: The HTTPS server and client must support this function. The default value is false. If this parameter is set to true, the HTTPS client needs to carry cn_name when initiating a request. The HTTPS server returns the corresponding certificate based on cn_name. If this parameter is set to false, this function is disabled.
signature_enable	No	Boolean	Parameter description: whether to enable a signature. The token takes effect only when this parameter is set to true. You are advised to set this parameter to true to use the token signature to check whether messages are from the platform.
token	No	String	Parameter description: Token used to generate a signature. The client can use the token to generate a signature based on rules and compare the signature with that carried in the push message for security verification. Value: The value can contain 3 to 32 characters. Only letters and digits are allowed. For details, see [Token-based IoT Platform Authentication for HTTP/HTTPS Subscription/Push].

**Table 6** DisForwarding
Parameter	Mandatory	Type	Description
region_name	Yes	String	Parameter description: region where the DIS service is deployed.
project_id	Yes	String	Parameter description: ID of the project to which the DIS service belongs.
stream_name	No	String	Parameter description: DIS stream name. Either stream_id or stream_name must be carried. If both parameters are carried, stream_id is used.
stream_id	No	String	Parameter description: DIS stream ID. Either stream_id or stream_name must be carried. If both parameters are carried, stream_id is used.

**Table 7** ObsForwarding
Parameter	Mandatory	Type	Description
region_name	Yes	String	Parameter description: region where the OBS service is deployed.
project_id	Yes	String	Parameter description: ID of the project to which the OBS service belongs.
bucket_name	Yes	String	Parameter description: OBS bucket name.
location	No	String	Parameter description: region where the OBS bucket is deployed.
file_path	No	String	Parameter description: custom directory to store files that will be dumped to OBS. Different directory levels are separated by slashes (/). The directory cannot start or end with a slash (/) or contain two or more consecutive slashes (/). Value: The value can contain a maximum of 256 characters. Only letters (a–z and A–Z), digits (0–9), underscores (_), hyphens (-), slashes (/), and braces ({}) are allowed. Braces can be used only for template parameters. Template parameters: {YYYY}: year {MM}: month {DD}: day {HH}: hour {appId}: application ID {deviceId}: device ID For example, if the custom directory structure is {YYYY}/{MM}/{DD}/{HH}, data is generated in the corresponding directory structure 2021>08>11>09 based on the current time during data forwarding.

**Table 8** AmqpForwarding
Parameter	Mandatory	Type	Description
queue_name	Yes	String	Parameter description: AMQP queue for receiving data that meets the rule triggering condition.

**Table 9** DmsKafkaForwarding
Parameter	Mandatory	Type	Description
region_name	Yes	String	Parameter description: region where the Kafka service is deployed.
project_id	Yes	String	Parameter description: ID of the project to which the Kafka service belongs.
addresses	Yes	Array of SupportPrivateLinkNetAddress objects	Parameter description: list of addresses for Kafka message forwarding.
topic	Yes	String	Parameter description: topic associated with the message to be forwarded to Kafka.
username	No	String	Parameter description: username associated with the message to be forwarded to Kafka.
password	No	String	Parameter description: password associated with the message to be forwarded to Kafka.
mechanism	No	String	Parameter description: SASL authentication mechanism associated with the message to be forwarded to Kafka. Options: PAAS: In this mode, data is not encrypted and transmitted in plaintext, which is insecure. You are advised to use a more secure data encryption mode. PLAIN: SASL/PLAIN authentication. You must enter the username and password. It is a simple username and password verification mechanism. It is not recommended in the SASL_PLAINTEXT scenario. SCRAM-SHA-512: SASL/SCRAM-SHA-512 authentication. You must enter the username and password. This mechanism uses the hash algorithm to generate credentials for usernames and passwords to verify identities. SCRAM-SHA-512 is more secure than PLAIN.
security_protocol	No	String	Parameter description: Kafka transmission security protocol. If this parameter is left blank, the default value SASL_SSL is used. This parameter does not take effect when mechanism is set to PAAS or left empty. Options: SASL_SSL: Data is encrypted with SSL certificates for high-security transmission. SASL_PLAINTEXT: Data is transmitted in plaintext with username and password authentication. It is recommended that mechanism is set to SCRAM-SHA-512.

**Table 10** SupportPrivateLinkNetAddress
Parameter	Mandatory	Type	Description
ip	No	String	Parameter description: IP address of the service.
port	No	Integer	Parameter description: Port number of the service.
domain	No	String	Parameter description: Domain name of the service.

**Table 11** MysqlForwarding
Parameter	Mandatory	Type	Description
address	Yes	NetAddress object	List of addresses to which the message is forwarded to ROMA.
db_name	Yes	String	Parameter description: name of the MySQL database to be connected. Value: The value can contain a maximum of 64 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
username	Yes	String	Parameter description: username of the MySQL database to be connected.
password	Yes	String	Parameter description: password of the MySQL database to be connected.
enable_ssl	No	Boolean	Parameter description: Whether the client uses SSL to connect to the server. The default value is true. If the value is false, the insecure non-encrypted data transmission mode is used. You are advised to use the SSL mode.
table_name	Yes	String	Parameter description: table name of the MySQL database.
column_mappings	Yes	Array of ColumnMapping objects	Parameter description: list of mappings between MySQL databases and the forwarding data. A maximum of 32 mappings are supported.

**Table 12** InfluxDBForwarding
Parameter	Mandatory	Type	Description
address	Yes	NetAddress object	Parameter description: addresses for InfluxDB message forwarding.
db_name	Yes	String	Parameter description: name of the InfluxDB database to be connected. The database will be automatically created if it does not exist.
username	Yes	String	Parameter description: username of the InfluxDB database to be connected.
password	Yes	String	Parameter description: password of the InfluxDB database to be connected.
measurement	Yes	String	Parameter description: measurement of the InfluxDB database. The measurement will be automatically created if it does not exist.
column_mappings	Yes	Array of ColumnMapping objects	Parameter description: list of mappings between InfluxDB databases and the forwarding data. A maximum of 32 mappings are supported.

**Table 13** NetAddress
Parameter	Mandatory	Type	Description
ip	No	String	Parameter description: IP address of the service.
port	No	Integer	Parameter description: port number of the service.
domain	No	String	Parameter description: domain name of the service.

**Table 14** ColumnMapping
Parameter	Mandatory	Type	Description
column_name	Yes	String	Parameter description: database column name.
json_key	Yes	String	Parameter description: attribute name of the data to be forwarded.

**Table 15** FunctionGraphForwarding
Parameter	Mandatory	Type	Description
func_urn	Yes	String	Parameter description: Function Uniform Resource Name (URN), which uniquely identifies a function.
func_name	Yes	String	Parameter description: function name.

Response Parameters

Status code: 201

**Table 16** Response body parameters
Parameter	Type	Description
action_id	String	Unique rule ID, which is allocated by the platform during rule creation. You do not need to carry this parameter when creating a rule.
rule_id	String	ID of the rule triggering condition corresponding to the rule action.
app_id	String	Resource space ID.
channel	String	Rule action type. Options: HTTP_FORWARDING: HTTP service message forwarding. DIS_FORWARDING: DIS service message forwarding. OBS_FORWARDING: OBS service message forwarding. AMQP_FORWARDING: AMQP service message forwarding. DMS_KAFKA_FORWARDING: Kafka message forwarding. INFLUXDB_FORWARDING: InfluxDB message forwarding. MYSQL_FORWARDING: MySQL message forwarding. FUNCTIONGRAPH_FORWARDING: FunctionGraph message forwarding.
channel_detail	ChannelDetail object	Channel configuration details.

**Table 17** ChannelDetail
Parameter	Type	Description
http_forwarding	HttpForwarding object	Parameter description: HTTP server message forwarding. This parameter is mandatory when channel is set to HTTP_FORWARDING.
dis_forwarding	DisForwarding object	Parameter description: DIS service message forwarding. This parameter is mandatory when channel is set to DIS_FORWARDING.
obs_forwarding	ObsForwarding object	Parameter description: OBS service message forwarding. This parameter is mandatory when channel is set to OBS_FORWARDING.
amqp_forwarding	AmqpForwarding object	Parameter description: AMQP service message forwarding. This parameter is mandatory when channel is set to AMQP_FORWARDING.
dms_kafka_forwarding	DmsKafkaForwarding object	Parameter description: Kafka message forwarding. This parameter is mandatory when channel is set to DMS_KAFKA_FORWARDING.
mysql_forwarding	MysqlForwarding object	Parameter description: MySQL message forwarding. This parameter is mandatory when channel is set to MYSQL_FORWARDING.
influxdb_forwarding	InfluxDBForwarding object	Parameter description: InfluxDB forwarding configuration parameters. This parameter is mandatory when channel is set to INFLUXDB_FORWARDING.
functiongraph_forwarding	FunctionGraphForwarding object	Parameter description: FunctionGraph service message forwarding. This parameter is mandatory when channel is set to FUNCTIONGRAPH_FORWARDING.

**Table 18** HttpForwarding
Parameter	Type	Description
url	String	Parameter description: IP address of the HTTP server for receiving data that meets the rule triggering condition. HTTP is an insecure non-encrypted data transmission mode. You are advised to use HTTPS, which is more secure.
cert_id	String	Parameter description: certificate ID. For details about how to obtain a certificate ID, see step 3 in Loading the CA Certificate.
cn_name	String	Parameter description: If sni_enable is set to true, this parameter is mandatory and the value is the domain name of the server certificate, for example, domain:8443. If sni_enable is set to false, this parameter is left blank by default.
sni_enable	Boolean	Parameter description: The HTTPS server and client must support this function. The default value is false. If this parameter is set to true, the HTTPS client needs to carry cn_name when initiating a request. The HTTPS server returns the corresponding certificate based on cn_name. If this parameter is set to false, this function is disabled.
signature_enable	Boolean	Parameter description: whether to enable a signature. The token takes effect only when this parameter is set to true. You are advised to set this parameter to true to use the token signature to check whether messages are from the platform.
token	String	Parameter description: Token used to generate a signature. The client can use the token to generate a signature based on rules and compare the signature with that carried in the push message for security verification. Value: The value can contain 3 to 32 characters. Only letters and digits are allowed. For details, see [Token-based IoT Platform Authentication for HTTP/HTTPS Subscription/Push].

**Table 19** DisForwarding
Parameter	Type	Description
region_name	String	Parameter description: region where the DIS service is deployed.
project_id	String	Parameter description: ID of the project to which the DIS service belongs.
stream_name	String	Parameter description: DIS stream name. Either stream_id or stream_name must be carried. If both parameters are carried, stream_id is used.
stream_id	String	Parameter description: DIS stream ID. Either stream_id or stream_name must be carried. If both parameters are carried, stream_id is used.

**Table 20** ObsForwarding
Parameter	Type	Description
region_name	String	Parameter description: region where the OBS service is deployed.
project_id	String	Parameter description: ID of the project to which the OBS service belongs.
bucket_name	String	Parameter description: OBS bucket name.
location	String	Parameter description: region where the OBS bucket is deployed.
file_path	String	Parameter description: custom directory to store files that will be dumped to OBS. Different directory levels are separated by slashes (/). The directory cannot start or end with a slash (/) or contain two or more consecutive slashes (/). Value: The value can contain a maximum of 256 characters. Only letters (a–z and A–Z), digits (0–9), underscores (_), hyphens (-), slashes (/), and braces ({}) are allowed. Braces can be used only for template parameters. Template parameters: {YYYY}: year {MM}: month {DD}: day {HH}: hour {appId}: application ID {deviceId}: device ID For example, if the custom directory structure is {YYYY}/{MM}/{DD}/{HH}, data is generated in the corresponding directory structure 2021>08>11>09 based on the current time during data forwarding.

**Table 21** AmqpForwarding
Parameter	Type	Description
queue_name	String	Parameter description: AMQP queue for receiving data that meets the rule triggering condition.

**Table 22** DmsKafkaForwarding
Parameter	Type	Description
region_name	String	Parameter description: region where the Kafka service is deployed.
project_id	String	Parameter description: ID of the project to which the Kafka service belongs.
addresses	Array of SupportPrivateLinkNetAddress objects	Parameter description: list of addresses for Kafka message forwarding.
topic	String	Parameter description: topic associated with the message to be forwarded to Kafka.
username	String	Parameter description: username associated with the message to be forwarded to Kafka.
password	String	Parameter description: password associated with the message to be forwarded to Kafka.
mechanism	String	Parameter description: SASL authentication mechanism associated with the message to be forwarded to Kafka. Options: PAAS: In this mode, data is not encrypted and transmitted in plaintext, which is insecure. You are advised to use a more secure data encryption mode. PLAIN: SASL/PLAIN authentication. You must enter the username and password. It is a simple username and password verification mechanism. It is not recommended in the SASL_PLAINTEXT scenario. SCRAM-SHA-512: SASL/SCRAM-SHA-512 authentication. You must enter the username and password. This mechanism uses the hash algorithm to generate credentials for usernames and passwords to verify identities. SCRAM-SHA-512 is more secure than PLAIN.
security_protocol	String	Parameter description: Kafka transmission security protocol. If this parameter is left blank, the default value SASL_SSL is used. This parameter does not take effect when mechanism is set to PAAS or left empty. Options: SASL_SSL: Data is encrypted with SSL certificates for high-security transmission. SASL_PLAINTEXT: Data is transmitted in plaintext with username and password authentication. It is recommended that mechanism is set to SCRAM-SHA-512.

**Table 23** SupportPrivateLinkNetAddress
Parameter	Type	Description
ip	String	Parameter description: IP address of the service.
port	Integer	Parameter description: Port number of the service.
domain	String	Parameter description: Domain name of the service.

**Table 24** MysqlForwarding
Parameter	Type	Description
address	NetAddress object	List of addresses to which the message is forwarded to ROMA.
db_name	String	Parameter description: name of the MySQL database to be connected. Value: The value can contain a maximum of 64 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
username	String	Parameter description: username of the MySQL database to be connected.
password	String	Parameter description: password of the MySQL database to be connected.
enable_ssl	Boolean	Parameter description: Whether the client uses SSL to connect to the server. The default value is true. If the value is false, the insecure non-encrypted data transmission mode is used. You are advised to use the SSL mode.
table_name	String	Parameter description: table name of the MySQL database.
column_mappings	Array of ColumnMapping objects	Parameter description: list of mappings between MySQL databases and the forwarding data. A maximum of 32 mappings are supported.

**Table 25** InfluxDBForwarding
Parameter	Type	Description
address	NetAddress object	Parameter description: addresses for InfluxDB message forwarding.
db_name	String	Parameter description: name of the InfluxDB database to be connected. The database will be automatically created if it does not exist.
username	String	Parameter description: username of the InfluxDB database to be connected.
password	String	Parameter description: password of the InfluxDB database to be connected.
measurement	String	Parameter description: measurement of the InfluxDB database. The measurement will be automatically created if it does not exist.
column_mappings	Array of ColumnMapping objects	Parameter description: list of mappings between InfluxDB databases and the forwarding data. A maximum of 32 mappings are supported.

**Table 26** NetAddress
Parameter	Type	Description
ip	String	Parameter description: IP address of the service.
port	Integer	Parameter description: port number of the service.
domain	String	Parameter description: domain name of the service.

**Table 27** ColumnMapping
Parameter	Type	Description
column_name	String	Parameter description: database column name.
json_key	String	Parameter description: attribute name of the data to be forwarded.

**Table 28** FunctionGraphForwarding
Parameter	Type	Description
func_urn	String	Parameter description: Function Uniform Resource Name (URN), which uniquely identifies a function.
func_name	String	Parameter description: function name.

Example Requests

Creates a rule action and pushes it to the HTTP server.

POST https://{endpoint}/v5/iot/{project_id}/routing-rule/actions

{
  "rule_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce0",
  "channel" : "HTTP_FORWARDING",
  "channel_detail" : {
    "http_forwarding" : {
      "url" : "http://host:port/callbackurltest"
    }
  }
}

Creates a rule action and pushes it to OBS.

POST https://{endpoint}/v5/iot/{project_id}/routing-rule/actions

{
  "rule_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce0",
  "channel" : "OBS_FORWARDING",
  "channel_detail" : {
    "obs_forwarding" : {
      "file_path" : "yourPath",
      "project_id" : "yourProjectId",
      "bucket_name" : "yourBucket_name",
      "region_name" : "yourRegion"
    }
  }
}

Creates a rule action and pushes it to an AMQP queue.

POST https://{endpoint}/v5/iot/{project_id}/routing-rule/actions

{
  "rule_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce0",
  "channel" : "AMQP_FORWARDING",
  "channel_detail" : {
    "amqp_forwarding" : {
      "queue_name" : "yourQueueName"
    }
  }
}

Creates a rule action and pushes it to a MySQL database.

POST https://{endpoint}/v5/iot/{project_id}/routing-rule/actions

{
  "rule_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce0",
  "channel" : "MYSQL_FORWARDING",
  "channel_detail" : {
    "mysql_forwarding" : {
      "address" : {
        "ip" : "yourIp",
        "port" : 3306
      },
      "username" : "userName",
      "password" : "passworld",
      "db_name" : "yourDBName",
      "table_name" : "yourTableName",
      "enable_ssl" : true,
      "column_mappings" : [ {
        "column_name" : "serviceId",
        "json_key" : "notify_data.body.services[0].service_id"
      } ]
    }
  }
}

Example Responses

Status code: 201

Created

{
  "action_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce1",
  "rule_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce0",
  "app_id" : "1a7ffc5cd89c44dd8265b1653d951ce0",
  "channel" : "HTTP_FORWARDING",
  "channel_detail" : {
    "http_forwarding" : {
      "url" : "http://host:port/callbackurltest"
    }
  }
}