什么是物模型
物模型是为产品定义的数据模型,用于描述产品的功能。本文介绍物模型相关概念和使用限制。
功能说明
物模型是物理空间中的实体(如传感器、车载装置、楼宇、工厂等)在云端的数字化表示,从属性、服务和事件三个维度,分别描述了该实体是什么、能做什么、可以对外提供哪些信息。定义了物模型的这三个维度,即完成了产品功能的定义。
功能类型 | 说明 |
---|---|
属性(Property) | 用于描述设备运行时具体信息和状态。 例如,环境监测设备所读取的当前环境温度、智能灯开关状态、电风扇风力等级等。 属性可分为读写和只读两种类型,即支持读取和设置属性。 |
服务(Service) | 指设备可供外部调用的指令或方法。服务调用中可设置输入和输出参数。输入参数是服务执行时的参数,输出参数是服务执行后的结果。 相比于属性,服务可通过一条指令实现更复杂的业务逻辑,例如执行某项特定的任务。 服务分为异步和同步两种调用方式。 |
事件(Event) | 设备运行时,主动上报给云端的信息,一般包含需要被外部感知和处理的信息、告警和故障。事件中可包含多个输出参数。 例如,某项任务完成后的通知信息;设备发生故障时的温度、时间信息;设备告警时的运行状态等。 事件可以被订阅和推送。 |
标签(Tag) | 用于定义设备标签 |
物联网平台支持以下数据类型,为产品定义物模型功能时,您可选择使用。
数据类型 | 说明 | 示例 |
---|---|---|
int32 | 32位整型。 | 10 |
float | 单精度浮点型。 | 1.1 |
double | 双精度浮点型。 | 1.23 |
text | 字符串,对应的数据长度不能超过10240字节。 | “Hello world!” |
date | 时间戳。格式为String类型的UTC时间戳,单位:毫秒。 | “1635839462000” |
bool | 布尔型。采用0(false)或1(true)来定义布尔值,且0和1为int32类型。 | 0表示关、1表示开。 |
enum | 枚举型。定义枚举项的参数值和参数描述,参数值必须为整数。 | 整数0表示红色,整数1表示蓝色,整数2表示绿色。 |
struct | JSON对象。定义一个JSON结构体,结构体内元素类型支持int32、float、double、text、date、bool和enum,不支持结构体嵌套。 | > { “name”:”Tom”, “age”:10 } |
| | array | 数组。需声明数组内的元素类型、数组元素个数。元素类型支持int32、float、double、text或struct,需确保同一个数组元素类型相同。元素个数限制为1~512个。 | [1, 2, 3, 4, 5, 6] |
物模型JSON格式定义
下方介绍物模型中JSON字段及其详细说明。 说明 为了完整展示的结构,以下示例中包含所有参数,不代表实际使用中可能出现的组合。参数后的文字为参数说明,非参数值。各参数的使用场景,请参见参数说明。
{
"schema": "物模型结构定义的访问URL",
"profile": {
"version": "物模型结构定义版本号",
"productKey": "当前产品的ProductKey"
},
"properties": [
{
"identifier": "属性唯一标识符(物模型模块下唯一)",
"name": "属性名称",
"desc": "属性描述",
"accessMode": "属性读写类型:只读(r)或读写(rw)。",
"required": "是否是标准功能的必选属性",
"dataType": {
"type": "属性类型: int(原生)、float(原生)、double(原生)、text(原生)、date(String类型UTC毫秒)、bool(0或1的int类型)、enum(int类型,枚举项定义方法与bool类型定义0和1的值方法相同)、struct(结构体类型,可包含前面7种类型,下面使用'structItems':[{}]描述包含的对象)、array(数组类型,支持int、double、float、text、struct)",
"specs": {
"min": "参数最小值(int、float、double类型特有)",
"max": "参数最大值(int、float、double类型特有)",
"unit": "属性单位(int、float、double类型特有,非必填)",
"unitName": "单位名称(int、float、double类型特有,非必填)",
"size": "数组元素的个数,最大512(array类型特有)。",
"step": "步长(text、enum类型无此参数)",
"length": "数据长度,最大10240(text类型特有)。",
"0": "0的值(bool类型特有)",
"1": "1的值(bool类型特有)",
"item": {
"type": "数组元素的类型(array类型特有)"
}
},
//枚举定义,enum类型特有,枚举项定义方法与bool类型定义0和1的值方法相同
"enumObj":{},
//结构体项,struct类型特有,结构同外层properties的项,但没有accessMode,required这两项
"structItems":[{}],
},
//用于扩展项的定义
"expands": {}
}
],
"events": [
{
"identifier": "事件唯一标识符(物模型模块下唯一,其中post是默认生成的属性上报事件。)",
"name": "事件名称",
"desc": "事件描述",
"type": "事件类型(info、alert、error)",
"required": "是否是标准功能的必选事件",
"outputData": [
{
"identifier": "参数唯一标识符",
"name": "参数名称",
"dataType": {
"type": "属性类型: int(原生)、float(原生)、double(原生)、text(原生)、date(String类型UTC毫秒)、bool(0或1的int类型)、enum(int类型,枚举项定义方法与bool类型定义0和1的值方法相同)、struct(结构体类型,可包含前面7种类型,下面使用'structItems':[{}]描述包含的对象)、array(数组类型,支持int、double、float、text、struct)",
"specs": {
"min": "参数最小值(int、float、double类型特有)",
"max": "参数最大值(int、float、double类型特有)",
"unit": "属性单位(int、float、double类型特有,非必填)",
"unitName": "单位名称(int、float、double类型特有,非必填)",
"size": "数组元素的个数,最大512(array类型特有)。",
"step": "步长(text、enum类型无此参数)",
"length": "数据长度,最大10240(text类型特有)。",
"0": "0的值(bool类型特有)",
"1": "1的值(bool类型特有)",
"item": {
"type": "数组元素的类型(array类型特有)"
}
},
//枚举定义,enum类型特有,枚举项定义方法与bool类型定义0和1的值方法相同
"enumObj":{},
//结构体项,struct类型特有,结构同外层properties的项,但没有accessMode,required这两项
"structItems":[{}],
},
//用于扩展项的定义
"expands": {}
}
],
"method": "事件对应的方法名称(根据identifier生成)"
}
],
"services": [
{
"identifier": "服务唯一标识符(物模型模块下唯一,其中set/get是根据属性的accessMode默认生成的服务。)",
"name": "服务名称",
"desc": "服务描述",
"required": "是否是标准功能的必选服务",
"callType": "async(异步调用)或sync(同步调用)",
"inputData": [
{
"identifier": "入参唯一标识符",
"name": "入参名称",
"dataType": {
"type": "属性类型: int(原生)、float(原生)、double(原生)、text(原生)、date(String类型UTC毫秒)、bool(0或1的int类型)、enum(int类型,枚举项定义方法与bool类型定义0和1的值方法相同)、struct(结构体类型,可包含前面7种类型,下面使用'structItems':[{}]描述包含的对象)、array(数组类型,支持int、double、float、text、struct)",
"specs": {
"min": "参数最小值(int、float、double类型特有)",
"max": "参数最大值(int、float、double类型特有)",
"unit": "属性单位(int、float、double类型特有,非必填)",
"unitName": "单位名称(int、float、double类型特有,非必填)",
"size": "数组元素的个数,最大512(array类型特有)。",
"step": "步长(text、enum类型无此参数)",
"length": "数据长度,最大10240(text类型特有)。",
"0": "0的值(bool类型特有)",
"1": "1的值(bool类型特有)",
"item": {
"type": "数组元素的类型(array类型特有)"
}
},
//枚举定义,enum类型特有,枚举项定义方法与bool类型定义0和1的值方法相同
"enumObj":{},
//结构体项,struct类型特有,结构同外层properties的项,但没有accessMode,required这两项
"structItems":[{}],
},
//用于扩展项的定义
"expands": {}
}
],
"outputData": [
{
"identifier": "出参唯一标识符",
"name": "出参名称",
"dataType": {
"type": "属性类型: int(原生)、float(原生)、double(原生)、text(原生)、date(String类型UTC毫秒)、bool(0或1的int类型)、enum(int类型,枚举项定义方法与bool类型定义0和1的方法相同)、struct(结构体类型,可包含前面7种类型,下面使用'structItems':[{}]描述包含的对象)、array(数组类型,支持int、double、float、text、struct)",
"specs": {
"min": "参数最小值(int、float、double类型特有)",
"max": "参数最大值(int、float、double类型特有)",
"unit": "属性单位(int、float、double类型特有,非必填)",
"unitName": "单位名称(int、float、double类型特有,非必填)",
"size": "数组元素的个数,最大512(array类型特有)。",
"step": "步长(text、enum类型无此参数)",
"length": "数据长度,最大10240(text类型特有)。",
"0": "0的值(bool类型特有)",
"1": "1的值(bool类型特有)",
"item": {
"type": "数组元素的类型(array类型特有)"
}
},
//枚举定义,enum类型特有,枚举项定义方法与bool类型定义0和1的值方法相同
"enumObj":{},
//结构体项,struct类型特有,结构同外层properties的项,但没有accessMode,required这两项
"structItems":[{}],
},
//用于扩展项的定义
"expands": {}
}
],
"method": "服务对应的方法名称(根据identifier生成)"
}
],
//用于扩展项的定义
"expands": {},
//用于标签的定义,结构同外层properties的项,但没有accessMode这一项
"tags":[{}]
}
物模型JSON示例
{
"schema": "https://xxx.com/schema.json",
"profile": {
"version": "1.0",
"productKey": "a1yX7nPdoqs"
},
"properties": [
{
"identifier": "LightSwitch",
"name": "主灯开关",
"accessMode": "rw",
"required": true,
"dataType": {
"type": "bool",
"specs": {
"0": "关闭",
"1": "开启"
}
}
}
],
"events": [
{
"identifier": "post",
"name": "post",
"type": "info",
"required": true,
"desc": "属性上报",
"method": "thing.event.property.post",
"outputData": [
{
"identifier": "LightSwitch",
"name": "主灯开关",
"dataType": {
"type": "bool",
"specs": {
"0": "关闭",
"1": "开启"
}
}
}
]
},
{
"identifier": "Error",
"name": "故障上报",
"type": "error",
"required": true,
"method": "thing.event.Error.post",
"outputData": [
{
"identifier": "ErrorCode",
"name": "故障代码",
"dataType": {
"type": "enum",
"enumObj": {
"0": "恢复正常"
}
}
}
]
}
],
"services": [
{
"identifier": "set",
"name": "set",
"required": true,
"callType": "async",
"desc": "属性设置",
"method": "thing.service.property.set",
"inputData": [
{
"identifier": "LightSwitch",
"name": "主灯开关",
"dataType": {
"type": "bool",
"specs": {
"0": "关闭",
"1": "开启"
}
}
}
],
"outputData": []
},
{
"identifier": "get",
"name": "get",
"required": true,
"callType": "async",
"desc": "属性获取",
"method": "thing.service.property.get",
"inputData": [
"LightSwitch"
],
"outputData": [
{
"identifier": "LightSwitch",
"name": "主灯开关",
"dataType": {
"type": "bool",
"specs": {
"0": "关闭",
"1": "开启"
}
}
}
]
}
],
"tags": [
{
"identifier": "producer",
"name": "生产商",
"required": true,
"dataType": {
"type": "text",
"specs": {
"length": "50",
}
}
}
],
}