什么是物模型

物模型是为产品定义的数据模型，用于描述产品的功能。本文介绍物模型相关概念和使用限制。

功能说明

物模型是物理空间中的实体（如传感器、车载装置、楼宇、工厂等）在云端的数字化表示，从属性、服务和事件三个维度，分别描述了该实体是什么、能做什么、可以对外提供哪些信息。定义了物模型的这三个维度，即完成了产品功能的定义。

功能类型 说明
属性（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字段及其详细说明。 说明 为了完整展示的结构，以下示例中包含所有参数，不代表实际使用中可能出现的组合。参数后的文字为参数说明，非参数值。各参数的使用场景，请参见参数说明。

  1. {
  2.     "schema": "物模型结构定义的访问URL",
  3.     "profile": {
  4.                 "version": "物模型结构定义版本号",
  5.         "productKey": "当前产品的ProductKey"
  6.     },
  7.     "properties": [
  8.         {
  9.             "identifier": "属性唯一标识符（物模型模块下唯一）",
  10.             "name": "属性名称",
  11.                         "desc": "属性描述",
  12.             "accessMode": "属性读写类型：只读（r）或读写（rw）。",
  13.             "required": "是否是标准功能的必选属性",
  14.             "dataType": {
  15.                 "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）",
  16.                 "specs": {
  17.                     "min": "参数最小值（int、float、double类型特有）",
  18.                     "max": "参数最大值（int、float、double类型特有）",
  19.                     "unit": "属性单位（int、float、double类型特有，非必填）",
  20.                     "unitName": "单位名称（int、float、double类型特有，非必填）",
  21.                     "size": "数组元素的个数，最大512（array类型特有）。",
  22.                     "step": "步长（text、enum类型无此参数）",
  23.                     "length": "数据长度，最大10240（text类型特有）。",
  24.                     "0": "0的值（bool类型特有）",
  25.                     "1": "1的值（bool类型特有）",
  26.                     "item": {
  27.                         "type": "数组元素的类型（array类型特有）"
  28.                     }
  29.                 },
  30.                                 //枚举定义,enum类型特有,枚举项定义方法与bool类型定义0和1的值方法相同
  31.                                 "enumObj":{},
  32.                                 //结构体项,struct类型特有,结构同外层properties的项,但没有accessMode,required这两项
  33.                                 "structItems":[{}],
  34.             },
  35.                         //用于扩展项的定义
  36.                         "expands": {}
  37.         }
  38.     ],
  39.     "events": [
  40.         {
  41.             "identifier": "事件唯一标识符（物模型模块下唯一，其中post是默认生成的属性上报事件。）",
  42.             "name": "事件名称",
  43.             "desc": "事件描述",
  44.             "type": "事件类型（info、alert、error）",
  45.             "required": "是否是标准功能的必选事件",
  46.             "outputData": [
  47.                 {
  48.                     "identifier": "参数唯一标识符",
  49.                     "name": "参数名称",
  50.                     "dataType": {
  51.                         "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）",
  52.                         "specs": {
  53.                             "min": "参数最小值（int、float、double类型特有）",
  54.                             "max": "参数最大值（int、float、double类型特有）",
  55.                             "unit": "属性单位（int、float、double类型特有，非必填）",
  56.                             "unitName": "单位名称（int、float、double类型特有，非必填）",
  57.                             "size": "数组元素的个数，最大512（array类型特有）。",
  58.                             "step": "步长（text、enum类型无此参数）",
  59.                             "length": "数据长度，最大10240（text类型特有）。",
  60.                             "0": "0的值（bool类型特有）",
  61.                             "1": "1的值（bool类型特有）",
  62.                             "item": {
  63.                                 "type": "数组元素的类型（array类型特有）"
  64.                             }
  65.                         },
  66.                                                 //枚举定义,enum类型特有,枚举项定义方法与bool类型定义0和1的值方法相同
  67.                                                 "enumObj":{},
  68.                                                 //结构体项,struct类型特有,结构同外层properties的项,但没有accessMode,required这两项
  69.                                                 "structItems":[{}],
  70.                     },
  71.                                         //用于扩展项的定义
  72.                                         "expands": {}
  73.                 }
  74.             ],
  75.             "method": "事件对应的方法名称（根据identifier生成）"
  76.         }
  77.     ],
  78.     "services": [
  79.         {
  80.             "identifier": "服务唯一标识符（物模型模块下唯一，其中set/get是根据属性的accessMode默认生成的服务。）",
  81.             "name": "服务名称",
  82.             "desc": "服务描述",
  83.             "required": "是否是标准功能的必选服务",
  84.             "callType": "async（异步调用）或sync（同步调用）",
  85.             "inputData": [
  86.                 {
  87.                     "identifier": "入参唯一标识符",
  88.                     "name": "入参名称",
  89.                     "dataType": {
  90.                         "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）",
  91.                         "specs": {
  92.                             "min": "参数最小值（int、float、double类型特有）",
  93.                             "max": "参数最大值（int、float、double类型特有）",
  94.                             "unit": "属性单位（int、float、double类型特有，非必填）",
  95.                             "unitName": "单位名称（int、float、double类型特有，非必填）",
  96.                             "size": "数组元素的个数，最大512（array类型特有）。",
  97.                             "step": "步长（text、enum类型无此参数）",
  98.                             "length": "数据长度，最大10240（text类型特有）。",
  99.                             "0": "0的值（bool类型特有）",
  100.                             "1": "1的值（bool类型特有）",
  101.                             "item": {
  102.                                 "type": "数组元素的类型（array类型特有）"
  103.                             }
  104.                         },
  105.                                                 //枚举定义,enum类型特有,枚举项定义方法与bool类型定义0和1的值方法相同
  106.                                                 "enumObj":{},
  107.                                                 //结构体项,struct类型特有,结构同外层properties的项,但没有accessMode,required这两项
  108.                                                 "structItems":[{}],
  109.                     },
  110.                                         //用于扩展项的定义
  111.                                         "expands": {}
  112.                 }
  113.             ],
  114.             "outputData": [
  115.                 {
  116.                     "identifier": "出参唯一标识符",
  117.                     "name": "出参名称",
  118.                     "dataType": {
  119.                         "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）",
  120.                         "specs": {
  121.                             "min": "参数最小值（int、float、double类型特有）",
  122.                             "max": "参数最大值（int、float、double类型特有）",
  123.                             "unit": "属性单位（int、float、double类型特有，非必填）",
  124.                             "unitName": "单位名称（int、float、double类型特有，非必填）",
  125.                             "size": "数组元素的个数，最大512（array类型特有）。",
  126.                             "step": "步长（text、enum类型无此参数）",
  127.                             "length": "数据长度，最大10240（text类型特有）。",
  128.                             "0": "0的值（bool类型特有）",
  129.                             "1": "1的值（bool类型特有）",
  130.                             "item": {
  131.                                 "type": "数组元素的类型（array类型特有）"
  132.                             }
  133.                         },
  134.                                                 //枚举定义,enum类型特有,枚举项定义方法与bool类型定义0和1的值方法相同
  135.                                                 "enumObj":{},
  136.                                                 //结构体项,struct类型特有,结构同外层properties的项,但没有accessMode,required这两项
  137.                                                 "structItems":[{}],
  138.                     },
  139.                                         //用于扩展项的定义
  140.                                         "expands": {}
  141.                 }
  142.             ],
  143.             "method": "服务对应的方法名称（根据identifier生成）"
  144.         }
  145.     ],
  146.         //用于扩展项的定义
  147.         "expands": {},
  148.         //用于标签的定义,结构同外层properties的项,但没有accessMode这一项
  149.         "tags":[{}]
  150. }

