调用某些物模型相关API时,请求参数或返回参数中包含参数ThingModelJson,该参数的取值格式为物模型功能定义在物联网平台系统的存储结构,与TSL中的数据结构有所不同。ThingModelJson中所有字段按照key的字符排序。

物模型功能定义的限制说明,请参见产品与设备中物模型功能定义限制

数据结构

默认模块和自定义模块数据结构不同。

  • 默认模块
    {
      "_ppk":{
           "description":"test",
           "version":"159244410****"
      }
      "events":[],
      "productKey":"al12345****",
      "properties":[],
      "services":[],
      "functionBlocks":[{
          "productKey":"al12345****",
          "functionBlockId":"location0",
          "functionBlockName":"定位模块0"
        }]
    }
    参数类型说明
    productKeyString物模型所属产品的ProductKey。
    _ppkString物模型版本信息。包含参数:
    • version:当前物模型版本号。仅发布后的正式版物模型才有此参数。
    • description:当前默认模块物模型版本的描述。仅发布后的正式版物模型才有此参数。
    propertiesList物模型中的属性列表。关于属性数据结构中包含的参数说明,请参见属性数据结构规范

    每个属性数据结构中,可以使用extendConfig来定义物模型扩展描述的配置,请参见extendConfig数据结构规范。当属性无扩展描述时,无需传入extendConfig

    servicesList物模型中的服务列表。关于服务数据结构中包含的参数说明,请参见服务数据格式规范

    每个服务数据结构中,可以使用extendConfig来定义物模型扩展描述的配置,请参见extendConfig数据结构规范。当服务无扩展描述时,无需传入extendConfig

    eventsList物模型中的事件列表。关于事件数据结构中包含的参数说明,请参见事件数据格式规范

    每个事件数据结构中,可以使用extendConfig来定义物模型扩展描述的配置,请参见extendConfig数据结构规范。当事件无扩展描述时,无需传入extendConfig

    functionBlocksList自定义模块列表。仅当产品下有自定义模块时,才包含该参数。包含参数:
    • productKey:物模型所属产品的ProductKey。
    • functionBlockId:物模型自定义模块标识符,在产品中具有唯一性。
    • functionBlockName:物模型自定义模块名称。
  • 自定义模块
    {
      "productKey":"al12345****", 
      "identifier":"location0",
      "name":"定位模块0",
      "properties":[],
      "services":[],
      "events":[],
      "description":""
    }

    自定义模块基本参数说明如下,其他参数说明与默认模块中相同。

    参数类型说明
    identifierString物模型自定义模块标识符,在产品中具有唯一性。

    支持英文大小写字母、数字和下划线(_),不超过30个字符。

    nameString物模型的自定义模块名称。

    支持中文、英文字母、日文、数字和下划线(_),长度限制为4~30个字符,一个中文、一个日文算1个字符。

    descriptionString对模块进行说明或备注。长度限制为100个字符。

属性数据结构规范

以下表格展示属性定义中需包含的参数和说明。

重要 参数stdcustomFlag已过期,对于已使用的API,不影响接口调用,此处不再说明;对于新调用的API,无需传入已过期参数。
参数类型是否必需说明
productKeyString物模型所属产品的ProductKey。
createTsLong功能创建的时间戳,默认长度是13位。可手动传入也可由系统生成。功能定义会根据该时间由小到大进行排序。
说明 存量物模型创建时间,以该物模型功能上线后第一次编辑为准。
identifierString属性的标识符。可包含大小写英文字母、数字、下划线(_),长度不超过50个字符。
说明 不能用以下词汇作为标识符:set、get、post、property、event、time、value。
dataTypeString属性值的数据类型。

可选值:ARRAYSTRUCTINTFLOATDOUBLETEXTDATEENUMBOOL

不同数据类型,可传入的参数不同。详情请参见本文中对应数据类型的数据规范章节。

nameString属性名称。可包含中文、大小写英文字母、数字、短划线(-)、下划线(_)和半角句号(.),且必须以中文、英文字母或数字开头,长度不超过30个字符,一个中文计为一个字符。
rwFlagString在云端可以对该属性进行的操作类型。
  • READ_WRITE:读写。
  • READ_ONLY:只读。
