一、物模型简介
| 功能类型 | 功能描述 |
| 属性 | 指设备在运行过程中的各类参数和状态数据。如温湿度传感器采集的温度、湿度值；电器类设备的开关状态值、车载设备采集的当前速度、经纬度值。属性支持读写和只读两类：读写表示该属性可从设备端上报到平台，也可从平台发起控制。只读表示该属性只从设备向平台上报。 |
| 事件 | 指设备运行时由设备发起需要用户业务系统感知的数据，事件类型包括信息、告警和故障。例如设备运行出现故障，需要将故障信息及故障发生时的相关数据发送到平台。 |
| 行为 | 指设备为应用提供的调用方法，用于业务发起请求，需要设备端处理完成后返回处理结果，业务系统能同步或异步获取结果的场景。例如：停车场用户在支付完停车费后，系统需要立刻打开道闸放行，业务系统需要获取道闸的最终状态同步操作是否成功。云打印场景用户下发打印行为后，行为的入参包含订单 ID、打印单据内容等，出参包括打印结果编码。 |
二、前提条件
已完成创建产品。具体操作，请参见 创建产品。
三、添加物模型
1. 登录 物联网开发平台，在控制台右上方，选择物联网开发平台所在地域。
2. 在实例管理页面，找到对应的实例，单击实例卡片。
3. 在左侧导航栏，选择设备管理 > 产品。
4. 进入对应产品详情页后，选择功能定义，然后单击新增功能。
5. 在弹出窗口中按需选择“功能类型”。
功能类型为属性功能类型为事件功能类型为行为1. 功能类型选择属性，填写功能名称，如“开关”。2. 标识符必须在该产品下所有物模型中保持唯一。3. 按需选择数据类型与读写类型，配置填写其他信息后即可保存。功能类型选择事件，填写功能名称。配置填写其他信息后即可保存。例如，选择“事件类型”为“信息”，用户可自定义设备向物联网开发平台发送的事件信息。在自助零售、共享支付或停车场景中，常需在支付完成后通过物联网平台让业务系统立即执行开门、开锁或开闸等操作。这要求业务系统能实时接收到设备端的处理结果。若未能及时响应，业务系统需对该交易进行取消处理，例如发起退款。1. 功能类型选择行为。2. 在功能名称录入对应的行为名称，然后定义相关参数。请求参数需要由用户定义，返回参数是设备侧执行完之后上报到物联网开发平台的参数。例如，功能名称为“开锁”，标识符为“Open”。请求参数自定义一个订单 ID 的字符串类型，这样业务系统可以跟踪到每笔订单在设备侧的处理情况；返回参数也可以添加订单 ID 以及设备最终开锁状态结果的字段 code，如果开锁成功，则返回 code 为0，失败则为1。当业务系统接收到 code 为1时，要么在业务允许的情况下重试，若已支付完成重试多次失败后则发起退款操作。
四、查看物模型 JSON
1. 添加完功能后，用户可以在产品详情页的功能定义中单击查看物模型JSON。
2. 你可查看或下载物模型对应的 JSON 格式。你还可以通过"导入物模型"功能，将复制的 JSON 用于产品间物模型定义的复制。
五、导入物模型
1. 在目标产品详情页的功能定义中单击导入物模型，将复制的某个产品的物模型 JSON 粘贴到文本框中。
2. 然后单击导入，新的 JSON 将覆盖原产品的物模型。
注意：若是已量产的产品需要慎用物模型导入功能。
六、物模型格式参考
以下为智能灯的物模型 JSON 描述说明，包括各种数据类型和事件类型。示例 JSON 如下，可供参考。
{ "version": "1.0", "profile": { "ProductId": "2300UMK31M", "CategoryId": "3" }, "properties": [ { "id": "power_switch", "name": "电灯开关", "desc": "控制电灯开灭", "required": true, "mode": "rw", "define": { "type": "bool", "mapping": { "0": "关", "1": "开" } } }, { "id": "color", "name": "颜色", "desc": "灯光颜色", "mode": "rw", "define": { "type": "enum", "mapping": { "0": "Red", "1": "Green", "2": "Blue" } } }, { "id": "brightness", "name": "亮度", "desc": "灯光亮度", "mode": "rw", "define": { "type": "int", "unit": "%", "step": "1", "min": "0", "max": "100", "start": "1" } }, { "id": "name", "name": "灯位置名称", "desc": "灯位置名称：书房、客厅等", "mode": "rw", "required": false, "define": { "type": "string", "min": "0", "max": "64" } } ], "events": [ { "id": "status_report", "name": "DeviceStatus", "desc": "Report the device status", "type": "info", "required": false, "params": [ { "id": "status", "name": "running_state", "desc": "Report current device running state", "define": { "type": "bool", "mapping": { "0": "normal", "1": "fault" } } }, { "id": "message", "name": "Message", "desc": "Some extra message", "define": { "type": "string", "min": "0", "max": "64" } } ] }, { "id": "low_voltage", "name": "LowVoltage", "desc": "Alert for device voltage is low", "type": "alert", "required": false, "params": [ { "id": "voltage", "name": "Voltage", "desc": "Current voltage", "define": { "type": "float", "unit": "V", "step": "1", "min": "0.0", "max": "24.0", "start": "1" } } ] }, { "id": "hardware_fault", "name": "Hardware_fault", "desc": "Report hardware fault", "type": "fault", "required": false, "params": [ { "id": "name", "name": "Name", "desc": "Name like: memory,tf card, censors …", "define": { "type": "string", "min": "0", "max": "64" } }, { "id": "error_code", "name": "Error_Code", "desc": "Error code for fault", "define": { "type": "int", "unit": "", "step": "1", "min": "0", "max": "2000", "start": "1" } } ] } ], "actions": [ { "id": "unlock", "name": "开灯行为检测", "desc": "用于描述开灯的动作", "input": [ { "id": "open", "name": "开关", "define": { "type": "bool", "mapping": { "0": "关", "1": "开" } } }, { "id": "user", "name": "用户", "define": { "type": "string", "min": "0", "max": "2048" } } ], "output": [ { "id": "user", "name": "用户", "define": { "type": "string", "min": "0", "max": "2048" } }, { "id": "time", "name": "开灯时间", "define": { "type": "timestamp" } }, { "id": "state", "name": "灯的状态", "define": { "type": "bool", "mapping": { "0": "关", "1": "开" } } } ], "required": false } ]}
七、相关文档
如需了解物模型协议，请参考 物模型协议。