Script syntax - IoT Platform - Alibaba Cloud Documentation Center

Alibaba Cloud's IoT Platform offers rules for time-series data storage, enabling the processing and storage of custom topic data from devices. These rules facilitate the retrieval of message content, transformation of data formats, string processing, JSON data assembly, and binary data handling. This topic outlines the scriptwriting process for time-series data storage rules.

Background information

To configure custom topic data storage, it is necessary to implement time-series data storage rules for editing scripts and storing the processed data within the IoT Platform's time-series data storage. For more information, see Configure Custom Topic Data Storage.

The IoT Platform's time-series data storage rule script is akin to JavaScript, allowing you to apply JavaScript syntax for script editing. Note that the parser supports only a subset of JavaScript syntax. For a detailed description, refer to the sections below.

Write a script

Follow these steps to write a script:

Utilize the payload() function to retrieve device-submitted data and convert it into JSON format.
```
var data = payload("json");
```
Important
Ensure the data source is converted into JSON format, either as an array or nested JSON.
Define fields to filter and assign device-reported field data.
- Refer to the "Identifiers" and "Data Types" sections for guidance on defining a field using an identifier and setting its data type.
- The script file allows the use of JSONPath and the getOrNull() function to retrieve field values from the data. For comprehensive instructions on how to use these features, refer to LanguageManual UDF and getOrNull().
Important
To retrieve a specific field value from device data using the script:
- When the identifier of a specified field begins with a number, JSONPath cannot be applied directly. Instead, the getOrNull() method must be used. As illustrated in the "Sample script" section of this topic, 2C0 should not be accessed with data.items.2Co.value; rather, one should use getOrNull(data, "items", "2Co", "value") to retrieve the value 10.
- If the desired field is absent:
  - Invoking the function method returns a null value, allowing the script to proceed with execution.
  - Using JSONPath results in a null pointer, halting the script.
Further data processing or calculations can be performed as per business needs. The script supports various operators and functions. For more details, see Operators and Function List.
Utilize the transformation function convert2HotStorageData(fields, time) to standardize the field data acquired from the preceding step.

Important
The fields may include a maximum of 500 keys.
The standard format after conversion is:
```
{
    "key1": {
        "value": value1,
        "time": timestamp()
    },
    "key2": {
        "value": value2,
        "time": timestamp()
    }
}
```
Additionally, you can merge the retrieved field data into a standard format and tailor the time value for each respective field. For instance:
```
{
    "key1": {
        "value": value1,
        "time": 1626948134319
    },
    "key2": {
        "value": value2,
        "time": 1626948134000
    }
}
```
Assign the data, once converted to the standard format, to params, and utilize the writeHotStorage(params) function to store it.

Important
Within the same time-series data storage rule, the data type associated with the key must remain consistent for the corresponding value. Any alteration in data type (such as changing from int32 to text) will prevent new data from being written and historical data from being retrieved.

Control statements can be used to apply additional filter conditions for data storage. For supported control statements in the parser script, refer to the "Control Statements" section.

Sample script

Example of device-reported data:

{
    "deviceType": "CustomCategory",
    "iotId": "JCp9***",
    "requestId": "1626948228247",
    "productKey": "a1o***",
    "gmtCreate": 1626948134445,
    "deviceName": "Device1",
    "items": {
        "Temperature": {
            "value": 38,
            "time": 1626948134319
        },
        "Humidity": {
            "value": 25,
            "time": 1626948134319
        },
        "2Co": {
            "value": 10,
            "time": 1626948134319
        }
    }
}

Corresponding script example:

Storing data with the current system time:

// Retrieve device-submitted data and convert to JSON format using the payload() function.
var data = payload("json"); 
// Extract temperature and humidity values submitted by the device.
var h = getOrNull(data, "items", "Humidity", "value");
var t = data.items.Temperature.value;
var c = getOrNull(data, "items", "2Co", "value");

var fields = {
    "h": h,
    "t": t,
    "c": c
}

var params = convert2HotStorageData(fields, timestamp());
writeHotStorage(params);

Storing data with a custom time:

// Retrieve device-submitted data and convert to JSON format using the payload() function.
var data = payload("json"); 
// Extract temperature and humidity values submitted by the device.
var h = getOrNull(data, "items", "Humidity", "value");
var t = data.items.Temperature.value;
var c = getOrNull(data, "items", "2Co", "value");

var params = {
    "h": {
         "value": h,
         "time": 1626948134319
    },
    "t": {
         "value": t,
         "time": 1627048134319
     },
    "c": {
        "value": c,
        "time": 1628048134319
     }
}
writeHotStorage(params);

Identifiers

The following keywords and reserved words cannot be used as identifiers:

Keywords: for, break, continue, if, else, true, false, var, new, null, and return.
Reserved words: breakdo, instanceof, typeof, case, catch, finally, void, switch, while, debugger, function, this, with, default, throw, delete, in, try, as, from, classenum, extends, super, const, export, import, await, implementslet, let, private, public, interface, package, protected, static, and yield.

Data types

The value of a constant can be null. The supported data types of numeric constants include decimal integer, hexadecimal integer, and floating point.

Control statements

IoT Platform supports for and if...else statements. for statements support the break and continue keywords.

Important

When utilizing the for statement to iterate within a flow function, ensure that the loop count does not surpass 100.

Operators

Logical operators: && and ||.
For non-Boolean values that are specified in logical conditions, a value of null indicates false and other values indicate true. For example, null && "x" returns false, and null || "x" returns true.
Mathematical operators: *, /, %, +, and -.
Only numeric data types are supported. Otherwise, an error occurs.
Comparison operators: >, =>, <, <=, ==, and !=. The == comparison operator supports only numeric values.

Comments

Multi-line comments (/* ${comments}*/) and single-line comments (// ${comments}) are supported.