dataSpecsObject数据类型(dataType)为非列表型(INTFLOATDOUBLETEXTDATEARRAY)的数据规范存储在dataSpecs中,请参见表格下方示例。
说明
  • 除属性、服务、事件和参数定义数据以外,其他数据都属于数据规范。
  • dataSpecsdataSpecsList之中必须传入且只能传入一个,请根据实际数据类型传入。
dataSpecsListList数据类型(dataType)为列表型(ENUMBOOLSTRUCT)的数据规范存储在dataSpecsList中,请参见表格下方示例。
说明
  • 除属性、服务、事件和参数定义数据以外,其他数据都属于数据规范。
  • dataSpecsdataSpecsList之中必须传入且只能传入一个,请根据实际数据类型传入。
requiredBoolean是否是标准品类的必选属性。
  • true:是
  • false:否
customBoolean是否是自定义功能。
  • true:是
  • false:否
  • dataTypeINTdataSpecs示例:
    {
      "dataSpecs": {
        "custom": true,
        "dataType": "INT",
        "defaultValue": "30",
        "max": "1440",
        "min": "0",
        "step": "10",
        "unit": "min"
      }
    }
  • dataTypeTEXTdataSpecs示例:
    {
      "dataSpecs": {
        "custom": true,
        "dataType": "TEXT",
        "id": 2412127,
        "length": 2048
      }
    }
  • dataTypeARRAYdataSpecs示例:
    {
      "dataSpecs": {
        "childDataType": "INT",
        "custom": true,
        "dataType": "ARRAY",
        "size": 1
      }
    }
  • dataTypeENUMdataSpecsList示例:
    {
      "dataSpecsList": [
        {
          "custom": false,
          "dataType": "ENUM",
          "defaultValue": "true",
          "name": "打开",
          "value": 1
        },
        {
          "custom": false,
          "dataType": "ENUM",
          "defaultValue": "false",
          "name": "关闭",
          "value": 0
        }
      ]
    }
  • dataTypeSTRUCTdataSpecsList示例:
    {
      "childDataType": "TEXT",
      "childName": "卡编号",
      "dataSpecs": {
        "custom": true,
        "dataType": "TEXT",
        "length": 128
      },
      "dataType": "STRUCT",
      "identifier": "CardNo",
      "name": "NVR所拥有的芯片信息"
    }

服务数据格式规范

以下表格展示服务定义中需包含的参数和说明。

参数类型是否必填说明
productKeyString物模型所属产品的ProductKey。
createTsLong功能创建的时间戳,默认长度是13位。可手动传入也可由系统生成。功能定义会根据该时间由小到大进行排序。
说明 存量物模型创建时间,以该物模型功能上线后第一次编辑为准。
identifierString服务的标识符。可包含大小写英文字母、数字、下划线(_),长度不超过50个字符。
说明 不能用以下词汇作为标识符:set、get、post、property、event、time、value。
serviceNameString服务名称。可包含中文、大小写英文字母、数字、短划线(-)、下划线(_)和半角句号(.),且必须以中文、英文字母或数字开头,长度不超过30个字符,一个中文计为一个字符。
inputParamsList服务的输入参数。数据结构说明,请参见输入、输出参数结构规范
outputParamsList服务的输出参数。数据结构说明,请参见输入、输出参数结构规范
requiredBoolean是否是标准品类的必选服务。
  • true:是
  • false:否
callTypeString服务的调用方式。
  • ASYNC:异步调用
  • SYNC:同步调用
customBoolean是否是自定义功能。
  • true:是
  • false:否

事件数据格式规范

以下表格展示事件定义中需包含的参数和说明。

