IoT Platform:Functions

Function

Description

toBoolean(Object)

Converts the Object parameter into a Boolean value. The parameter supports the following data types:

• Boolean: The function returns the same value as the parameter.

• Number: If the parameter is set to 0, the function returns false. Otherwise, the function returns true.

• String: If the parameter is set to "true", the function returns true. Otherwise, the function returns false.

• If the parameter is set to NULL, the function returns false.

toNumber(Object)

Converts the value of the Object parameter into a number. The parameter supports the following data types:

• Boolean: If the parameter is set to true, the function returns 1. If the parameter is set to false, the function returns 0.

• Number: The function returns the same value as the parameter.

• String: The function parses the string to a number.

• If the parameter is set to NULL, the function returns 0.

toString(Object)

Converts the value of the Object parameter into a string.

If the parameter is set to a value other than NULL, the function returns the value as a string. If the parameter is set to NULL, the function returns an empty string.

If the parameter is of the binary type, the function returns a UTF-8 decoded value.

toMap(Object)

Converts the value of the Object parameter into a map. The parameter supports the following data types:

• Map: The function returns the same value as the parameter.

• String: The function parses the string to a map in the JSON format.

• If the parameter is set to NULL, the function returns an empty map.

toArray(Object)

Converts the value of the Object parameter into an array. The parameter supports the following data types:

• Array: The function returns the same value as the parameter.

• String: The function parses the string to an array in the JSON format.

• If the parameter is set to NULL, the function returns an empty array.

toBinary(Object)

Converts the value of the Object parameter into a binary value. The parameter supports the following data types:

• Binary: The function returns the same value as the parameter.

• String: The function returns a UTF-8 encoded value.

• If the parameter is set to NULL, the function returns an empty binary value.

Function

Description

format_date(timestamp, patten, timeZone)

Converts a timestamp in milliseconds into a time value in a specified format. A string is returned.

• timestamp: the timestamp in milliseconds.

• patten: the required time format. Example: yyyy-MM-dd HH:mm:ss.

• timeZone: the time zone. Examples: GMT, UTC, and CST. We recommend that you specify a time zone. If you do not configure the timeZone parameter, the function returns a time value in GMT+8.

to_timestamp(dateString, patten, timeZone)

Converts a time value in a specified format into a timestamp in milliseconds. A numeric value is returned.

• dateString: the time string.

• patten: the time format. Example: yyyy-MM-dd HH:mm:ss.

• timeZone: the time zone. Examples: GMT, UTC, and CST. We recommend that you specify a time zone. If you do not configure the timeZone parameter, the function returns a timestamp in GMT+8.

Function

Description

Example

writeAmqp(destinationId, payload, tag)

Forwards data to an Advanced Message Queuing Protocol (AMQP) consumer group.

tag: This parameter is optional. If you specify a tag, the tag is added to all messages that are forwarded to the AMQP consumer group.

Forward data to an AMQP consumer group

writeDatahub(destinationId, data)

Forwards data to DataHub.

data: the data that you want to write to DataHub. Only the map and binary data types are supported.

Forward data to DataHub

writeFc(destinationId, data)

Forwards data to Function Compute.

data: the data that you want to forward to Function Compute.

Forward data to Function Compute

writeKafka(destinationId, payload, key)

Forwards data to ApsaraMQ for Kafka.

key: the key that you want to specify in the messages to be forwarded to ApsaraMQ for Kafka. This parameter is optional

You can route messages based on the tags on your consumer client.

writeMns(destinationId, payload)

Forwards data to Simple Message Queue (formerly MNS) (SMQ).

Forward data to Message Service (MNS)

writeMq(destinationId, payload, tag)

Forwards data to ApsaraMQ for RocketMQ.

tag: This parameter is optional. If you specify a tag, the tag is added to all messages that are forwarded to ApsaraMQ for RocketMQ. You can filter messages based on tags on your consumer client.

Forward data to ApsaraMQ for RocketMQ

writeTableStore(destinationId, data, flowType)

Forwards data to Tablestore (OTS) instances of the Wide Column model.

• data: the data that you want to write to OTS. Only the map data type is supported. The key specifies the table column name and the value specifies the column value.

  The data parameter must contain the primary key of OTS.

• flowType: This parameter is optional. This parameter specifies the data type of fields that are not primary keys.

  • If the value of the flowType parameter is true, the system converts the values of non-primary-key fields into strings and then forwards the strings to OTS.

  • If you set the flowType parameter to false or do not configure the flowType parameter, the system forwards the values of non-primary-key fields to OTS but does not convert the data types.

Forward data to OTS instances of the Wide Column model

writeTableStoreTs(destinationId, timeInUs, metricName, tags, fields, dataSource)

Forwards data to OTS instances of the TimeSeries model.

• timeInUs: the timestamp when data was submitted. Unit: microseconds. Data type: integer.

• metricName: the name of a physical quantity or metric for data in a time series. Data type: string.

• tags: the tag of the time series Data type: map. The key and value of a tag are strings.

• fields: the data in the time series. Data type: map. Multiple data values can be specified at a specific point in time in a time series. Each value corresponds to a column in the time series table, including the column name and column value.

  Column names are strings, and column values can be of the Boolean, integer, floating-point, string, and binary data types.

