IoT Platform:Script syntax

Background information

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

The parser provided by IoT Platform uses a syntax that is similar to the JavaScript syntax. You can write the parser script based on the JavaScript syntax. However, the parser does not support all JavaScript syntax. The following section describes how to write a script.

Write a script

You can perform the following steps to write a script:

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 how to define a field by using the identifier and how to set the data type, see "Identifiers" and "Data types" sections.
   • You can use JSONPath expressions or the getOrNull() function in a script to obtain field values. For more information about how to use the JSONPath expressions or the getOrNull() function, see LanguageManual UDF and getOrNull().

     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 want to use the script to obtain a specific field value from the 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 whose value you want to obtain does not exist in the submitted device data, one of the following scenarios may occur:
     • If you use the getOrNull() function, the value null is returned and the script can continue 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 the operators and functions supported in the parser script, see Operators and Functions.

3. Use functions to forward data.

   For more information about such functions, see Forward data to destinations.

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

Sample script

The following 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 is used to parse and process 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

You must use identifiers to define constants, variables, and custom fields in the script. An identifier can contain letters, digits, and underscores (_). But the identifier 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

Number, Boolean, string, byte, map, and array are the supported data types of constants, variables, and custom fields in the script.

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.

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.

References

• For information about the functions supported in the script, see Functions.
• For more examples on how to configure parser scripts to forward data, see the documentation in the Data forwarding examples directory.