本文介绍查询物模型的 API。

接口描述

查询指定设备的物模型定义。

接口地址

GET: /v2.0/cloud/thing/{device_id}/model

请求参数

参数名	类型	参数位置	是否必填	说明
device_id	String	path	true	设备 ID。

返回参数

参数名	类型	说明
result	Object	返回结果。

result 说明

参数名	类型	说明
model	String	物模型的功能定义。model 取值的数据格式说明，参见 model 字段数据说明。

请求示例

GET: /v2.0/cloud/thing/372817193*****/model

返回示例

{
    "result": {
        "model": "{\"modelId\":\"000004****\",\"services\":[{\"code\":\"\",\"description\":\"\",\"name\":\"\",\"actions\":[{\"code\":\"setPassword\",\"inputParams\":[{\"code\":\"password\",\"name\":\"密码\",\"typeSpec\":{\"typeDefaultValue\":\"\",\"type\":\"string\",\"maxlen\":1024}}],\"description\":\"app设置或者更新开门密码\",\"outputParams\":[{\"code\":\"state\",\"name\":\"状态\",\"typeSpec\":{\"max\":100,\"scale\":0,\"type\":\"value\",\"unit\":\"\",\"min\":1,\"step\":0}}],\"name\":\"设置密码\",\"abilityId\":104}],\"events\":[{\"code\":\"doorStateEvent\",\"description\":\"当触发开门后上报开门事件\",\"outputParams\":[{\"code\":\"doorState\",\"name\":\"门的状态\",\"typeSpec\":{\"range\":[\"开启\",\"关闭\"],\"type\":\"enum\"}}],\"name\":\"开门事件\",\"abilityId\":103}],\"properties\":[{\"code\":\"batterLevel\",\"description\":\"门锁电池电量\",\"accessMode\":\"rw\",\"name\":\"剩余电量\",\"typeSpec\":{\"max\":100,\"scale\":0,\"type\":\"value\",\"unit\":\"%\",\"min\":1,\"step\":0},\"abilityId\":102}]}]}"
    },
    "t": 1673423649773,
    "success": true
}

错误码

参考 错误码。

调用频率限制

参考 调用频率限制。

model 结构规范

调用物模型相关 API 时，返回参数中包含参数 model，该参数的取值格式为物模型功能定义在物联网平台系统的存储结构。

参数名	类型	说明
modelId	String	物模型 ID。
services	List	服务定义列表。

---

{
  "modelId": "00000****",
  "services": [
    {
      "code": "",
      "name": "",
      "description": "",
      "properties": [
      ],
      "actions": [
      ],
      "events": [
      ]
    }
  ]
}

service 结构规范

参数名	类型	说明
code	String	服务标识代码，空字符串代表默认服务。
name	String	服务名称。
description	String	对服务进行说明或备注。
properties	List	属性定义列表。关于属性数据结构中包含的参数说明，请参见 property 结构规范。
actions	List	动作定义列表。关于动作数据结构中包含的参数说明，请参见 action 结构规范。
events	List	事件定义列表。关于事件数据结构中包含的参数说明，请参见 event 结构规范。

property 结构规范

参数名	类型	说明
abilityId	Integer	整数型的能力标识 ID，同一个服务下唯一。
code	String	属性标识代码，空字符串代表默认属性。
name	String	属性名称。
description	String	对属性进行说明或备注。
accessMode	String	存取方式。ro：只读。wr：只写。rw：读写。
typeSpec	Object	数据类型规范，value, float, double, string, date, bool, enum, raw, bitmap, struct, array。请参见 typespec 数据结构规范。

action 结构规范

参数名	类型	说明
abilityId	Integer	整数型的能力标识 ID，同一个服务下唯一。
code	String	动作标识代码，同一个服务下唯一。
name	String	动作名称。
description	String	对动作进行说明或备注。
inputParams	List	动作的输入参数。数据结构说明，请参见 inputParam 与 outputParam结构规范。
outputParams	List	动作的输出参数。数据结构说明，请参见 inputParam 与 outputParam结构规范。

event 结构规范

参数名	类型	说明
abilityId	Integer	整数型的能力标识 ID，同一个服务下唯一。
code	String	事件标识代码，同一个服务下唯一。
name	String	事件名称。
description	String	对事件进行说明或备注。
outputParams	List	事件的输出参数。数据结构说明，请参见 inputParam 与 outputParam结构规范。

