调用某些物模型相关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时,会自动智能提示,如下图所示。