調用某些物模型相關API時,請求參數或返回參數中包含參數ThingModelJson,該參數的取值格式為物模型功能定義在物聯網平台系統的儲存結構,與TSL中的資料結構有所不同。ThingModelJson中所有欄位按照key的字元排序。
物模型功能定義的限制說明,請參見產品與裝置中物模型功能定義限制。
資料結構
預設模組和自訂模組資料結構不同。
- 預設模組
{ "_ppk":{ "description":"test", "version":"159244410****" } "events":[], "productKey":"al12345****", "properties":[], "services":[], "functionBlocks":[{ "productKey":"al12345****", "functionBlockId":"location0", "functionBlockName":"定位模組0" }] }
參數 類型 說明 productKey String 物模型所屬產品的ProductKey。 _ppk String 物模型版本資訊。包含參數: - version:當前物模型版本號碼。僅發布後的正式版物模型才有此參數。
- description:當前預設模組物模型版本的描述。僅發布後的正式版物模型才有此參數。
properties List 物模型中的屬性列表。關於屬性資料結構中包含的參數說明,請參見屬性資料結構規範。 每個屬性資料結構中,可以使用extendConfig來定義物模型擴充描述的配置,請參見extendConfig資料結構規範。當屬性無擴充描述時,無需傳入extendConfig。
services List 物模型中的服務列表。關於服務資料結構中包含的參數說明,請參見服務資料格式規範。 每個服務資料結構中,可以使用extendConfig來定義物模型擴充描述的配置,請參見extendConfig資料結構規範。當服務無擴充描述時,無需傳入extendConfig。
events List 物模型中的事件列表。關於事件數目據結構中包含的參數說明,請參見事件數目據格式規範。 每個事件數目據結構中,可以使用extendConfig來定義物模型擴充描述的配置,請參見extendConfig資料結構規範。當事件無擴充描述時,無需傳入extendConfig。
functionBlocks List 自訂模組列表。僅當產品下有自訂模組時,才包含該參數。包含參數: - productKey:物模型所屬產品的ProductKey。
- functionBlockId:物模型自訂模組標識符,在產品中具有唯一性。
- functionBlockName:物模型自訂模組名稱。
- 自訂模組
{ "productKey":"al12345****", "identifier":"location0", "name":"定位模組0", "properties":[], "services":[], "events":[], "description":"" }
自訂模組基本參數說明如下,其他參數說明與預設模組中相同。
參數 類型 說明 identifier String 物模型自訂模組標識符,在產品中具有唯一性。 支援英文大小寫字母、數字和底線(_),不超過30個字元。
name String 物模型的自訂模組名稱。 支援中文、英文字母、日文、數字和底線(_),長度限制為4~30個字元,一個中文、一個日文算1個字元。
description String 對模組進行說明或備忘。長度限制為100個字元。
屬性資料結構規範
以下表格展示屬性定義中需包含的參數和說明。
參數 | 類型 | 是否必需 | 說明 |
productKey | String | 是 | 物模型所屬產品的ProductKey。 |
createTs | Long | 否 | 功能建立的時間戳記,預設長度是13位。可手動傳入也可由系統產生。功能定義會根據該時間由小到大進行排序。 說明 存量物模型建立時間,以該物模型功能上線後第一次編輯為準。 |
identifier | String | 是 | 屬性的標識符。可包含大小寫英文字母、數字、底線(_),長度不超過50個字元。 說明 不能用以下詞彙作為標識符:set、get、post、property、event、time、value。 |
dataType | String | 是 | 屬性值的資料類型。 可選值:ARRAY、STRUCT、INT、FLOAT、DOUBLE、TEXT、DATE、ENUM、BOOL。 不同資料類型,可傳入的參數不同。詳情請參見本文中對應資料類型的資料規範章節。 |
name | String | 是 | 屬性名稱。可包含中文、大小寫英文字母、數字、短劃線(-)、底線(_)和半形句號(.),且必須以中文、英文字母或數字開頭,長度不超過30個字元,一個中文計為一個字元。 |
rwFlag | String | 是 | 在雲端可以對該屬性進行的操作類型。
|
dataSpecs | Object | 否 | 資料類型(dataType)為非列表型(INT、FLOAT、DOUBLE、TEXT、DATE、ARRAY)的資料規範儲存在dataSpecs中,請參見表格下方樣本。 說明
|
dataSpecsList | List | 否 | 資料類型(dataType)為列表型(ENUM、BOOL、STRUCT)的資料規範儲存在dataSpecsList中,請參見表格下方樣本。 說明
|
required | Boolean | 是 | 是否是標準品類的必選屬性。
|
custom | Boolean | 是 | 是否是自訂功能。
|
- dataType為INT的dataSpecs樣本:
{ "dataSpecs": { "custom": true, "dataType": "INT", "defaultValue": "30", "max": "1440", "min": "0", "step": "10", "unit": "min" } }
- dataType為TEXT的dataSpecs樣本:
{ "dataSpecs": { "custom": true, "dataType": "TEXT", "id": 2412127, "length": 2048 } }
- dataType為ARRAY的dataSpecs樣本:
{ "dataSpecs": { "childDataType": "INT", "custom": true, "dataType": "ARRAY", "size": 1 } }
- dataType為ENUM的dataSpecsList樣本:
{ "dataSpecsList": [ { "custom": false, "dataType": "ENUM", "defaultValue": "true", "name": "開啟", "value": 1 }, { "custom": false, "dataType": "ENUM", "defaultValue": "false", "name": "關閉", "value": 0 } ] }
- dataType為STRUCT的dataSpecsList樣本:
{ "childDataType": "TEXT", "childName": "卡編號", "dataSpecs": { "custom": true, "dataType": "TEXT", "length": 128 }, "dataType": "STRUCT", "identifier": "CardNo", "name": "NVR所擁有的晶片資訊" }
服務資料格式規範
以下表格展示服務定義中需包含的參數和說明。
參數 | 類型 | 是否必填 | 說明 |
productKey | String | 是 | 物模型所屬產品的ProductKey。 |
createTs | Long | 否 | 功能建立的時間戳記,預設長度是13位。可手動傳入也可由系統產生。功能定義會根據該時間由小到大進行排序。 說明 存量物模型建立時間,以該物模型功能上線後第一次編輯為準。 |
identifier | String | 是 | 服務的標識符。可包含大小寫英文字母、數字、底線(_),長度不超過50個字元。 說明 不能用以下詞彙作為標識符:set、get、post、property、event、time、value。 |
serviceName | String | 是 | 服務名稱。可包含中文、大小寫英文字母、數字、短劃線(-)、底線(_)和半形句號(.),且必須以中文、英文字母或數字開頭,長度不超過30個字元,一個中文計為一個字元。 |
inputParams | List | 否 | 服務的輸入參數。資料結構說明,請參見輸入、輸出參數結構規範。 |
outputParams | List | 否 | 服務的輸出參數。資料結構說明,請參見輸入、輸出參數結構規範。 |
required | Boolean | 是 | 是否是標準品類的必選服務。
|
callType | String | 是 | 服務的調用方式。
|
custom | Boolean | 是 | 是否是自訂功能。
|
事件數目據格式規範
以下表格展示事件定義中需包含的參數和說明。
參數 | 類型 | 是否必填 | 說明 |
productKey | String | 是 | 物模型所屬產品的ProductKey。 |
createTs | Long | 否 | 功能建立的時間戳記,預設長度是13位。可手動傳入也可由系統產生。功能定義會根據該時間由小到大進行排序。 說明 存量物模型建立時間,以該物模型功能上線後第一次編輯為準。 |
identifier | String | 是 | 事件的標識符。可包含大小寫英文字母、數字、底線(_),長度不超過50個字元。 說明 不能用以下詞彙作為標識符:set、get、post、property、event、time、value。 |
eventName | String | 是 | 事件名稱。可包含中文、大小寫英文字母、數字、短劃線(-)、底線(_)和半形句號(.),且必須以中文、英文或數字開頭,長度不超過30個字元,一個中文計為一個字元。 |
eventType | String | 是 | 事件類型。
|
outputdata | List | 否 | 事件的輸出參數。資料結構說明,請參見輸入、輸出參數結構規範。 |
required | Boolean | 是 | 是否是標準品類的必選事件。
|
custom | Boolean | 是 | 是否是自訂功能。
|
輸入、輸出參數結構規範
服務或事件中的輸入或輸出參數的資料結構規範如下。
參數 | 類型 | 是否必填 | 說明 |
dataType | String | 是 | 參數值的資料類型。 可選值:ARRAY、STRUCT、INT、FLOAT、DOUBLE、TEXT、DATE、ENUM、BOOL。 各資料類型的資料規範,請參見本文中對應資料類型的資料規範章節。 |
identifier | String | 是 | 參數的標識符。可包含大小寫英文字母、數字、底線(_),長度不超過50個字元。 說明 不能用以下詞彙作為標識符:set、get、post、property、event、time、value。 |
name | String | 是 | 參數名稱。可包含中文、大小寫英文字母、數字、短劃線(-)、底線(_)和半形句號(.),且必須以中文、英文字母或數字開頭,長度不超過30個字元,一個中文計為一個字元。 |
direction | String | 是 | 表示參數是輸入參數還是輸出參數。
|
paraOrder | Integer | 是 | 參數的序號。從0開始排序,且不能重複。 |
dataSpecs | Object | 否 | 資料類型(dataType)為非列表型(INT、FLOAT、DOUBLE、TEXT、DATE、ARRAY)的資料規範儲存在dataSpecs中。 說明
|
dataSpecsList | List | 否 | 資料類型(dataType)為列表型(ENUM、BOOL、STRUCT)的資料規範儲存在dataSpecsList中。 說明
|
custom | Boolean | 是 | 參數是否隸屬於自訂功能。
|
INT、FLOAT、DOUBLE類型資料結構規範
當功能或參數的資料類型為INT、FLOAT或DOUBLE時,資料結構中包含的參數如下。
參數 | 類型 | 是否必需 | 說明 |
dataType | String | 是 | 取值為INT、FLOAT或DOUBLE。 |
max | String | 是 | 最大值。取值為INT、FLOAT或DOUBLE,必須與dataType設定一致。 取值需轉為對應的STRING類型。例如,dataType為INT,取值為 |
min | String | 是 | 最小值。取值為INT、FLOAT或DOUBLE,必須與dataType設定一致。 取值需轉為對應的STRING類型,請參見max說明。 |
step | String | 是 | 步長,資料每次變化的增量。取值為INT、FLOAT或DOUBLE,必須與dataType設定一致。 取值需轉為對應的STRING類型,請參見max說明。 |
precise | String | 否 | 精度。當dataType取值為FLOAT或DOUBLE時,可傳入的參數。 |
defaultValue | String | 否 | 傳入此參數,可存入一個預設值。 |
unit | String | 是 | 單位的符號。 |
unitName | String | 是 | 單位的名稱。 |
custom | Boolean | 是 | 是否是自訂功能。
|
DATE、TEXT類型資料結構規範
當功能或參數的資料類型為DATE或TEXT時,資料結構中包含的參數如下。
參數 | 類型 | 是否必需 | 說明 |
dataType | String | 是 | 取值為DATE或TEXT。 |
length | Long | 是 | 資料長度,取值不能超過2048,單位:位元組。dataType取值為TEXT時,需傳入該參數。 |
defaultValue | String | 否 | 傳入此參數,可存入一個預設值。 |
custom | Boolean | 是 | 是否是自訂功能。
|
ARRAY類型資料規範
當功能或參數的資料類型為ARRAY時,資料結構中包含的參數如下。
參數 | 類型 | 是否必需 | 說明 |
dataType | String | 是 | 取值為ARRAY。 |
size | Long | 是 | 數組中的元素個數。 |
childDataType | String | 是 | 數組中的元素的資料類型。可選值:STRUCT、INT、FLOAT、DOUBLE或TEXT。 |
dataSpecs | Object | 否 | 資料類型(dataType)為非列表型(INT、FLOAT、DOUBLE、TEXT、DATE、ARRAY)的資料規範儲存在dataSpecs中。 說明
|
dataSpecsList | List | 否 | 資料類型(dataType)為列表型(ENUM、BOOL、STRUCT)的資料規範儲存在dataSpecsList中。 說明
|
custom | Boolean | 是 | 是否是自訂功能。
|
枚舉、布爾類型資料規範
當功能或參數的資料類型為BOOL或ENUM時,資料結構中包含的參數如下。
參數 | 類型 | 是否必需 | 說明 |
dataType | String | 是 | 取值為BOOL或ENUM。 |
name | String | 是 | 枚舉項的名稱,可包含中文、大小寫英文字母、數字、底線(_)和短劃線(-),且必須以中文、英文字母或數字開頭。長度不超過20個字元,一個中文計為一個字元。 |
value | Integer | 是 | 枚舉值。 |
custom | Boolean | 是 | 是否是自訂功能。
|
STRUCT類型資料結構規範
當功能或參數的資料類型為STRUCT時,資料結構中包含的參數如下。
- 參數childSpecsDTO、childEnumSpecsDTO已到期,對於已使用的API,不影響介面調用,此處不再說明;對於新調用的API,無需傳入已到期參數,建議使用參數dataSpecsList。
- ARRAY和STRUCT類型資料相互嵌套時,最多支援遞迴嵌套2層(父和子)。
參數 | 類型 | 是否必需 | 說明 |
dataType | String | 是 | 取值為STRUCT。 |
identifier | String | 是 | 結構體中的子參數的標識符。可包含大小寫英文字母、數字、底線(_),長度不超過50個字元。 說明 不能用以下詞彙作為標識符:set、get、post、property、event、time、value。 |
name | String | 是 | 結構體中的子參數名稱。可包含中文、大小寫英文字母、數字、短劃線(-)、底線(_)和半形句號(.),且必須以中文、英文字母或數字開頭,長度不超過30個字元,一個中文計為一個字元。 說明 該參數與childName定義相同,目前不使用。 |
childDataType | String | 否 | 結構體中子參數的資料類型。 可選值:INT、FLOAT、DOUBLE、TEXT、DATE、ENUM、BOOL。 |
childName | String | 是 | 結構體中的子參數名稱。可包含中文、大小寫英文字母、數字、短劃線(-)、底線(_)和半形句號(.),且必須以中文、英文字母或數字開頭,長度不超過30個字元,一個中文計為一個字元。 |
dataSpecs | Object | 否 | 資料類型(dataType)為非列表型(INT、FLOAT、DOUBLE、TEXT、DATE、ARRAY)的資料規範儲存在dataSpecs中。 說明
|
dataSpecsList | List | 否 | 資料類型(dataType)為列表型(ENUM、BOOL、STRUCT)的資料規範儲存在dataSpecsList中。 說明
|
custom | Boolean | 是 | 是否是自訂功能。
|
extendConfig資料結構規範
每個屬性、事件或服務資料結構中,可以使用extendConfig來定義物模型擴充描述的配置。擴充描述為裝置通訊協定到標準物模型的映射關係。
目前系統支援接入網關協議為Modbus、OPC UA或自訂的裝置配置擴充描述。不同類型的擴充描述需要滿足不同的資料規範:
Modbus類型
Modbus只支援屬性類型的物模型擴充描述。
{
"identifier":"extend1",
"writeFunctionCode":0,
"writeOnly":0,
"registerAddress":"0xFE",
"operateType":"coilStatus",
"scaling":0.1,
"pollingTime":1000,
"trigger":1,
"bitMask":128,
"originalDataType":{
"type":"uint64",
"specs":{
"swap":0,
"reverseRegister":0}
}
}
參數 | 類型 | 說明 |
identifier | String | 屬性唯一識別碼(產品下唯一)。 |
registerAddress | String | 寄存器地址,必須以0x 開頭,且限制範圍是0x0~0xFFFF,例如0xFE。 |
operateType | String | 操作類型,取值:
|
writeFunctionCode | Integer | 讀寫操作,對於不同操作類型(operateType),可選的取值不同:
|
writeOnly | Integer | 是否唯寫。
|
scaling | Number | 縮放因子,不能為0。 string、bool無該參數。 |
pollingTime | Integer | 採集間隔,單位是ms。無需傳入,將使用裝置配置的採集間隔。 |
trigger | Integer | 資料上報方式。1代表按時上報,2代表變更上報。 |
bitMask | Integer | bool特有的參數。 掩碼,取值:1、2、4、8、16、32、64、128、256、512、1024、2048、4096、8192、16384、32768,即1<<(0~15)。 |
originalDataType | Object | 未經處理資料類型描述。 |
type | String | 未經處理資料類型,需要為基礎類型:int16、uint16、int32、uint32、int64、uint64、float、double、string、bool、customized data(按大端順序返回hex data)。 |
specs | Object | 部分資料類型特有的參數。 |
registerCount | Integer | string、customized data特有的參數。 寄存器的資料個數。 |
swap | Integer | 除string、customized data外,其他資料類型特有的參數。 是否交換寄存器內高低位元組,把寄存器內16位元據的前後8個bit互換(byte1byte2 -> byte2byte1)。
|
reverseRegister | Integer | 除string、customized data外,其他資料類型特有的參數。 是否交換寄存器順序,把未經處理資料32位元據的前後16個bit互換(byte1byte2byte3byte4 -> byte3byte4byte1byte2)。
|
OPC UA類型
OPC UA支援屬性、服務、事件類型的物模型擴充描述。
{
"identifier":"extend2",
"displayName":"Action",
"inputData":[
{
"identifier":"xxxx",
"index":1
},
{
"identifier":"xxxx",
"index":2
}
],
"outputData":[
{
"identifier":"xxxx",
"index":1
},
{
"identifier":"xxxx",
"index":2
}
]
}
參數 | 類型 | 說明 |
identifier | String | 屬性、服務、事件的唯一識別碼(產品下唯一)。 |
displayName | String | 屬性、事件需要傳入displayName,服務不需要傳入。 |
inputData | List | 輸入資料。 |
outputData | List | 輸出資料。 |
identifier | String | 輸入資料、輸出資料的唯一識別碼(產品下唯一)。 |
index | Integer | 索引。inputData中的index不能重複,outputData中的index不能重複。 |
自訂類型
自訂類型支援屬性、服務、事件類型的物模型擴充描述。
{
"identifier":"xxx",
"customize":{}
}
參數 | 類型 | 說明 |
identifier | String | 屬性、服務、事件的唯一識別碼(產品下唯一)。 |
customize | Object | 自訂JSON。 |
校正
您可以通過json-schema對ThingModelJson中的入參進行預校正。
關於json-schema的定義代碼,請參見schema.json。
校正樣本如下:
- 在Maven工程中添加如下依賴,下載json-schema的版本庫。
<dependency> <groupId>com.github.everit-org.json-schema</groupId> <artifactId>org.everit.json.schema</artifactId> <version>1.11.0</version> </dependency>
- 範例程式碼:
package com.aliyun.iot.thingmodel; import java.io.InputStream; import java.net.URL; import java.util.ArrayList; import java.util.Arrays; import org.everit.json.schema.Schema; import org.everit.json.schema.ValidationException; import org.everit.json.schema.loader.SchemaLoader; import org.json.JSONObject; import org.json.JSONTokener; /** * @author: *** * @date: 2020-01-14 15:11 */ public class ThingModelJsonValidator { public static void main(String[] args) throws Exception { try (InputStream inputStream = new URL("https://iotx-thing-model-schema.oss-ap-southeast-1.aliyuncs.com/schema.json").openStream()) { JSONObject rawSchema = new JSONObject(new JSONTokener(inputStream)); Schema schema = SchemaLoader.load(rawSchema); long start = System.currentTimeMillis(); JSONObject object = new JSONObject(); String jsonStr = "{\n" + "\t\t\t\"productKey\": \"a1Q1Yrc****\",\n" + "\t\t\t\"name\": \"警示事件\",\n" + "\t\t\t\"identifier\": \"alarmEvent\",\n" + "\t\t\t\"eventName\": \"警示事件\",\n" + "\t\t\t\"eventType\": \"ALERT_EVENT_TYPE\",\n" + "\t\t\t\"outputData\": [\n" + "\t\t\t\t{\n" + "\t\t\t\t\t\"paraOrder\": 0,\n" + "\t\t\t\t\t\"direction\": \"PARAM_OUTPUT\",\n" + "\t\t\t\t\t\"dataSpecsList\": [\n" + "\t\t\t\t\t\t{\n" + "\t\t\t\t\t\t\t\"dataType\": \"ENUM\",\n" + "\t\t\t\t\t\t\t\"name\": \"防拆警示\",\n" + "\t\t\t\t\t\t\t\"value\": 0\n" + "\t\t\t\t\t\t},\n" + "\t\t\t\t\t\t{\n" + "\t\t\t\t\t\t\t\"dataType\": \"ENUM\",\n" + "\t\t\t\t\t\t\t\"name\": \"防拆警示解除\",\n" + "\t\t\t\t\t\t\t\"value\": 1\n" + "\t\t\t\t\t\t}\n" + "\t\t\t\t\t],\n" + "\t\t\t\t\t\"dataType\": \"ENUM\",\n" + "\t\t\t\t\t\"identifier\": \"alarmType\",\n" + "\t\t\t\t\t\"name\": \"警示類型\",\n" + "\t\t\t\t\t\"index\": 0,\n" + "\t\t\t\t\t\"custom\": true\n" + "\t\t\t\t}\n" + "\t\t\t],\n" + "\t\t\t\"outputParams\": [\n" + "\t\t\t\t{\n" + "\t\t\t\t\t\"index\": 0,\n" + "\t\t\t\t\t\"identifier\": \"alarmType\"\n" + "\t\t\t\t}\n" + "\t\t\t],\n" + "\t\t\t\"custom\": true\n" + "\t\t}"; object.put("properties", new ArrayList<>()); object.put("services", new ArrayList<>()); object.put("events", Arrays.asList(com.alibaba.fastjson.JSONObject.parseObject(jsonStr))); object.put("productKey", "a1Q1Yrc****"); schema.validate(object); // throws a ValidationException if this object is invalid //} System.out.println(System.currentTimeMillis() - start); } catch (ValidationException exception) { System.out.println(exception); } } }
如何快速編寫ThingModelJson
下文為您介紹,如何使用Visual Studio Code工具編寫ThingModelJson。
- 訪問Visual Studio Code官網 ,下載並安裝新版本Visual Studio Code工具。
- 開啟Visual Studio Code,單擊左下角按鈕,選擇Settings。
- 在user頁簽,選擇
"json.schemas": [{ "fileMatch": ["/.json"], "url": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json" }]
配置完成後,編寫TSL時,會自動智能提示,如下圖所示。
,單擊Schemas下Edit in settings.json,配置如下內容並儲存。