什么是物模型 - 设备管理| 阿里云

物模型是阿里云物联网平台为产品定义的数据模型，用于描述产品的功能。本文介绍物模型的相关概念、TLS格式、使用流程和数据校验。

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

物模型将产品功能类型分为三类：属性、服务和事件。


功能类型	说明
属性（Property）	设备可读取和设置的能力。一般用于描述设备运行时的状态，如环境监测设备所读取的当前环境温度等。属性支持GET和SET请求方式。应用系统可发起对属性的读取和设置请求。
服务（Service）	设备可被外部调用的能力或方法，可设置输入参数和输出参数。产品提供了什么功能供云端调用。相比于属性，服务可通过一条指令实现更复杂的业务逻辑，如执行某项特定的任务。
事件（Event）	设备运行时，主动上报给云端的事件。事件一般包含需要被外部感知和处理的通知信息，可包含多个输出参数。例如，某项任务完成的信息，或者设备发生故障或告警时的温度等，事件可以被订阅和推送。

物联网平台提供物模型模块功能。物模型模块是一组功能定义的集合，可以解决工业场景中复杂的设备建模。不同模块可以定义不同的功能，且彼此互不影响。您可根据需要新增自定义模块，总模块数量不超过10个。

说明 2021年01月01日（不含当日）之前已定义的产品功能，归类于默认模块。

关于物模型使用限制，请参见产品与设备中物模型功能定义部分。

物模型TSL格式

物模型TSL（Thing Specification Language）是一个JSON格式的文件。您可以在产品的功能定义页面，单击物模型TSL，查看JSON格式的TSL。

物模型TSL的JSON字段结构如下：

说明为了完整展示TSL的结构，以下示例中包含所有参数，不代表实际使用中可能出现的组合。参数后的文字为参数说明，非参数值。各参数的使用场景，请参见参数说明。

{
    "schema": "物模型结构定义的访问URL",
    "profile": {
        "productKey": "产品ProductKey"
    },
    "properties": [
        {
            "identifier": "属性唯一标识符（产品下唯一）",
            "name": "属性名称",
            "accessMode": "属性读写类型：只读（r）或读写（rw）。",
            "required": "是否是标准功能的必选属性",
            "dataType": {
                "type": "属性类型: int（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的值方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、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类型特有）"
                    }
                }
            }
        }
    ],
    "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种类型，下面使用"specs":[{}]描述包含的对象）、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类型特有）"
                            }
                        }
                    }
                }
            ],
            "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种类型，下面使用"specs":[{}]描述包含的对象）、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类型特有）"
                                }
                            }
                        }
                    }
                }
            ],
            "outputData": [
                {
                    "identifier": "出参唯一标识符",
                    "name": "出参名称",
                    "dataType": {
                        "type": "属性类型: int（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、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类型特有）"
                            }
                        }
                    }
                }
            ],
            "method": "服务对应的方法名称（根据identifier生成）"
        }
    ],
    //仅自定义模块的TSL中有以下参数。
    "functionBlockId": "自定义模块的唯一标识符，模块ID",
    "functionBlockName": "自定义模块名称"

    //当产品下添加了自定义模块，默认模块TSL中才有functionBlocks，表示自定义模块列表。
    "functionBlocks": [
    {
      "functionBlockId": "自定义模块的唯一标识符，模块ID",
      "functionBlockName": "自定义模块名称",
      "productKey": "产品ProductKey"
    }
  ]
}

若产品的节点类型是设备，且接入网关协议为Modbus、OPC UA或自定义时，可以查看物模型扩展配置信息。

Modbus协议产品的扩展配置可用于Modbus子设备的物联网边缘计算，请参见物联网边缘计算文档。

Modbus协议产品的扩展配置数据结构如下：

{
  "profile": {
    "productKey": "产品ProductKey"
  },
  "properties": [
    {
      "identifier": "属性唯一标识符（产品下唯一）",
      "operateType": "（线圈状态/离散量输入/保持寄存器/输入寄存器: coilStatus/inputStatus/holdingRegister/inputRegister）",
      "registerAddress": "寄存器地址",
      "originalDataType": {
        "type": "原始数据类型：int16、uint16、int32、uint32、int64、uint64、float、double、string、bool、customized data（按大端顺序返回hex data）",
        "specs": {
          "registerCount": "寄存器数据个数，string、customized data特有。",
          "swap16": "交换寄存器内高低字节，把寄存器内16位数据的前后8个bit互换（byte1byte2 -> byte2byte1），除string和bool外，其他数据类型特有。",
          "reverseRegister": "交换寄存器顺序，把原始数据32位数据的前后16个bit互换（byte1byte2byte3byte4 -> byte3byte4byte1byte2），除string和bool外，其他数据类型特有。"
        }
      },
      "scaling": "缩放因子，除string和bool外，其他数据类型特有。",
      "trigger": "数据上报方式。1代表按时上报，2代表变更上报。",
      "writeFunctionCode":"读写操作，对于不同的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。",
      "writeOnly":"是否只写。0代表非只写，1代表只写。",
      "pollingTime":"采集间隔，单位是ms。无需传入，将使用设备配置的采集间隔。",
      "bitMask":"掩码，bool特有。取值：1、2、4、8、16、32、64、128、256、512、1024、2048、4096、8192、16384、32768，即1<<(0~15)。"
    }
  ]
}

物模型使用流程

在物联网平台控制台添加物模型，请参见单个添加物模型、批量添加物模型。
参见Link SDK 文档，进行设备端物模型开发。
开发完成后，设备端可以上报属性和事件，云端可以设置属性和调用服务，参见设备属性、事件、服务。云端还可以设置设备期望属性值，请参见设备期望属性值。
设备端上报的属性、事件和完成的服务调用数据，在通过强校验或弱校验后，将显示在物联网平台控制台对应设备的设备详情页物模型数据页签。您的服务器可以通过服务端订阅、云产品流转获得设备属性和事件数据，以及设备属性设置和服务调用指令响应结果。

物模型数据校验

设备上报物模型数据时，物联网平台将按设置的数据校验方式，根据物模型定义进行数据校验。

数据校验分为三种类型：


类型	适用范围	说明
强校验	对于2020年10月14日之前（不含当日）创建的产品，强校验为唯一的校验方式。	校验所有字段，仅流转校验通过的数据。校验通过的数据展示在物联网平台控制台对应设备的设备详情页物模型数据页签。校验不通过的数据则不展示。
弱校验	对于2020年10月14日至2020年12月31日（含当日）创建的产品，不再支持修改当前的校验方式。在2021年01月01日之后（含当日）创建产品时，需选择数据校验方式为弱校验或免校验。产品创建完成后，不可再修改。具体操作，请参见创建产品。	只校验设备数据的idetifier和dataType字段，不校验其他字段，流转全量数据。校验通过的数据展示在物联网平台控制台对应设备的设备详情页物模型数据页签。校验不通过的数据则不展示。通过流转数据中的参数checkFailedData，可查看校验不通过的数据。更多信息，请参见数据格式。
免校验		对上报的数据不进行校验，流转全量数据。数据不展示在物联网平台控制台对应设备的设备详情页物模型数据页签。

API	描述
CreateThingModel	为指定产品的物模型新增功能，支持定义物模型扩展描述。
UpdateThingModel	更新指定产品物模型中的单个功能，支持更新物模型扩展描述。
QueryThingModel	查看指定产品的物模型中的功能定义详情。
PublishThingModel	发布指定产品的物模型。
GetThingModelTsl	查询指定产品的物模型。

物模型TSL格式

物模型使用流程

物模型数据校验

相关API