• dataSource: the identifier of the data source that is used to generate the time series. Data type: string. Only this parameter can be left empty.

You can use this function to write data in a line of OTS. To write data in multiple lines at a time, use the following function:

writeTableStoreTs(destinationId, [
    {
        "timeInUs": timestamp() * 1000,
        "metricName": "name1",
        "tags":{},
        "fields":{},
        "dataSource": ""
    },
    {
        "timeInUs": timestamp() * 1000,
        "metricName": "name2",
        "tags":{},
        "fields":{},
        "dataSource": ""
    }
]);

For more information about the parameters, see Overview.

Forward data to OTS instances of the Wide Column model

writeRds(destinationId, data)

Writes data to an ApsaraDB RDS table.

data: the data that you want to write to ApsaraDB RDS. Only the map data type is supported. The key specifies the table column name and the value specifies the column value.

Forward data to ApsaraDB RDS

updateRds(destinationId, data, condition, limit)

Updates data that is written to an ApsaraDB RDS table.

• data: the data that you want to update for an ApsaraDB RDS table. Only the map data type is supported. The key specifies the table column name and the value specifies the column value.

• condition: the conditions that you want to configure to update data. This parameter is required. Only the string type is supported. The conditions are specified for the WHERE clause of an SQL statement. Example: a = 3 and b = 3.

• limit: The number of lines that can be returned by the function. Default value: 1. Maximum value: 50.

Examples:

• If multiple lines of data meet the conditions specified by the condition parameter, the function automatically updates data from the first line in the SQL result. If you set the limit parameter to 1, the function updates the data of the first line. If you set the limit parameter to 10, the function updates the data from the first line to the 10th line.

• If only one line of data meets the conditions specified by the condition parameter, the function updates only the line.

writeTsdb(destinationId, timestamp, metricName, value, tag)

Forwards data to Time Series Database.

• timestamp: the timestamp.

• metricName: the name of the metric in Time Series Database.

• value: the value of the data point in Time Series Database. The string and map data types are supported.

• tag: the tag that consists of a key-value pair. The data type is map.

Forward data to Time Series Database

writeIotTopic(destinationId, topic, payload)

Forwards data to another topic.

Topic: the destination topic to which you want to forward data. The following topics are supported:

• Custom topic: You must set the permission on the custom topic to subscribe. This allows devices to subscribe to the topic and obtain forwarded messages from the topic.

• Topic to which downstream TSL data is sent: /sys/${productKey}/${deviceName}/thing/service/property/set. IoT Platform forwards messages to this topic. The messages include commands to configure device properties. Devices receive the forwarded messages from the topic and configure device properties based on the payload of the messages. If you want to configure properties for the devices of the destination topic based on forwarded data, you can set the Topic parameter to this value.

The value of the ${productKey} variable must be the same as the ProductKey of the product that you specified in the destinationId parameter. You must specify a topic for the function. The topic name cannot contain wildcard characters.

For more information, see Create a data destination.

Forward data to another topic

writeLindorm(destinationId, timestamp, tags, fields)

Forwards data to Lindorm.

• timestamp: the timestamp when a data record was generated.

• tags: the tags. This parameter specifies object attributes for a metric. A tag consists of a tag key and a tag value. Data type: map.

• fields: the data records. A data record can include multiple field values, which indicate the objects of a metric. Data type: object.

Forward data to Lindorm

Function

Description

endWith(input, suffix)

Checks whether the input string ends with a specified suffix.

A Boolean value is returned.

productKey()

Returns the ProductKey of the current product.

getDeviceTag(key)

Returns the device tag value of a tag key. If the tag that contains the specified key is not attached to a device, no tag value is returned.

getOrNull(data, "items", ......)

Returns the value of a specified field in the JSON-formatted data parameter.

You can configure one or more fields in the function. Multiple fields must be configured based on levels. The function returns the value of the last field. If the last field does not exist or the field is empty, the function returns null.

Example of data:

"items": {
    "Humidity": {
        "value": 25,
        "time": 1626948134319
    }
}

Examples:

• getOrNull(data, "items"): returns the value of the items field "Humidity": {"value": 25,"time": 1626948134319}.

• getOrNull(data, "items", "Humidity", "value"): returns the value of the value field 25.

• getOrNull(data, "items", "Temperature"): returns the value null if the Temperature field does not exist.

payload(textEncoding)

Encodes the message payload that is sent by a device. The textEncoding parameter specifies an encoding scheme.

• If you do not configure the parameter, the message payload is converted into a UTF-8 encoded string. payload() is equivalent to payload('utf-8').

• If you set the parameter to 'json', the message payload is converted into a map. If the payload is not in the JSON format, an error occurs.

• If you set the parameter to 'binary', the message payload is converted into pass-through binary data.

parseNumber(numberString, radix)

Converts a string specified by the numberString parameter into a number based on a number system specified by the radix parameter.

// A device submits data. 
var content = '0xFF';
// The function obtains the string FF to be converted.
var x = content.substring(2);
// The function converts the string FF into a hexadecimal number. 
var value = parseNumber(x, 16);