IoT Platform:Script syntax

Background information

IoT Platform processes and transmits data based on the data formats in topics. For more information, see Data formats.

The parser uses a JavaScript-like syntax. You can write parser scripts based on JavaScript syntax, but not all JavaScript syntax is supported. The following sections describe how to write a script.

Write a script

To write a script, perform the following steps:

1. Use the payload() function to obtain the data that is submitted by devices, and then convert the data to JSON-formatted data.

   var data = payload("json");

   Important The submitted data that you want to parse must be converted to JSON arrays or nested JSON data.
2. Define a field, and set the field to the property value that you obtained from the payload.
   • For more information about defining fields by using identifiers and setting data types, see the "Identifiers" and "Data types" sections.
   • You can use JSONPath expressions or the getOrNull() function to obtain field values. For more information, see LanguageManual UDF and getOrNull().

     For example, in the following sample script, you can use getOrNull(data, "items", "Humidity", "value"); to obtain the value 25, use data.items.Temperature.value to obtain the value 38, and use data.iotId to obtain the value JCp9***.

   Important When you use the script to obtain a specific field value from submitted device data:

   • If the identifier of the field starts with a digit, you must use the getOrNull() function. JSONPath expressions are not supported. For example, you can only use the getOrNull(data, "items", "2Co", "value") function in the sample script to obtain the value 10 of the 2Co field. The data.items.2Co.value expression is not supported.
   • If the field does not exist in the submitted device data, one of the following scenarios may occur:
     • If you use the getOrNull() function, null is returned and the script continues to run.
     • If you use a JSONPath expression, a null pointer appears and the script stops running.

   You can also process data or perform calculations based on your business requirements. For information about supported operators and functions, see Operators and Function list.

3. Use functions to forward data.

   For more information, see Functions to forward data to data destinations.

   You can also use control statements to set data forwarding conditions. In the following sample script, the if statement sets a condition. For more information about supported control statements, see the "Control statements" section.

Sample script

The following sample property data is submitted:

{
    "deviceType": "CustomCategory",
    "iotId": "JCp9***",
    "requestId": "1626948228247",
    "checkFailedData": {

    },
    "productKey": "a1o***",
    "gmtCreate": 1626948134445,
    "deviceName": "Device1",
    "items": {
        "Temperature": {
            "value": 38,
            "time": 1626948134319
        },
        "Humidity": {
            "value": 25,
            "time": 1626948134319
        },
        "2Co": {
            "value": 10,
            "time": 1626948134319
        }
    }
}

The following script parses and processes the submitted data:

// Use the payload() function to obtain the data that is submitted by devices and convert the data to JSON-formatted data. 
var data = payload("json"); 
// Filter the submitted temperature and humidity values. 
var h = getOrNull(data, "items", "Humidity", "value");
var t = data.items.Temperature.value;
var c = getOrNull(data, "items", "2Co", "value");
// Configure a data forwarding rule. If the temperature value is greater than 38, the rule is triggered to send data to ApsaraDB RDS. 
// An ApsaraDB RDS table includes the following columns: id (auto-increment primary key), deviceName, temperature, humidity, 2Co, and time. You can call the writeRds() method and specify multiple <Column name>:<Value> pairs in the method to write the values to the specified columns. 
if (t > 38) { 
    writeRds(1000, {"deviceName":deviceName(), "temperature":t, "humidity":h, "2Co":c, "time":timestamp()});  
}

Identifiers

Identifiers are used to define constants, variables, and custom fields in the script. An identifier can contain letters, digits, and underscores (_), but cannot start with a digit.

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 script supports the following data types for constants, variables, and custom fields: number, Boolean, string, byte, map, and array.

Constants can be null. Supported numeric constant types 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.

Operators

• Logical operators: && and ||.

  In logical conditions, a null value evaluates to false and all other values evaluate to true. For example, null && "x" returns false, and null || "x" returns true.

• Mathematical operators: *, /, %, +, and -.

  Only numeric data types are supported. Using other types causes an error.

• Comparison operators: >, =>, <, <=, ==, and !=. The == comparison operator supports only numeric values.

Comments

The script supports multi-line comments (/* ${comments}*/) and single-line comments (// ${comments}).

References

• For information about supported functions, see Function list.
• For more examples on configuring parser scripts to forward data, see the Data forwarding examples directory.