什么是物模型

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

功能说明

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

功能类型 说明
属性(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类型定义01的值方法相同
  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类型定义01的值方法相同
  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类型定义01的值方法相同
  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类型定义01的值方法相同
  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. }