参数类型是否必填说明
productKeyString物模型所属产品的ProductKey。
createTsLong功能创建的时间戳,默认长度是13位。可手动传入也可由系统生成。功能定义会根据该时间由小到大进行排序。
说明 存量物模型创建时间,以该物模型功能上线后第一次编辑为准。
identifierString事件的标识符。可包含大小写英文字母、数字、下划线(_),长度不超过50个字符。
说明 不能用以下词汇作为标识符:set、get、post、property、event、time、value。
eventNameString事件名称。可包含中文、大小写英文字母、数字、短划线(-)、下划线(_)和半角句号(.),且必须以中文、英文或数字开头,长度不超过30个字符,一个中文计为一个字符。
eventTypeString事件类型。
  • INFO_EVENT_TYPE:信息。
  • ALERT_EVENT_TYPE:告警。
  • ERROR_EVENT_TYPE:故障。
outputdataList事件的输出参数。数据结构说明,请参见输入、输出参数结构规范
requiredBoolean是否是标准品类的必选事件。
  • true:是
  • false:否
customBoolean是否是自定义功能。
  • true:是
  • false:否

输入、输出参数结构规范

服务或事件中的输入或输出参数的数据结构规范如下。

参数类型是否必填说明
dataTypeString参数值的数据类型。

可选值:ARRAYSTRUCTINTFLOATDOUBLETEXTDATEENUMBOOL

各数据类型的数据规范,请参见本文中对应数据类型的数据规范章节。

identifierString参数的标识符。可包含大小写英文字母、数字、下划线(_),长度不超过50个字符。
说明 不能用以下词汇作为标识符:set、get、post、property、event、time、value。
nameString参数名称。可包含中文、大小写英文字母、数字、短划线(-)、下划线(_)和半角句号(.),且必须以中文、英文字母或数字开头,长度不超过30个字符,一个中文计为一个字符。
directionString表示参数是输入参数还是输出参数。
  • PARAM_INPUT:输入参数。
  • PARAM_OUTPUT:输出参数。
paraOrderInteger参数的序号。从0开始排序,且不能重复。
dataSpecsObject数据类型(dataType)为非列表型(INTFLOATDOUBLETEXTDATEARRAY)的数据规范存储在dataSpecs中。
说明
  • 除属性、服务、事件和参数定义数据以外,其他数据都属于数据规范。
  • dataSpecsdataSpecsList之中必须传入且只能传入一个,请根据实际数据类型传入。
dataSpecsListList数据类型(dataType)为列表型(ENUMBOOLSTRUCT)的数据规范存储在dataSpecsList中。
说明
  • 除属性、服务、事件和参数定义数据以外,其他数据都属于数据规范。
  • dataSpecsdataSpecsList之中必须传入且只能传入一个,请根据实际数据类型传入。
customBoolean参数是否隶属于自定义功能。
  • true:是
  • false:否

INT、FLOAT、DOUBLE类型数据结构规范

当功能或参数的数据类型为INTFLOATDOUBLE时,数据结构中包含的参数如下。

参数类型是否必需说明
dataTypeString取值为INTFLOATDOUBLE
maxString最大值。取值为INTFLOATDOUBLE,必须与dataType设置一致。

取值需转为对应的STRING类型。例如,dataTypeINT,取值为"max":"200",而不是"max":200

minString最小值。取值为INTFLOATDOUBLE,必须与dataType设置一致。

取值需转为对应的STRING类型,请参见max说明。

stepString步长,数据每次变化的增量。取值为INTFLOATDOUBLE,必须与dataType设置一致。

取值需转为对应的STRING类型,请参见max说明。

preciseString精度。当dataType取值为FLOATDOUBLE时,可传入的参数。
defaultValueString传入此参数,可存入一个默认值。
unitString单位的符号。
unitNameString单位的名称。
customBoolean是否是自定义功能。
  • true:是
  • false:否

DATE、TEXT类型数据结构规范

当功能或参数的数据类型为DATETEXT时,数据结构中包含的参数如下。

参数类型是否必需说明
dataTypeString取值为DATETEXT
lengthLong数据长度,取值不能超过2048,单位:字节。dataType取值为TEXT时,需传入该参数。
defaultValueString传入此参数,可存入一个默认值。
customBoolean是否是自定义功能。
  • true:是
  • false:否

ARRAY类型数据规范

当功能或参数的数据类型为ARRAY时,数据结构中包含的参数如下。

