单个添加物模型

单个添加物模型

物模型包括属性、事件和服务。设备与物联网平台之间，可通过物模型实现多场景消息通信。本文介绍如何在物联网平台定义物模型。

前提条件

已创建产品。具体操作，请参见创建产品。

使用限制

• MQTT型实例下不支持物模型功能，无法添加物模型。
• 物模型需要在模块中配置，每个产品中默认模块和自定义模块总个数不能超过200个。
• 如果产品已发布，不能编辑物模型。如需编辑物模型，需先撤销产品发布。
• 可以编辑物模型历史版本，生成新的版本。
• 同一物模型最多保存最近的10个版本，多余的历史版本将被覆盖。
• 物模型编辑后，需发布才会正式生效。

定义物模型的更多使用限制，请参见使用限制。

添加自定义模块

当您需要不同模块管理物模型功能时，可添加自定义模块管理不同业务场景的物模型功能。

1. 登录物联网平台控制台。
2. 在控制台左上方，选择物联网平台所在地域。
3. 在实例概览页签的全部环境下，找到对应的实例，单击实例卡片。
4. 在左侧导航栏，选择*设备管理* > *产品*。在产品列表中，单击产品对应操作列的查看**。
5. 在产品详情页面，单击功能定义页签，然后单击前往编辑草稿。
6. 单击添加图标，完成参数配置，单击确认。

参数	说明
模块名称	支持中文、英文字母、日文、数字和下划线（_），长度限制为4～30个字符，一个中文、一个日文算1个字符。
模块标识符	模块唯一标识符，也是模块ID，在产品中具有唯一性。支持英文大小写字母、数字和下划线（_），长度限制为30个字符。
模块描述	输入文字，对模块进行说明或备注。长度限制为4096个字符。

添加自定义模块后，如果没有添加物模型并发布上线，返回功能定义页签，左侧模块列表不会展示该自定义模块。

添加物模型功能

1. 在产品详情页面，单击功能定义页签，然后单击前往编辑草稿，单击默认模块或添加模块。

2. 可选：从历史版本下拉菜单选择要编辑的历史版本，再单击恢复此版本，在历史版本的基础上编辑草稿。

3. 添加标准功能。如果您创建产品时选择了标准品类，则物联网平台已为该品类预定义标准功能。

   1. 标准功能分为必选和可选，使用如下：

      • 必选功能：已在物模型的默认模块中添加且不可删除。

      • 可选功能：单击添加标准功能，然后在弹出的双列表框左侧中，选择适用于该产品的标准功能。

        支持全选添加和全选删除。

      • 

   • 通用操作：您可单击功能对应操作列的编辑，修改标准功能定义。

     重要

     不支持修改标准功能的功能类型、标识符和数据类型。

4. 添加自定义功能。

   选择添加自定义功能。您可以为产品自定义属性、服务和事件。

