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

Query the Rule Action List

Function

This API is used by an application to query the rule action list 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

GET /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.

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

rule_id

No

String

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

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.

app_type

No

String

Parameter description: application scope of the tenant rule. Options:

  • GLOBAL: The rule takes effect for all resources under the tenant.

  • APP: The rule takes effect for resources in a resource space. If app_id is specified, rule actions in the specified resource space are queried. If app_id is not specified, rule actions in the default resource space are queried.

app_id

No

String

Parameter description: resource space ID. This parameter is optional. This parameter is valid only when rule_id is not carried and app_type is set to APP. If app_id is specified, rule actions in the specified resource space are queried. If app_id is not specified, rule actions in the default resource space are queried. Value: The value can contain a maximum of 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

limit

No

Integer

Parameter description: number of records to display on each page. By default, 10 records are displayed on each page. A maximum of 50 records can be displayed on each page. Value: The value is an integer ranging from 1 to 50. The default value is 10.

Minimum: 1

Maximum: 50

Default: 10

marker

No

String

Parameter description: ID of the last record in the previous query. The value is returned by the platform during the previous query. Records are queried in descending order of record IDs (the marker value). A newer record will have a larger ID. If marker is specified, only the records whose IDs are smaller than marker are queried. If marker is not specified, the query starts from the record with the largest ID, that is, the latest record. If all data needs to be queried in sequence, this parameter must be filled with the value of marker returned in the last query response each time. Value: The value is a string of 24 hexadecimal characters. The default value is ffffffffffffffffffffffff.

Default: ffffffffffffffffffffffff

offset

No

Integer

Parameter description: If offset is set to N, the query starts from the N+1 record after the last record in the previous query. The value is an integer ranging from 0 to 500. The default value is 0. If offset is set to 0, the output starts from the first record after the last record in the previous query. - To ensure API performance, you can use this parameter together with marker to turn pages. For example, if there are 50 records on each page, you can directly specify offset to jump to the specified page within page 1 and 11. If you want to view records displayed on pages 12 to 22, you need to use the marker value returned on page 11 as the marker value for the next query. Value: The value is an integer ranging from 0 to 500. The default value is 0.

Minimum: 0

Maximum: 500

Default: 0

Request Parameters

Table 3 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.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

actions

Array of RoutingRuleAction objects

Rule action list.

count

Integer

Total number of records that meet the query conditions.

marker

String

ID of the last record in this query, which can be used in the next query.

Table 5 RoutingRuleAction

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 6 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 7 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 8 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 9 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 10 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 11 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 12 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 13 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 14 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 15 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 16 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 17 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

Queries rule actions in a list.

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

Example Responses

Status code: 200

Successful response

{
  "actions" : [ {
    "rule_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce1",
    "action_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce0",
    "channel_detail" : {
      "amqp_forwarding" : {
        "queue_name" : "test"
      },
      "obs_forwarding" : {
        "file_path" : "device_property_report/{YYYY}/{MM}/{DD}/{HH}",
        "project_id" : "project_id",
        "bucket_name" : "bucket_name",
        "region_name" : "region_name",
        "location" : "location"
      },
      "http_forwarding" : {
        "sni_enable" : false,
        "cn_name" : "domain:8443",
        "cert_id" : "0ae892cfeff641158920300b2292d2ca",
        "url" : "http://host:port/callbackurltest"
      },
      "dis_forwarding" : {
        "stream_name" : "stream_name",
        "project_id" : "project_id",
        "stream_id" : "stream_id",
        "region_name" : "region_name"
      },
      "dms_kafka_forwarding" : {
        "addresses" : [ {
          "port" : 443,
          "ip" : "host",
          "domain" : "huawei.com"
        } ],
        "password" : "password",
        "project_id" : "project_id",
        "topic" : "topic",
        "region_name" : "region_name",
        "mechanism" : "PLAIN",
        "security_protocol" : "SASL_SSL",
        "username" : "username"
      }
    },
    "channel" : "HTTP_FORWARDING",
    "app_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce2"
  } ],
  "count" : 10,
  "marker" : "5c90fa7d3c4e4405e8525079"
}

Status Codes

Status Code

Description

200

Successful response

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

Error Codes

See Error Codes.