重要 ARRAYSTRUCT类型数据相互嵌套时,最多支持递归嵌套2层(父和子)。
参数类型是否必需说明
dataTypeString取值为ARRAY
sizeLong数组中的元素个数。
childDataTypeString数组中的元素的数据类型。可选值:STRUCTINTFLOATDOUBLETEXT
dataSpecsObject数据类型(dataType)为非列表型(INTFLOATDOUBLETEXTDATEARRAY)的数据规范存储在dataSpecs中。
说明
  • 除属性、服务、事件和参数定义数据以外,其他数据都属于数据规范。
  • dataSpecsdataSpecsList之中必须传入且只能传入一个,请根据实际数据类型传入。
dataSpecsListList数据类型(dataType)为列表型(ENUMBOOLSTRUCT)的数据规范存储在dataSpecsList中。
说明
  • 除属性、服务、事件和参数定义数据以外,其他数据都属于数据规范。
  • dataSpecsdataSpecsList之中必须传入且只能传入一个,请根据实际数据类型传入。
customBoolean是否是自定义功能。
  • true:是
  • false:否

枚举、布尔类型数据规范

当功能或参数的数据类型为BOOLENUM时,数据结构中包含的参数如下。

参数类型是否必需说明
dataTypeString取值为BOOLENUM
nameString枚举项的名称,可包含中文、大小写英文字母、数字、下划线(_)和短划线(-),且必须以中文、英文字母或数字开头。长度不超过20个字符,一个中文计为一个字符。
valueInteger枚举值。
customBoolean是否是自定义功能。
  • true:是
  • false:否

STRUCT类型数据结构规范

当功能或参数的数据类型为STRUCT时,数据结构中包含的参数如下。

重要
  • 参数childSpecsDTOchildEnumSpecsDTO已过期,对于已使用的API,不影响接口调用,此处不再说明;对于新调用的API,无需传入已过期参数,建议使用参数dataSpecsList
  • ARRAYSTRUCT类型数据相互嵌套时,最多支持递归嵌套2层(父和子)。
参数类型是否必需说明
dataTypeString取值为STRUCT
identifierString结构体中的子参数的标识符。可包含大小写英文字母、数字、下划线(_),长度不超过50个字符。
说明 不能用以下词汇作为标识符:set、get、post、property、event、time、value。
nameString结构体中的子参数名称。可包含中文、大小写英文字母、数字、短划线(-)、下划线(_)和半角句号(.),且必须以中文、英文字母或数字开头,长度不超过30个字符,一个中文计为一个字符。
说明 该参数与childName定义相同,目前不使用。
childDataTypeString结构体中子参数的数据类型。

可选值:INTFLOATDOUBLETEXTDATEENUMBOOL

childNameString结构体中的子参数名称。可包含中文、大小写英文字母、数字、短划线(-)、下划线(_)和半角句号(.),且必须以中文、英文字母或数字开头,长度不超过30个字符,一个中文计为一个字符。
dataSpecsObject

数据类型(dataType)为非列表型(INTFLOATDOUBLETEXTDATEARRAY)的数据规范存储在dataSpecs中。

说明
  • 除属性、服务、事件和参数定义数据以外,其他数据都属于数据规范。
  • dataSpecsdataSpecsList之中必须传入且只能传入一个,请根据实际数据类型传入。
dataSpecsListList数据类型(dataType)为列表型(ENUMBOOLSTRUCT)的数据规范存储在dataSpecsList中。
说明
  • 除属性、服务、事件和参数定义数据以外,其他数据都属于数据规范。
  • dataSpecsdataSpecsList之中必须传入且只能传入一个,请根据实际数据类型传入。
customBoolean是否是自定义功能。
  • true:是
  • false:否

extendConfig数据结构规范

每个属性、事件或服务数据结构中,可以使用extendConfig来定义物模型扩展描述的配置。扩展描述为设备通信协议到标准物模型的映射关系。

说明 返回数据中的configCode是系统为单个功能定义扩展描述生成的唯一标识符。

目前系统支持接入网关协议为Modbus、OPC UA或自定义的设备配置扩展描述。不同类型的扩展描述需要满足不同的数据规范:

Modbus类型

Modbus只支持属性类型的物模型扩展描述。

说明 为了完整展示extendConfig的结构,以下示例中包含所有参数,不代表实际使用中可能出现的组合。各参数的使用场景请参见参数说明。
{
  "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}
  }
}
参数类型说明
identifierString属性唯一标识符(产品下唯一)。
registerAddressString寄存器地址,必须以0x开头,且限制范围是0x0~0xFFFF,例如0xFE。
operateTypeString操作类型,取值:
  • coilStatus:线圈状态
  • inputStatus:离散量输入
  • holdingRegister:保持寄存器
  • inputRegister:输入寄存器
writeFunctionCodeInteger读写操作,对于不同操作类型(operateType),可选的取值不同:
  • coilStatus:
    • 5:读写(读0x01,写0x05)
    • 15:读写(读0x01,写0x0F)
    • 0:只读0x01
    • 6:只写0x05
    • 15:只写0x0F
  • inputStatus:0:只读0x02
  • holdingRegister:
    • 6:读写(读0x03,写0x06)
    • 16:读写(读0x03,写0x10)
    • 0:只读0x03
    • 6:只写0x06
    • 16:只写0x10
  • inputRegister:0:只读0x04
writeOnlyInteger是否只写。
  • 0:非只写。
    • writeFunctionCode取值不为0(表示读写)时,writeOnly为0表示支持读写。
    • writeFunctionCode取值为0(表示只读)时,writeOnly必须为0。
  • 1:只写。

    仅当writeFunctionCode取值不为0(表示读写)时,writeOnly可以为1,表示仅支持写。

scalingNumber缩放因子,不能为0。

string、bool无该参数。

pollingTimeInteger采集间隔,单位是ms。无需传入,将使用设备配置的采集间隔。
triggerInteger数据上报方式。1代表按时上报,2代表变更上报。
bitMaskIntegerbool特有的参数。

掩码,取值:1、2、4、8、16、32、64、128、256、512、1024、2048、4096、8192、16384、32768,即1<<(0~15)。

originalDataTypeObject原始数据类型描述。
typeString原始数据类型,需要为基础类型:int16、uint16、int32、uint32、int64、uint64、float、double、string、bool、customized data(按大端顺序返回hex data)。
specsObject部分数据类型特有的参数。
registerCountIntegerstring、customized data特有的参数。

寄存器的数据个数。

swapInteger除string、customized data外,其他数据类型特有的参数。

是否交换寄存器内高低字节,把寄存器内16位数据的前后8个bit互换(byte1byte2 -> byte2byte1)。

  • 0:不交换
  • 1:交换
reverseRegisterInteger除string、customized data外,其他数据类型特有的参数。
是否交换寄存器顺序,把原始数据32位数据的前后16个bit互换(byte1byte2byte3byte4 -> byte3byte4byte1byte2)。
  • 0:不交换
  • 1:交换

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
    }
  ]
}
参数类型说明
identifierString属性、服务、事件的唯一标识符(产品下唯一)。
displayNameString属性、事件需要传入displayName,服务不需要传入。
inputDataList输入数据。
outputDataList输出数据。
identifierString输入数据、输出数据的唯一标识符(产品下唯一)。
indexInteger索引。inputData中的index不能重复,outputData中的index不能重复。

自定义类型

自定义类型支持属性、服务、事件类型的物模型扩展描述。

{
  "identifier":"xxx",
  "customize":{}
}
参数类型说明
identifierString属性、服务、事件的唯一标识符(产品下唯一)。
customizeObject自定义JSON。

校验

您可以通过json-schemaThingModelJson中的入参进行预校验。

关于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。

  1. 访问Visual Studio Code官网 ,下载并安装新版本Visual Studio Code工具。
  2. 打开Visual Studio Code,单击左下角设置按钮,选择Settings
  3. user页签,选择Extensions > JSON,单击SchemasEdit in settings.json,配置如下内容并保存。
     "json.schemas": [{
            "fileMatch": ["/.json"],
            "url": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json"
    }]

    配置完成后,编写TSL时,会自动智能提示,如下图所示。

    提示