• 自定义属性：在添加自定义功能对话框，选择功能类型为属性。设置参数完成后，单击确认。

  属性参数设置说明如下表。

  参数	描述
  功能名称	属性的名称，例如：用电量。同一产品下功能名称不能重复。支持中文、英文字母、日文、数字、短划线（-）、下划线（_）、正斜线（/）和英文句号（.），且必须以中文、英文、日文或数字开头，不超过30个字符。输入功能名称时，将从标准功能库中筛选匹配的标准功能供您选择，您可以参考标准功能进行配置。说明当接入网关协议为Modbus时，不支持标准属性，仅支持自定义属性。
  标识符	属性唯一标识符，在产品中具有唯一性。即Alink JSON格式中的identifier的值，作为设备上报该属性数据的Key，云端根据该标识符校验是否接收数据。支持英文、数字和下划线（_），不超过50个字符，例如：PowerConsumption。说明不能用以下系统保留参数作为标识符：set、get、post、property、event、time、value。
  数据类型	int32：32位整型。需定义取值范围、步长和单位符号。float：单精度浮点型。需定义取值范围、步长和单位符号。double：双精度浮点型。需定义取值范围、步长和单位符号。enum：枚举型。定义枚举项的参数值和参数描述，例如：1表示加热模式、2表示制冷模式。bool：布尔型。采用0或1来定义布尔值，例如：0表示关、1表示开。text：字符串。需定义字符串的数据长度，最长支持10240字节。date：时间戳。格式为String类型的UTC时间戳，单位：毫秒。struct：JSON对象。定义一个JSON结构体，新增JSON参数项，例如：定义灯的颜色是由Red、Green、Blue三个参数组成的结构体。不支持结构体嵌套。array：数组。需声明数组内的元素类型、数组元素个数。元素类型可选择int32、float、double、text或struct，需确保同一个数组元素类型相同。元素个数，限制1~512个。说明当设备协议为Modbus时，无需设置该参数。
  取值范围	数据类型为int32、float、double时，可设置属性值的取值范围。
  步长	属性值变化的最小粒度。数据类型为int32、float、double时，可根据您的业务需要设置步长。例如：为温度计产品定义温度属性时，将数据类型设置为int32，步长为2，单位为℃，取值范围0~100。即温度每变化两度，设备上报温度值，例如：0℃、2℃、4℃、6℃、8℃等。
  单位	单位可选择为无，或根据实际情况选择。
  读写类型	读写：请求读写的方法支持GET（获取）和SET（设置）。只读：请求只读的方法仅支持GET（获取）。说明当接入网关协议为Modbus时，无需设置该参数。
  描述	输入文字，对该功能进行说明或备注。长度限制为100个字符。
  扩展描述	扩展描述为设备通信协议到标准物模型的映射关系。对应物模型TSL中的物模型扩展配置。仅节点类型为网关子设备且接入网关协议为自定义、OPC UA或Modbus的产品，添加物模型属性时，显示且需填写该参数。接入网关协议为自定义时，填写JSON格式的自定义配置信息，长度限制为1024个字符。接入网关协议为OPC UA时，设置节点名称。节点名称需保证属性维度下唯一。接入网关协议为Modbus时，需设置以下参数：操作类型：离散量输入（只读，0x02）线圈状态（只读，0x01）线圈状态（读写，读取使用0x01，写入使用0x05）线圈状态（读写，读取使用0x01，写入使用0x0F）线圈状态（只写，0x05）线圈状态（只写，0x0F）保持寄存器（只读，0x03）保持寄存器（读写，读取使用0x03，写入使用0x06）保持寄存器（读写，读取使用0x03，写入使用0x10）保持寄存器（只写，0x06）保持寄存器（只写，0x10）输入寄存器（只读，0x04）寄存器地址：十六进制，必须以0x开头，且限制范围是0x0~0xFFFF，例如：0xFE。原始数据类型：支持int16、uint16、int32、uint32、int64、uint64、float、double、string、bool、bits。比特位置：原始数据类型选择bits时的参数。选择数据对应的位置。取值范围：这是原始数据经过缩放因子处理之后的取值范围。不在该取值范围内的数据会被丢弃。物联网平台已为各操作类型设置了默认取值范围：线圈状态类型：01离散量输入类型：01保持寄存器类型：-21474836482147483647输入寄存器类型：-21474836482147483647交换寄存器内高低字节：是否把寄存器内16位数据的前后8个bit互换（byte1byte2 -> byte2byte1）。true：互换。false：不互换。交换寄存器顺序：是否把原始数据32位数据的前后16个bit互换（byte1byte2byte3byte4 -> byte3byte4byte1byte2）。true：互换。false：不互换。缩放因子：整型或浮点型数字，默认值为1，不可以为0，不可以为负数。数据上报方式：可选按时上报和变更上报。

自定义服务：在添加自定义功能对话框，选择功能类型为服务。设置参数完成后，单击确认。

说明

接入网关的协议选择为Modbus时，不支持定义任何服务。

