All Products
Search
Document Center

IoT Platform:Functions

Last Updated:Dec 18, 2023

IoT Platform provides various functions that can be used in a parser script to process data. You can use the functions to convert data types, forward data to destinations, and process payloads of specific data types. This topic describes the functions provided by IoT Platform.

You can use the functions supported by Data Forwarding v1.0 in parser scripts of Data Forwarding v2.0. For more information, see Functions.

Convert data types

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.

Convert time formats

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.

Forward data to destinations

In the following functions, the destinationId parameter specifies the ID of a data destination and the payload parameter specifies the message content.

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.

The tag must be 1 to 128 characters in length. You can specify a constant or a variable in the tag.

  • The constant can contain letters and digits.

  • The variable specifies the value of a key in the JSON data that is parsed from payloads by using a script. If the value is unavailable, a tag is not added to the messages.

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 Message Service (MNS).

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.

The tag must be 1 to 128 characters in length. You can specify a constant or a variable in the tag.

  • The constant can contain letters and digits.

  • The variable specifies the value of a key in the JSON data that is parsed from payloads by using a script. If the value is unavailable, a tag is not added to the messages.

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.

Important If a device does not subscribe to the destination topic, the device cannot receive forwarded data.

For example, if you use MQTT.fx to connect Device A to IoT Platform, Device A cannot automatically subscribe to device topics. If Device B forwards data to the thing/service/property/set topic and Device A does not subscribe to the topic, Device A cannot receive the data that is forwarded by Device B.

For more information, see Automatic topic subscription.

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

Functions that are supported by each basic data type

  • Map

    Function

    Description

    [Object]

    Obtains the value of a specified key.

    size()

    Obtains the number of key-value pairs in a map.

    containsKey(String)

    Checks whether a map contains a specified key.

    keySet()

    Obtains keys in a map. An array is returned.

    remove(Object)

    Removes a key-value pair from a map based on a specified key.

    put(Object, Object)

    Adds key-value pairs to a map.

    putAll(map)

    Adds another map to an existing map.

  • Array

    Function

    Description

    [int]

    Obtains the value at a specified index. The index of the first element in an array is 0.

    contains(Object)

    Checks whether an array contains a specified element.

    remove(Object)

    Removes a specified element from an array.

    removeAt(int)

    Removes an element at a specified index in an array.

    add(Object)

    Adds an element to the end of an array.

    add(index, Object)

    Adds an element to a specified index.

    addAll(array)

    Adds another array to an array.

    size()

    Obtains the number of elements in an array.

  • String

    Function

    Description

    substring(start, end)

    Extracts a string from the start position to the end-1 position. If you do not configure the parameter, the extraction process continues until the end of the string.

    length()

    Queries the length of a string.

    split(String)

    Splits a string by using a specified separator.

    startsWith(String)

    Checks whether a string starts with a specified substring.

    endsWith(String)

    Checks whether a string ends with a specified substring.

    indexOf(String, index)

    Queries the position in which a substring first appears from a specified index of a string.

    The default value of the index parameter is 0.

Other functions

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.

The radix parameter is optional. Valid values:

  • 10 (default): converts a string into a decimal number.

  • 2: converts a string into a binary number.

  • 16: converts a string into a hexadecimal number.

Examples:

// 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);

References

If you want to forward data to a destination, you can write a script by using the supported syntax to call specific functions. For more information, see Script syntax.