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 that are provided by IoT Platform.

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

Convert data types

Function Description
toBoolean(Object) Converts the value of the Object parameter to 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 to 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 to 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 to 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 based on 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 to 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 based on 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 to 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 to a time 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. If you do not configure this parameter, the time zone of the current system is used by default.
to_timestamp(dateString, patten, timeZone) Converts a time in a specified format to 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. If you do not configure this parameter, the time zone of the current system is used by default.

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 cannot be obtained, a tag is not added to the messages.
Forward data to an AMQP consumer group
writeFc(destinationId, data) Forwards data to Function Compute.

data: the data that is forwarded to Function Compute.

Forward data to Function Compute
writeMns(destinationId, payload) Forwards data to Message Service (MNS). Forward data to Message Service (MNS)
writeMq(destinationId, payload, tag) Forwards data to Message Queue for Apache RocketMQ.

tag: This parameter is optional. If you specify a tag, the tag is added to all messages that are forwarded to Message Queue for Apache 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 cannot be obtained, a tag is not added to the messages.
Forward data to Message Queue for Apache RocketMQ
writeTableStore(destinationId, data) Forwards data to Tablestore.

data: the data that is written to Tablestore. 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 Tablestore.

Forward data to Tablestore
writeRds(destinationId, data) Forwards data to ApsaraDB RDS.

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
writeTsdb(destinationId, timestamp, metricName, value, tag) Forwards data to ApsaraDB for Lindorm.
  • timestamp: the timestamp.
  • metricName: the name of the metric that is stored in Lindorm.
  • value: the value of the data point that is stored in Lindorm. The string and map data types are supported.
  • tag: the tag, which consists of a key-value pair. The data type is map.
Forward data to Time Series Database (TSDB)
writeIotTopic(destinationId, topic, payload) Forwards data to another topic.

Topic: the topic to which the data is forwarded. The ProductKey in the topic must be the same as the ProductKey that is specified when you specify the data destination. For more information, see Create a data destination.

Forward data to another topic

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.
    containKey(String) Checks whether a map contains a specified key.
    keySet() Obtains the 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 a map.
  • Array
    Function Description
    [int] Retrieves 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 at the end of an array.
    add(index, Object) Adds an element at a specified index.
    addAll(array) Adds another array to an array.
    size() Retrieves 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 end parameter, the extraction 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 where 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.

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 specify one or more fields in the function. Multiple fields must be specified based on levels. The function returns the value of the last field. If the last field does not exist or the value is empty, the function returns null.

Example of data:

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

Examples of the function:

  • 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 to a string by using the UTF-8 encoding. payload() is equivalent to payload('utf-8').
  • If you set the parameter to 'json', the message payload is converted to 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 to pass-through binary data.

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.