指令碼文法 - IoT Platform

物聯網平台提供的時序資料存放區規則，可加工處理裝置上報的自訂Topic資料進行儲存。時序資料存放區規則的能力包括擷取訊息內容、轉換資料格式、處理字串、組裝JSON格式資料、處理位元據等。本文介紹如何編寫時序資料存放區規則的指令碼。

背景資訊

配置自訂Topic資料存放區時，需添加對應的時序資料存放區規則來編輯指令碼，將加工處理後的資料存放區到物聯網平台的時序資料存放區空間。詳細內容，請參見配置自訂Topic資料存放區。

物聯網平台的時序資料存放區規則指令碼類似JavaScript語言，編輯指令碼的文法參考JavaScript文法即可。指令碼解析器僅支援JavaScript語言的部分文法，詳情見下文描述。

指令碼編寫說明

指令碼編寫方法如下：

通過payload函數，擷取裝置上報的訊息內容，並按照JSON格式轉換。
```
var data = payload("json");
```
重要
待處理的資料來源必須轉換為JSON格式資料，即數組或者嵌套的JSON資料。
定義欄位，然後篩選裝置上報的欄位資料，並賦值給定義的欄位。
- 定義欄位標識符和資料類型的規則，請參見本文下方的“標識符”和“資料類型”。
- 指令檔中支援使用JSONPath和函數getOrNull()擷取data中的欄位值。詳細的使用說明，請參見LanguageManual UDF和getOrNull()。
重要
在指令檔中擷取裝置資料中指定欄位值時：
- 若指定欄位的標識符以數字開頭，不支援直接使用JSONPath方法，需使用getOrNull()方法。例如本文“指令碼樣本”中的2C0，不能使用data.items.2Co.value，而是使用getOrNull(data, "items", "2Co", "value")擷取值10。
- 若指定欄位不存在，則：
  - 使用函數方法，會傳回值null，指令碼可繼續向下執行。
  - 使用JSONPath方法，指令碼會出現null 指標，中斷執行。
您也可根據需要處理和計算資料。指令碼中支援操作符和函數，請參見操作符和函數列表。

使用轉換函式convert2HotStorageData(fields, time)將上一步擷取的欄位資料進行標準格式轉換。

重要

fields中最多包含500個key。

轉換後的標準格式為：

{
    "key1": {
        "value": value1,
        "time": timestamp()
    },
    "key2": {
        "value": value2,
        "time": timestamp()
    }
}

您也可將擷取的欄位資料，按照標準格式組合，自訂每個欄位的time值。例如：

{
    "key1": {
        "value": value1,
        "time": 1626948134319
    },
    "key2": {
        "value": value2,
        "time": 1626948134000
    }
}

將轉換後的標準格式資料賦值給params，使用資料存放區函數writeHotStorage(params)進行儲存。
重要
同一時序資料存放區規則下，同一欄位key對應value的資料類型必須保持不變。若發生改變（例如：int32類型改為text類型），則新資料的寫入會失敗，且無法再查詢歷史儲存資料。
您也可使用流程式控制制語句，設定資料存放區的更多過濾條件。指令碼支援的控制語句，請參見本文下方的“流程式控制制語句”。

指令碼樣本

裝置上報資料樣本：

{
    "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
        }
    }
}

對應指令碼樣本：

儲存資料使用系統目前時間：

//通過payload函數，擷取裝置上報的訊息內容，並按照JSON格式轉換。
var data = payload("json"); 
//篩選出上報的溫濕度值。
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);

儲存資料使用自訂時間：

//通過payload函數，擷取裝置上報的訊息內容，並按照JSON格式轉換。
var data = payload("json"); 
//篩選出上報的溫濕度值。
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);

標識符

代碼中常量、變數和其他自訂欄位，需使用標識符定義。標識符支援大小寫英文字母、數字和底線（_），不能以數字開頭，長度限制為30個字元。

以下關鍵詞和保留字不能作為標識符使用。

關鍵詞：for、break、continue、if、else、true、false、var、new、null和return。
保留字：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、yield。

資料類型

代碼中常量、變數和其他自訂欄位支援資料類型有：int32（32為整型）、float（單精確度浮點型）、double（雙精確度浮點型）、text（字串）和struct（JSON對象）。

常量可取值為null，數值型常量的取實值型別包括十進位整型、十六進位整型和浮點型。

流程式控制制語句

物聯網平台支援使用for迴圈和if...else條件陳述式。其中for迴圈，支援使用關鍵詞break（跳出迴圈）和continue（跳出本次迴圈）。

重要

若使用for語句迴圈執行流轉函數，迴圈次數不能超過100。

操作符

邏輯運算：&&、||。
邏輯條件結果為非布爾型時，null（空值）表示false，否則為true。例如null && "x" 返回false，null || "x"返回true。
數學運算：*、/、%、+、-。
操作資料必須為數值型，否則會拋出異常。
條件判斷：>、=>、<、<=、==（僅支援值比較）、!=。

注釋

指令碼中支援多行注釋（/* ${comments}*/）和單行注釋（// ${comments} ）。