物模型JSON示例

  1. {
  2.   "schema": "https://xxx.com/schema.json",
  3.   "profile": {
  4.     "version": "1.0",
  5.     "productKey": "a1yX7nPdoqs"
  6.   },
  7.   "properties": [
  8.     {
  9.       "identifier": "LightSwitch",
  10.       "name": "主灯开关",
  11.       "accessMode": "rw",
  12.       "required": true,
  13.       "dataType": {
  14.         "type": "bool",
  15.         "specs": {
  16.           "0": "关闭",
  17.           "1": "开启"
  18.         }
  19.       }
  20.     }
  21.   ],
  22.   "events": [
  23.     {
  24.       "identifier": "post",
  25.       "name": "post",
  26.       "type": "info",
  27.       "required": true,
  28.       "desc": "属性上报",
  29.       "method": "thing.event.property.post",
  30.       "outputData": [
  31.         {
  32.           "identifier": "LightSwitch",
  33.           "name": "主灯开关",
  34.           "dataType": {
  35.             "type": "bool",
  36.             "specs": {
  37.               "0": "关闭",
  38.               "1": "开启"
  39.             }
  40.           }
  41.         }
  42.       ]
  43.     },
  44.     {
  45.       "identifier": "Error",
  46.       "name": "故障上报",
  47.       "type": "error",
  48.       "required": true,
  49.       "method": "thing.event.Error.post",
  50.       "outputData": [
  51.         {
  52.           "identifier": "ErrorCode",
  53.           "name": "故障代码",
  54.           "dataType": {
  55.             "type": "enum",
  56.             "enumObj": {
  57.               "0": "恢复正常"
  58.             }
  59.           }
  60.         }
  61.       ]
  62.     }
  63.   ],
  64.   "services": [
  65.     {
  66.       "identifier": "set",
  67.       "name": "set",
  68.       "required": true,
  69.       "callType": "async",
  70.       "desc": "属性设置",
  71.       "method": "thing.service.property.set",
  72.       "inputData": [
  73.         {
  74.           "identifier": "LightSwitch",
  75.           "name": "主灯开关",
  76.           "dataType": {
  77.             "type": "bool",
  78.             "specs": {
  79.               "0": "关闭",
  80.               "1": "开启"
  81.             }
  82.           }
  83.         }
  84.       ],
  85.       "outputData": []
  86.     },
  87.     {
  88.       "identifier": "get",
  89.       "name": "get",
  90.       "required": true,
  91.       "callType": "async",
  92.       "desc": "属性获取",
  93.       "method": "thing.service.property.get",
  94.       "inputData": [
  95.         "LightSwitch"
  96.       ],
  97.       "outputData": [
  98.         {
  99.           "identifier": "LightSwitch",
  100.           "name": "主灯开关",
  101.           "dataType": {
  102.             "type": "bool",
  103.             "specs": {
  104.               "0": "关闭",
  105.               "1": "开启"
  106.             }
  107.           }
  108.         }
  109.       ]
  110.     }
  111.   ],
  112.   "tags": [
  113.     {
  114.       "identifier": "producer",
  115.       "name": "生产商",
  116.       "required": true,
  117.       "dataType": {
  118.         "type": "text",
  119.         "specs": {
  120.           "length": "50",
  121.         }
  122.       }
  123.     }
  124.   ],
  125. }