服务参数设置说明如下表。

参数	描述
功能名称	服务名称。支持中文、英文字母、日文、数字、短划线（-）、下划线（_）、正斜线（/）和英文句号（.），且必须以中文、英文、日文或数字开头，不超过30个字符。输入功能名称时，将从标准功能库中筛选匹配的标准功能供您选择，您可以参考标准功能进行配置。
标识符	服务唯一标识符，在产品下具有唯一性。即Alink JSON格式中该服务的identifier的值。支持英文、数字和下划线（_），不超过50个字符。说明不能用以下系统保留参数作为标识符：set、get、post、property、event、time、value。
调用方式	异步：服务为异步调用时，云端执行调用后直接返回结果，不会等待设备的回复消息。同步：服务为同步调用时，云端会等待设备回复；若设备没有回复，则调用超时。
输入参数	设置该服务的入参，可选。单击增加参数，在弹窗对话框中添加服务入参。当接入网关协议为OPC UA时，需设置参数索引，用于标记参数的顺序。说明不能用以下系统保留参数作为输入参数的标识符：set、get、post、property、event、time、value。您可以使用某个属性作为入参，也可以自定义参数。例如：在定义自动喷灌服务功能时，将已定义的属性喷灌时间和喷灌量作为自动喷灌服务的入参，则调用该参数时传入这两个参数，喷灌设备将按照设定的喷灌时间和喷灌量自动进行精准灌溉。一个服务最多支持定义20个入参。
输出参数	设置该服务的出参，可选。单击增加参数，在弹窗对话框中添加服务出参。当接入网关协议为OPC UA时，需设置参数索引，用于标记参数的顺序。说明不能用以下系统保留参数作为输出参数的标识符：set、get、post、property、event、time、value。您可以使用某个属性作为出参，也可以自定义参数，例如：将已定义的属性土壤湿度作为出参，则云端调用自动喷灌服务时，将返回当前土壤湿度的数据。一个服务最多支持定义20个出参。
扩展描述	扩展描述为设备通信协议到标准物模型的映射关系。对应物模型TSL中的物模型扩展配置。仅节点类型为网关子设备且接入网关协议为自定义或OPC UA的产品，添加物模型时，显示且需增加扩展描述。接入网关协议为自定义时，需传入JSON格式的自定义配置，长度不超过1024个字符。接入网关协议为OPC UA时，设置节点名称。节点名称需保证服务维度下唯一。
描述	输入文字，对该服务功能进行说明或备注。长度限制为100个字符。

自定义事件：在添加自定义功能对话框，选择功能类型为事件。设置参数完成后，单击确认。

说明

接入网关的协议选择为Modbus时，不支持定义任何事件。

事件参数设置说明如下。

参数	描述
功能名称	事件的名称。支持中文、英文字母、日文、数字、短划线（-）、下划线（_）、正斜线（/）和英文句号（.），且必须以中文、英文、日文或数字开头，不超过30个字符。输入功能名称时，将从标准功能库中筛选匹配的标准功能供您选择，您可以参考标准功能进行配置。
标识符	事件唯一标识符，在产品下具有唯一性。即Alink JSON格式中该事件的identifier的值，作为设备上报该事件数据的Key，例如：ErrorCode。 支持英文、数字和下划线（_），不超过50个字符。说明不能用以下系统保留参数作为标识符：set、get、post、property、event、time、value。
事件类型	您可以针对不同的事件类型进行业务逻辑处理和统计分析。信息：指设备上报的一般性通知，例如：完成某项任务。告警：设备运行过程中主动上报的突发或异常情况，告警类信息，优先级高。故障：设备运行过程中主动上报的突发或异常情况，故障类信息，优先级高。
输出参数	该事件的出参。单击增加参数，在弹窗对话框中添加一个服务出参。您可以使用某个属性作为出参，也可以自定义参数。例如：将已定义的属性电压作为出参，则设备上报该故障事件时，将携带当前设备的电压值，用于进一步判断故障原因。当接入网关协议为OPC UA时，需设置参数索引，用于标记参数的顺序。说明不能用以下系统保留参数作为输出参数的标识符：set、get、post、property、event、time、value。一个事件最多支持定义50个出参。
扩展描述	扩展描述为设备通信协议到标准物模型的映射关系。对应物模型TSL中的物模型扩展配置。仅节点类型为网关子设备且接入网关协议为自定义或OPC UA的产品，添加物模型时，显示且需增加扩展描述。接入网关协议为自定义时，需传入JSON格式的自定义配置，长度不超过1024个字符。接入网关协议为OPC UA时，设置节点名称。节点名称需保证事件维度下唯一。
描述	输入文字，对该事件功能进行说明或备注。长度限制为100个字符。

