Updated on 2024-06-27 GMT+08:00

Modify a Rule Action

Function

This API is used by an application to modify the configuration of a specific 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

PUT /v5/iot/{project_id}/routing-rule/actions/{action_id}

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.

action_id

Yes

String

Parameter description: rule action ID. Value: The value can contain a maximum of 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

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

channel

No

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

No

ChannelDetail object

Parameter description: channel configuration details.

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.

Minimum: 1

Maximum: 256

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.

Minimum: 1

Maximum: 64

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.

Minimum: 1

Maximum: 64

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].

Minimum: 3

Maximum: 32

Table 6 DisForwarding

Parameter

Mandatory

Type

Description

region_name

Yes

String

Parameter description: region where the DIS service is deployed.

Minimum: 1

Maximum: 256

project_id

Yes

String

Parameter description: ID of the project to which the DIS service belongs.

Minimum: 1

Maximum: 256

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.

Minimum: 1

Maximum: 256

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.

Minimum: 1

Maximum: 256

Table 7 ObsForwarding

Parameter

Mandatory

Type

Description

region_name

Yes

String

Parameter description: region where the OBS service is deployed.

Minimum: 1

Maximum: 256

project_id

Yes

String

Parameter description: ID of the project to which the OBS service belongs.

Minimum: 1

Maximum: 256

bucket_name

Yes

String

Parameter description: OBS bucket name.

Minimum: 1

Maximum: 256

location

No

String

Parameter description: region where the OBS bucket is deployed.

Minimum: 1

Maximum: 256

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.

Minimum: 8

Maximum: 256

Table 9 DmsKafkaForwarding

Parameter

Mandatory

Type

Description

region_name

Yes

String

Parameter description: region where the Kafka service is deployed.

Minimum: 1

Maximum: 256

project_id

Yes

String

Parameter description: ID of the project to which the Kafka service belongs.

Minimum: 1

Maximum: 256

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.

Minimum: 1

Maximum: 256

username

No

String

Parameter description: username associated with the message to be forwarded to Kafka.

Minimum: 1

Maximum: 256

password

No

String

Parameter description: password associated with the message to be forwarded to Kafka.

Minimum: 1

Maximum: 256

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.

Minimum: 0

Maximum: 65535

domain

No

String

Parameter description: Domain name of the service.

Minimum: 4

Maximum: 255

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.

Minimum: 1

Maximum: 256

password

Yes

String

Parameter description: password of the MySQL database to be connected.

Minimum: 1

Maximum: 256

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.

Default: true

table_name

Yes

String

Parameter description: table name of the MySQL database.

Minimum: 1

Maximum: 64

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.

Minimum: 1

Maximum: 64

username

Yes

String

Parameter description: username of the InfluxDB database to be connected.

Minimum: 1

Maximum: 256

password

Yes

String

Parameter description: password of the InfluxDB database to be connected.

Minimum: 1

Maximum: 256

measurement

Yes

String

Parameter description: measurement of the InfluxDB database. The measurement will be automatically created if it does not exist.

Minimum: 1

Maximum: 64

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.

Minimum: 0

Maximum: 65535

domain

No

String

Parameter description: domain name of the service.

Minimum: 4

Maximum: 255

Table 14 ColumnMapping

Parameter

Mandatory

Type

Description

column_name

Yes

String

Parameter description: database column name.

Minimum: 1

Maximum: 256

json_key

Yes

String

Parameter description: attribute name of the data to be forwarded.

Minimum: 1

Maximum: 256

Table 15 FunctionGraphForwarding

Parameter

Mandatory

Type

Description

func_urn

Yes

String

Parameter description: Function Uniform Resource Name (URN), which uniquely identifies a function.

Minimum: 0

Maximum: 65535

func_name

Yes

String

Parameter description: function name.

Minimum: 0

Maximum: 65535

Response Parameters

Status code: 200

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.

Minimum: 1

Maximum: 256

cert_id

String

Parameter description: certificate ID. For details about how to obtain a certificate ID, see step 3 in Loading the CA Certificate.

Minimum: 1

Maximum: 64

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.

Minimum: 1

Maximum: 64

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].

Minimum: 3

Maximum: 32

Table 19 DisForwarding

Parameter

Type

Description

region_name

String

Parameter description: region where the DIS service is deployed.

Minimum: 1

Maximum: 256

project_id

String

Parameter description: ID of the project to which the DIS service belongs.

Minimum: 1

Maximum: 256

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.

Minimum: 1

Maximum: 256

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.

Minimum: 1

Maximum: 256

Table 20 ObsForwarding

Parameter

Type

Description

region_name

String

Parameter description: region where the OBS service is deployed.

Minimum: 1

Maximum: 256

project_id

String

Parameter description: ID of the project to which the OBS service belongs.

Minimum: 1

Maximum: 256

bucket_name

String

Parameter description: OBS bucket name.

Minimum: 1

Maximum: 256

location

String

Parameter description: region where the OBS bucket is deployed.

Minimum: 1

Maximum: 256

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.

Minimum: 8

Maximum: 256

Table 22 DmsKafkaForwarding

Parameter

Type

Description

region_name

String

Parameter description: region where the Kafka service is deployed.

Minimum: 1

Maximum: 256

project_id

String

Parameter description: ID of the project to which the Kafka service belongs.

Minimum: 1

Maximum: 256

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.

Minimum: 1

Maximum: 256

username

String

Parameter description: username associated with the message to be forwarded to Kafka.

Minimum: 1

Maximum: 256

password

String

Parameter description: password associated with the message to be forwarded to Kafka.

Minimum: 1

Maximum: 256

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.

Minimum: 0

Maximum: 65535

domain

String

Parameter description: Domain name of the service.

Minimum: 4

Maximum: 255

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.

Minimum: 1

Maximum: 256

password

String

Parameter description: password of the MySQL database to be connected.

Minimum: 1

Maximum: 256

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.

Default: true

table_name

String

Parameter description: table name of the MySQL database.

Minimum: 1

Maximum: 64

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.

Minimum: 1

Maximum: 64

username

String

Parameter description: username of the InfluxDB database to be connected.

Minimum: 1

Maximum: 256

password

String

Parameter description: password of the InfluxDB database to be connected.

Minimum: 1

Maximum: 256

measurement

String

Parameter description: measurement of the InfluxDB database. The measurement will be automatically created if it does not exist.

Minimum: 1

Maximum: 64

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.

Minimum: 0

Maximum: 65535

domain

String

Parameter description: domain name of the service.

Minimum: 4

Maximum: 255

Table 27 ColumnMapping

Parameter

Type

Description

column_name

String

Parameter description: database column name.

Minimum: 1

Maximum: 256

json_key

String

Parameter description: attribute name of the data to be forwarded.

Minimum: 1

Maximum: 256

Table 28 FunctionGraphForwarding

Parameter

Type

Description

func_urn

String

Parameter description: Function Uniform Resource Name (URN), which uniquely identifies a function.

Minimum: 0

Maximum: 65535

func_name

String

Parameter description: function name.

Minimum: 0

Maximum: 65535

Example Requests

Modifies the action of a specified rule and pushes the rule to the HTTP server.

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

{
  "channel" : "HTTP_FORWARDING",
  "channel_detail" : {
    "http_forwarding" : {
      "url" : "http://host:port/callbackurltest"
    }
  }
}

Example Responses

Status code: 200

OK

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

Status Codes

Status Code

Description

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

Error Codes

See Error Codes.