inputParam 与 outputParam 结构规范

参数名	类型	说明
code	String	参数标识代码。
name	String	参数名称。
typeSpec	Object	数据类型规范，value, float, double, string, date, bool, enum, raw, bitmap, struct, array)。请参见 typespec 类型结构规范。

typeSpec 类型结构规范

value 类型结构规范

32 位数值类型，支持整数或小数。

参数名	类型	是否必需	说明
type	String	是	取值为 value。
min	Integer	是	最小值。
max	Integer	是	最大值。
step	Integer	否	变化步长。
unit	String	否	单位，如：cm。
scale	Integer	否	倍数，用于表示小数。参数值是实际值乘以 10 的 scale 次方得到的乘积，默认为 0。

类型示例

{
  "type":"value",
  "min":1,
  "max":100,
  "step":0,
  "unit":"cm",
  "scale":0 
}

float 与 double 类型结构规范

float：单精度浮点数，double：双精度浮点数。

参数名	类型	是否必需	说明
type	String	是	取值为 float 或 double。
min	Integer	是	最小值。
max	Integer	是	最大值。
step	Integer	否	变化步长。
unit	String	否	单位，如：cm。

类型示例

{
  "type":"float",
  "min":0.1,
  "max":100.1,
  "step":0.1,
  "unit":"cm"
}

bool 类型结构规范

布尔类型，true/false。

参数名	类型	是否必需	说明
type	String	是	取值为 bool。

类型示例

{
    "type":"bool"
}

date 类型结构规范

时间戳类型，10 位（秒级）或 13 位（毫秒级）的整数。

参数名	类型	是否必需	说明
type	String	是	取值为 date。

类型示例

{
    "type":"date"
}

string 类型结构规范

字符串类型

参数名	类型	是否必需	说明
type	String	是	取值为 string。
maxlen	Integer	否	string：字符串最大长度为 255。

类型示例

{
    "type":"string",
    "maxlen":100
}

enum 类型结构规范

枚举

参数名	类型	是否必需	说明
type	String	是	取值为 enum。
range	List	是	枚举值。例如：取值为["男","女"]。

类型示例

{
   "type":"enum",
   "range": [
     "男","女"
    ]
}

raw 类型结构规范

原始类型，用 base64 编码的二进制原始数据。

参数名	类型	是否必需	说明
type	String	是	取值为 raw。原始类型，用 base64 编码的二进制原始数据。
maxlen	Integer	否	支持的最大的二进制字节数。

类型示例

{
  "type":"raw",
  "maxlen":128
}

bitmap 类型结构规范

位图类型，最大支持 32 位。

参数名	类型	是否必需	说明
type	String	是	取值为 bitmap。
maxlen	Integer	否	支持的最大位数，最大值为 32 位。
range	List	是	每个二进制位的说明描述。

类型示例

{
  "type":"bitmap",
  "maxlen":31,
  "lable":[
    "故障1","故障2"
  ]
}

struct 类型结构规范

复杂的结构嵌套。结构体属性的数据类型目前只支持 value, string, bool, enum, raw。

参数名	类型	是否必需	说明
type	String	是	取值为 struct。
properties	Object	是	结构体对象。例如：{"code1":"typeSpec","code2":"typeSpec"...}。key 为结构体的属性表示，value 为属性的数据类型规范，value, float, double, string, date, bool, enum, raw, bitmap, struct, array。请参见 typespec 类型结构规范。

类型示例

{
    "type":"struct",
    "properties":{
        "name":{
            "type":"date"
        },
        "sex":{
            "type":"enum",
            "range":[
                "男",
                "女"
            ]
        }
    }
}

array 类型结构规范

数组中元素的数据类型，目前只支持 value, string, bool, raw。

参数名	类型	是否必需	说明
type	String	是	取值为 array。
maxSize	Integer	否	支持的最大元素个数。
elementTypeSpec	Object	是	数组中元素的数据类型规范， value, float, double, string, date, bool, enum, raw, bitmap, struct, array。请参见 typespec 类型结构规范。

类型示例

{
    "type":"array",
    "maxSize":100,
    "elementTypeSpec":{
        "type":"date"
    }
}