調用某些物模型相關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頁簽,選擇 ,單擊Schemas下Edit in settings.json,配置如下內容并保存。
"json.schemas": [{ "fileMatch": ["/.json"], "url": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json" }]
配置完成后,編寫TSL時,會自動智能提示,如下圖所示。