发布物模型

重要：物模型发布后，才会正式生效。

1. 单击功能定义的编辑草稿页面左下方的发布上线。控制台页面会弹出发布物模型上线？对话框。

2. 可选：单击添加发布备注，输入版本号和版本描述。

   参数	说明
   版本号	设置当前物模型版本号。后期可根据版本号管理物模型。版本号支持英文字母、数字和英文句号（.），长度限制1～16个字符。
   版本描述	描述当前版本物模型。支持中文汉字、英文字母、日文、数字和特殊符号。长度限制为100个字符。一个中文汉字算一个字符；一个日文算一个字符。

3. 如果存在已上线的版本，则需要进行比对，确认新版本的修改点。

   单击比对结果，在比对结果对话框中查看修改点。确认无误后，单击确认查阅，回到发布物模型上线对话框，自动选中“确认已查看当前版本与线上版本的比对结果”前的复选框。

   如果不需要比对，您可直接手动选中“确认已查看当前版本与线上版本的比对结果”前的复选框。

4. 单击确定，完成物模型的发布。

   发布物模型成功后，会直接返回产品详情页面的功能定义页签，您可看到当前物模型的版本号和上线时间。

   

执行结果

物模型发布后，物联网平台为该产品生成正式版本的物模型。在产品详情页面的功能定义页签下，您可以：

• 单击物模型TSL，查看JSON格式的物模型TSL。
• 单击生成设备端代码，下载物联网平台根据您定义的功能生成的设备端代码，用于设备端物模型功能开发。

重要

仅华东2（上海）地域的旧版公共实例支持生成设备端代码。实例说明，请参见实例概述。

相关API

API	描述
CreateThingModel	为指定产品的物模型新增功能，支持定义物模型扩展描述。
QueryThingModel	查看指定产品的物模型中的功能定义详情。
CopyThingModel	复制指定产品的物模型到目标产品。
PublishThingModel	发布指定产品的物模型。
ListThingTemplates	获取物联网平台预定义的产品品类列表。
GetThingTemplate	查询指定品类的标准物模型信息。
ListThingModelVersion	获取指定产品的物模型历史版本列表。
GetThingModelTsl	查询指定产品的物模型。
ImportThingModelTsl	为指定产品导入物模型TSL，暂不支持扩展描述配置。
QueryThingModelPublished	查看指定产品的已发布物模型中的功能定义详情。
GetThingModelTslPublished	查询指定产品的已发布物模型TSL。
QueryThingModelExtendConfig	导出指定产品的物模型扩展描述配置。
QueryThingModelExtendConfigPublished	导出已发布物模型的扩展描述配置。

后续操作

产品下设备上报的物模型数据默认会自动写入热数据存储空间，您可根据实际业务需要，停止部分或全部物模型的热数据存储服务。具体内容，请参见关闭或开启物模型数据存储。

相关文档

• 修改或删除已添加的物模型模块或物模型属性、事件和服务，请参见修改和删除物模型。
• 批量导入物模型文件或直接复制其他产品物模型，请参见批量添加物模型。
• 通过物模型实现设备与物联网平台通信的使用说明，请参见设备使用物模型通信。