设备API

更新时间:2020-07-30 10:11:37

概述

设备服务是与设备相关的一组服务接口,为用户提供设备的查询、控制和关系服务能力。

本文档整体分为两部分

第一部分数据定义,这些数据结构会频繁在接口中使用;

第二部分接口定义,说明接口的入参、出参和示例。

接口分为两类:

基本操作接口

接口名 简介
控制设备 实现设备的控制。可以获取设备属性、设备设备属性和执行服务。
获取设备TSL 获取设备的物模型。
获取产品TSL 获取产品的物模型。
查询品类列表 查询品类列表。
查询设备 分页查询租户下的设备。
更新设备的备注名 更新设备的备注名。
重置设备 重置设备,解析所有关系和权限,并把设备从当前租户下移除。
查询子设备网关 查询子设备所属的网关。
查询设备详情 查询设备详细信息。
查询网关的子设备 查询网关下的子设备列表。
根据PK、DN查询设备信息 根据PK、DN查询设备信息。
绑定公区设备 根据PK、DN或者iotId绑定租户或者授权过的设备。

用户与设备的相关接口

接口名 简介
绑定用户与设备 建立用户与设备的逻辑关系。
解绑用户与设备 解除用户与设备的逻辑关系。
授权用户某设备的权限 给用户添加某个设备的管理员权限。
查询用户的设备 查询用户的关联设备。
查询设备的用户 查询设备的关联用户。
查询设备的用户(带角色) 查询设备的关联用户(带角色版本)。

数据定义

设备信息deviceInfo

名称 类型 备注
iotId String 设备ID
productImage String 设备的产品图片
deviceName String 设备名DeviceName
nickName String 用户对设备设置的昵称
productKey String 设备ProductKey
productName String 设备的产品名称
netType String 产品入网方式
nodeType String 产品类型,0 DEVICE 1 GATEWAY
categoryName String 设备所属品类名称
categoryKey String 设备所属品类key
thingType String 设备的类型: "VIRTUAL", "WEB", "APP","DEVICE"
status Integer 设备的状态: 0-初始化;1-在线;3-离线;8-禁用
spaceNamePath String 设备所属空间路径名称
lastOnlineTime String 设备最后上线时间
attributeList JSONArray 设备属性列表,见定义

设备属性attribute

名称 类型 备注
iotId String 设备ID
batchId String 批次ID
group String 设备分组
attribute String 设备属性名
value JSONObject 设备属性值
gmtModified String 设备状态变化时间,须大于前一次同一个属性值的更新时间。

接口定义

设备配网接入

人居开放平台内使用的设备需要通过设备配网接入到平台中。完成了配网接入的设备,可以使用本文档内的接口实现设备的控制、查询、关联操作。

控制设备

实现设备的控制。

支持三种控制类型,通过控制命令的type参数来区分

  1. 获取设备的属性 type=GET_PROPERTIES

  2. 设置设备的属性 type=SET_PROPERTIES

  3. 调用设备的服务 type=INVOKE_SERVICE

/home/paas/device/control
  • 当前版本 1.0.0

入参

字段名 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
targetId String 设备ID,是所有执行命令的目标设备。
commands JSONArray 控制命令列表,命令格式见下面的CommandInfo定义。

CommandInfo

字段名 类型 必填 备注
type String 命令类型:SET_PROPERTIES 设置设备属性;INVOKE_SERVICE 服务调用; GET_PROPERTIES 获取设备属性
data Map 要执行的具体操作:其参数结构详见下文示例

示例

以下示例说明如何使用“控制设备”接口实现“获取属性”、“设置属性”和“调用服务”。

获取属性-示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10

获取设备的属性值,仅传参type=GET_PROPERTIES即可。

获取到的设备属性与“获取设备TSL”接口->“TSL数据定义”中->properties的定义相同。

请求参数如下:

{
  "operator":{
      "hid":"1111299939433",
      "hidType":"OPEN"
  },
  "targetId": "nOv2JqehdKHQHfVnrJ2L0010366f10",
  "commands": [
    {
      "data": {},
      "type": "GET_PROPERTIES"
    }
  ]
}

设置属性-示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10

要将设备属性"WorkMode" 的值设置为0。(设备属性名参考“获取设备TSL”接口->“TSL数据定义”中->properties)

请求参数如下:

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "commands":[
        {
            "data":{
                "PasswordLength":0
            },
            "type":"SET_PROPERTIES"
        }
    ]
}

调用服务-示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10

调用设备的服务“addKeys” ,服务参数为LockType=2, UserLimit=1。(设备服务参考“获取设备TSL”接口->“TSL数据定义”中->services)

请求参数如下:

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "commands":[
        {
            "data":{
                "args":{
                    "LockType":2,
                    "UserLimit":1
                },
                "method":"AddKey" 
            },
            "type":"INVOKE_SERVICE"
        }
    ]
}

获取设备TSL

获取设备的物模型(TSL)。

物模型,简称TSL,即Thing Specification Language。描述了产品是什么,能做什么,可以提供哪些服务,详细定义见“物模型”。

TSL中的services定义了设备支持的服务,properties定义了设备支持的属性,events定义了设备支持事件。关于TSL数据结构的定义,见“TSL数据定义”的定义。

/home/paas/device/tsl/get
  • 当前版本 1.0.0

入参

字段名 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
必须是有效的用户,用于记录接口操作者信息,不影响结果。
iotId String 设备ID,最大长度64。

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

字段名 类型 备注
data JSONObject TSL数据,见TSL数据定义

Remarks

使用范围

可以获取租户下所有完成了配网绑定设备的TSL信息,不能获取未配网设备或其它租户的设备的TSL。

权限

支持非登录态登录态。通常从B端调用时,使用非登录态。不建议从C端直接调用接口,如果使用则尽量以登录态访问(使用从鉴权服务拿到的iotToken作为请求参数)。

常见错误

错误码 处理建议
781 没有访问设备的权限。
1. 说明设备不在当前租户内,要检查设备ID是否正确。
2. 如果设备已经重置,也会报这个错误,可以尝试重新配网绑定。
62101 请求的设备不存在。
1. 检查请求的设备ID是否正确。
2. 如果确认设备ID无误,可以尝试重新配网绑定。

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

控制的设备ID是pp7Vy7zPg2SsL9hxRvIc0010695c10

请求参数如下:

请求示例

{ 
  "operator":{
      "hid":"1111299939433",
      "hidType":"OPEN"
  },
  "iotId": "pp7Vy7zPg2SsL9hxRvIc0010695c10"
]

返回示例

{
  "code": 200,
  "data": {
    "schema": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
    "profile": {
      "productKey": "a17FE8wdZOj"
    },
    "services": [
      {
        "outputData": [

        ],
        "identifier": "set",
        "inputData": [
          {
            "identifier": "PasswordLength",
            "dataType": {
              "specs": {
                "min": "6",
                "unitName": "无",
                "max": "15",
                "step": "1"
              },
              "type": "int"
            },
            "name": "密码长度"
          }
        ],
        "method": "thing.service.property.set",
        "name": "set",
        "required": true,
        "callType": "async",
        "desc": "属性设置"
      },
      {
        "outputData": [
          {
            "identifier": "LockState",
            "dataType": {
              "specs": {
                "0": "关闭",
                "1": "开启"
              },
              "type": "bool"
            },
            "name": "门锁状态"
          },
          {
            "identifier": "PasswordLength",
            "dataType": {
              "specs": {
                "min": "6",
                "unitName": "无",
                "max": "15",
                "step": "1"
              },
              "type": "int"
            },
            "name": "密码长度"
          }
        ],
        "identifier": "get",
        "inputData": [
          "LockState",
          "PasswordLength"
        ],
        "method": "thing.service.property.get",
        "name": "get",
        "required": true,
        "callType": "async",
        "desc": "属性获取"
      }
    ],
    "properties": [
      {
        "identifier": "LockState",
        "dataType": {
          "specs": {
            "0": "关闭",
            "1": "开启"
          },
          "type": "bool"
        },
        "name": "门锁状态",
        "accessMode": "r",
        "required": true
      },
      {
        "identifier": "PasswordLength",
        "dataType": {
          "specs": {
            "min": "6",
            "unitName": "无",
            "max": "15",
            "step": "1"
          },
          "type": "int"
        },
        "name": "密码长度",
        "accessMode": "rw",
        "required": false,
        "desc": "密码长度"
      }
    ],
    "events": [
      {
        "outputData": [
          {
            "identifier": "LockState",
            "dataType": {
              "specs": {
                "0": "关闭",
                "1": "开启"
              },
              "type": "bool"
            },
            "name": "门锁状态"
          },
          {
            "identifier": "PasswordLength",
            "dataType": {
              "specs": {
                "min": "6",
                "unitName": "无",
                "max": "15",
                "step": "1"
              },
              "type": "int"
            },
            "name": "密码长度"
          }
        ],
        "identifier": "post",
        "method": "thing.event.property.post",
        "name": "post",
        "type": "info",
        "required": true,
        "desc": "属性上报"
      },
      {
        "outputData": [
          {
            "identifier": "ErrorCode",
            "dataType": {
              "specs": {
                "0": "正常"
              },
              "type": "enum"
            },
            "name": "故障代码"
          }
        ],
        "identifier": "Error",
        "method": "thing.event.Error.post",
        "name": "故障上报",
        "type": "error",
        "required": true
      },
      {
        "outputData": [
          {
            "identifier": "KeyID",
            "dataType": {
              "specs": {
                "length": "10"
              },
              "type": "text"
            },
            "name": "钥匙ID"
          },
          {
            "identifier": "LockType",
            "dataType": {
              "specs": {
                "1": "指纹",
                "2": "密码",
                "3": "卡",
                "4": "机械钥匙"
              },
              "type": "enum"
            },
            "name": "开锁方式"
          }
        ],
        "identifier": "DoorOpenNotification",
        "method": "thing.event.DoorOpenNotification.post",
        "name": "开门通知",
        "type": "info",
        "required": true
      },
      {
        "outputData": [

        ],
        "identifier": "TamperAlarm",
        "method": "thing.event.TamperAlarm.post",
        "name": "防撬报警",
        "type": "alert",
        "required": true
      },
      {
        "outputData": [

        ],
        "identifier": "LowElectricityAlarm",
        "method": "thing.event.LowElectricityAlarm.post",
        "name": "低电量报警",
        "type": "alert",
        "required": true
      },
      {
        "outputData": [

        ],
        "identifier": "DoorUnlockedAlarm",
        "method": "thing.event.DoorUnlockedAlarm.post",
        "name": "门未锁好报警",
        "type": "alert",
        "required": true
      }
    ]
  }
}

TSL数据定义

{
    "schema": "物的TSL描述schema",
    "link": "云端系统级uri,用来调用服务/订阅事件",
    "profile": {
        "productKey": "产品key",
        "deviceName": "设备名称"
    },
    "properties": [
        {
            "identifier": "属性唯一标识符(产品下唯一)",
            "name": "属性名称",
            "accessMode": "属性读写类型,只读(r),读写(rw)",
            "required": "是否是标准功能的必选属性",
            "dataType": {
                "type": "属性类型: int(原生),float(原生),double(原生), text(原生),date(String类型UTC毫秒),bool(0或1的int类型),enum(int类型), struct(结构体类型,可包含前面6种类型),array(数组类型,支持int/double/float/text)",
                "specs": {
                    "min": "参数最小值(int, float, double类型特有)",
                    "max": "参数最大值(int, float, double类型特有)",
                    "unit": "属性单位, 参考(https://lark.alipay.com/bvm9rw/khct3d/mfedgo)",
                    "unitName": "单位的名称, 参考https://lark.alipay.com/bvm9rw/khct3d/mfedgo",
                    "size":"数组大小,默认最大128(数组特有)",
                    "item": {
                        "type":"数组元素的类型"
                    }
                }
            }
        }
    ],
    "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类型), struct(结构体类型,可包含前面6种类型),array(数组类型,支持int/double/float/text)",
                        "specs": {
                            "min": "参数最小值(int, float, double类型特有)",
                            "max": "参数最大值(int, float, double类型特有)",
                            "unit": "属性单位, 参考(https://lark.alipay.com/bvm9rw/khct3d/mfedgo)",
                            "unitName": "单位的名称, 参考https://lark.alipay.com/bvm9rw/khct3d/mfedgo",
                            "size":"数组大小,默认最大128(数组特有)",
                            "item": {
                                "type":"数组元素的类型"
                            }
                        }
                    }
                }
            ],
            "method": "事件对应的方法名称(根据identifier生成)"
        }
    ],
    "services": [
        {
            "identifier": "服务唯一标识符(产品下唯一,产品下唯一,其中set/get是根据属性的accessMode默认生成的服务)",
            "name": "服务名称",
            "desc": "服务描述",
            "callType": "async(异步调用),sync(同步调用)"
            "required": "是否是标准功能的必选服务",
            "inputData": [
                {
                    "identifier": "入参唯一标识符",
                    "name": "入参名称",
                    "dataType": {
                        "type": "属性类型: int(原生),float(原生),double(原生), text(原生),date(String类型UTC毫秒),bool(0或1的int类型),enum(int类型), struct(结构体类型,可包含前面6种类型),array(数组类型,支持int/double/float/text)",
                        "specs": {
                            "min": "参数最小值(int, float, double类型特有)",
                            "max": "参数最大值(int, float, double类型特有)",
                            "unit": "属性单位, 参考(https://lark.alipay.com/bvm9rw/khct3d/mfedgo)",
                            "unitName": "单位的名称, 参考https://lark.alipay.com/bvm9rw/khct3d/mfedgo",
                            "size":"数组大小,默认最大128(数组特有)",
                            "item": {
                                "type":"数组元素的类型"
                            }
                        }
                    }
                }
            ],
            "outputData": [
                {
                    "identifier": "出参唯一标识符",
                    "name": "出参名称",
                    "dataType": {
                        "type": "属性类型: int(原生),float(原生),double(原生), text(原生),date(String类型UTC毫秒),bool(0或1的int类型),enum(int类型), struct(结构体类型,可包含前面6种类型),array(数组类型,支持int/double/float/text)",
                        "specs": {
                            "min": "参数最小值(int, float, double类型特有)",
                            "max": "参数最大值(int, float, double类型特有)",
                            "unit": "属性单位, 参考(https://lark.alipay.com/bvm9rw/khct3d/mfedgo)",
                            "unitName": "单位的名称, 参考https://lark.alipay.com/bvm9rw/khct3d/mfedgo",
                            "size":"数组大小,默认最大128(数组特有)",
                            "item": {
                                "type":"数组元素的类型(数组特有)"
                            }
                        }
                    }
                }
            ],
            "method": "服务对应的方法名称(根据identifier生成)"
        }
    ]

获取产品TSL

获取产品的物模型(TSL),可查询产品的范围为 产品列表接口 返回结果中的所有产品。

物模型,简称TSL,即Thing Specification Language。描述了产品是什么,能做什么,可以提供哪些服务,详细定义见“物模型”。

TSL中的services定义了设备支持的服务,properties定义了设备支持的属性,events定义了设备支持事件。关于TSL数据结构的定义,见“TSL数据定义”的定义。

/thing/tsl/getByProducyKey
  • 当前版本 1.0.2

入参

字段名 类型 必填 备注
productKey String 产品key
deviceName String 设备名称。

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

字段名 类型 备注
data JSONObject TSL数据,见TSL数据定义

具体参考

接口详情描述

查询品类列表

获取人居品类列表

查询维度 categoryName superId

categoryName: 品类名称,支持模糊查询

superId: 父品类Id,某些品类存在层级结构,superId表示某的品类Id

            superId为null时,查询所有品类列表;

            superId不为null时,查询当前品类下的子品类列表;
  1. superId为空,categoryName为空,全量筛选,支持分页

  2. superId为空,categoryName不为空,模糊匹配categoryName,全量范围内筛选,支持分页

  3. superId不为空,categoryName为空,查询父id为superId的品类列表,支持分页

  4. superId不为空,categoryName不为空,查询父id为superId,且其品类名称模糊匹配categoryName的的品类列表,支持分页

  5. superId为0时,是在一级品类范围内筛选,支持分页

/home/paas/category/list
  • 当前版本 1.0.0

入参

字段名 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
categoryName String 品类名称筛选,支持模糊匹配
superId Long 父id
pageNo int 查询页码
pageSize int 页码大小

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

字段名 类型 备注
data JSONArray 分页数据,品类数据详情见CategoryInfo
total Integer 总条数
pageNo Integer 请求的页码,见“分页参数”定义。
pageSize Integer 请求的页码,见“分页参数”定义。

CategoryInfo信息

字段名 类型 备注
categoryId String 品类ID
categoryName String 品类名
categoryKey String 品类key
imageUrl String 品类图片
state Integer 品类状态:0无效,1有效
superId Long 父品类Id

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

查询匹配名称“智能”的品类列表,查询范围:全范围(superId为空)

请求参数如下:

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  }
  "pageNo":1,
  "pageSize":20
  "categoryName":"智能"
}

返回示例

{
  "code": 200,
  "data": {
    "data": [
      {
        "categoryKey": "SmartLife",
        "state": 1,
        "superId": 0,
        "class": "com.aliyun.iotx.homelink.aquarius.hsf.dto.device.CategoryDTO",
        "categoryName": "智能生活",
        "categoryId": 274
      },
      {
        "categoryKey": "campus",
        "state": 1,
        "superId": 0,
        "class": "com.aliyun.iotx.homelink.aquarius.hsf.dto.device.CategoryDTO",
        "categoryName": "智能园区",
        "categoryId": 623
      },
      {
        "imageUrl": "url",
        "categoryKey": "SmartCity",
        "state": 1,
        "superId": 0,
        "class": "com.aliyun.iotx.homelink.aquarius.hsf.dto.device.CategoryDTO",
        "categoryName": "智能城市",
        "categoryId": 1
      },
      {
        "categoryKey": "SmartIndustry",
        "state": 1,
        "superId": 0,
        "class": "com.aliyun.iotx.homelink.aquarius.hsf.dto.device.CategoryDTO",
        "categoryName": "智能工业",
        "categoryId": 300
      }
    ],
    "pageNo": 1,
    "pageSize": 10,
    "total": 4
  },
  "message": "success",
}

查询设备

查询租户接入的所有设备,以分页列表方式返回。

查询的范围是所有完成了配网接入的、与用户产生关联的设备。

/home/paas/device/list
  • 当前版本 1.0.0

入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
pageInfo JSONObject 分页查询参数,见“分页参数”定义。

出参

返回结果使用通用结果类型,data域是分页查询结果对象(下表中的data是分页结果中的数据),见下表的详细说明:

参数 类型 备注
data JSONArray 分页数据,见设备信息定义。
total Integer 总条数
pageNo Integer 分页页码
pageSize Integer 分页大小

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

查询所有接入的设备列表,查询第1页,每页20条记录。

请求参数如下:

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "pageQuery": {
    "pageNo":1,
    "pageSize":20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "iotId": "tMbycP1picrKhT0HQDCk001034b510",
        "spaceNamePath": "/根节点1/",
        "attributeList": [
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1547797068655,
            "attribute": "LightMode",
            "batchId": "ce354176212c47448b6a7e97e2c85705",
            "value": 0
          },
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1548036653624,
            "attribute": "LightSwitch",
            "batchId": "188cde35f2544526b9660abfc60b4b6a",
            "value": 1
          }
        ],
        "thingType": "DEVICE",
        "productKey": "a1mB9mXoz0q",
        "deviceName": "fordev",
        "productName": "带服务的灯_qw",
        "status": 1,
        "productImage": "https://img.alicdn.com/tps/TB1_I0aPXXXXXajXpXXXXXXXXXX-100-82.png",
        "nickName": "dev1",
        "lastOnlineTime": "2019-01-01 12:00:00"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

更新设备的备注名

设置单个设备的备注名。

主要用于设备详情页显示设备别名,前提需要发起请求的用户与设备已绑定,每个设备至多有一个备注名,nickName传入null时表示删除(清空)设备的备注名。

/home/paas/device/nickname/update
  • 当前版本 1.0.1

入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
iotId String 设备ID
nickName String 备注名,最大长度64字符

出参

返回结果使用通用结果类型,不使用data域,无值。

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

修改的设备ID是tMbycP1picrKhT0HQDCk001034b510

新名称为“deviceA

请求参数如下:

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "iotId": "tMbycP1picrKhT0HQDCk001034b510",
  "nickName": "deviceA"
}

返回示例

{
  "code": 200,
  "message": "success"
}

重置设备

实现云端设备重置。

设备的重置方式有三种:

1、硬件重置:用户在硬件上按reset键

2、云端重置:B端SaaS通过云云接口触发设备(云端)重置

3、C端重置:用户在App的设备管理中,点击“删除设备”

设备配网后即接入了业务平台,可以使用重置设备的接口主动从云端解绑与设备相关的所有业务关系。

主要流程有:

1、reset设备是否是网关设备

  1. 如果是网关设备

    1、解除与每个子设备相关的所有关系,包括:用户、空间、场景

    2、删除每个子设备的权限点

    3、发送reset complete消息给B端SaaS平台

2、解除与设备相关的所有关系,包括:用户、空间、场景

3、删除每个子设备的权限点

4、发送网关设备的reset complete消息给B端SaaS平台

注意:这个接口不会触发设备端的reset逻辑,所以云端重置后,如wifi类型的已配网设备可能仍保留配网信息连接在网络上。但从用户角度,已经查询不到这个设备,也接收不到这个设备的任何上报数据。

/home/paas/device/reset
  • 当前版本 1.0.1

入参

参数 类型 是否必填 备注
operator JSONObject 操作员,见“身份信息”定义。
iotId String 要重置的设备ID

出参

返回结果使用通用结果类型,data域是对象,类型是DeviceResetResult,见下面的详细说明:

DeviceResetResult

参数 类型 备注
iotId String 解绑的设备ID
users JSONArray 设备在重置前的关联用户列表,见DeviceUser定义
spaces JSONArray 设备在重置前的关联空间列表,见DeviceSpace定义
scenes JSONArray 设备在重置前的关联场景列表,见DeviceScene定义
children JSONArray 子设备的重置信息,见DeviceResetResult定义。这是个嵌套结构,最多只嵌套一层,即一个网关设备带所性的子设备重置信息。

DeviceUser

参数 类型 备注
identity JSONObject 设备的关联用户,见“身份信息”定义。
role String 用户对设备的角色

DeviceSpace

参数 类型 备注
id String 空间ID
name String 空间名称
rootSpaceId String 空间的根节点
parentId String 空间的父节点
typeCode String 空间类型代码
typeName String 空间类型名称

DeviceScene

参数 类型 备注
id String 场景ID

设备的重置数据用异步的方式通过HTTP2通道发给用户。消息数据见DeviceResetResult定义。

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

要重置的设备ID是ODFL8xIUDLrtAnfNw90v001020ae10

请求参数如下:

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10"
}

返回示例

{
  "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10",
  "deviceType":"GATEWAY",
  "users":[
    {
      "identity":{
        "hid":"1111299939433",
        "hidType":"OPEN",
        "appKey":"1234"
      }
    }
  ],
  "spaces":[
    {
      "id":"space_id_1",
      "name":"卧室",
      "parentId":"parent_space_id_1",
      "typeCode":"HOUSE",
      "typeName":"房屋"
    }
  ],
  "scenes":[],
  "children":[
    {
      "iotId":"child_device_1",
      "deviceType":"GATEWAY",
      "users":[
        {
          "identity":{
            "appKey":"1234",
            "hid":"abcd1234",
            "hidType":"OPEN"
          }
        }
      ],
      "spaces":[
        {
          "id":"space_id",
          "name":"卧室",
          "parentId":"parent_space_id_1",
          "typeCode":"HOUSE",
          "typeName":"房屋"
        }
      ],
      "scenes":[
        {
          "id":"scene_id_2"
        }
      ],
      "children":[]
    }
  ]
}

查询子设备网关

/home/paas/device/gateway/get
  • 当前版本 1.0.1

    入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
iotId String 要查询的子设备ID,接口会检查设备的有效性。

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数 类型 备注
data JSON 包含网关的productKey, deviceName以及iotId

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

要重置的设备ID是ODFL8xIUDLrtAnfNw90v001020ae10

请求参数如下:

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10"
}

返回示例

{
    "iotId":"4I0flISLFCDTMeE63LfG001085c000",
    "deviceName":"gridlink_gateway_01",
    "productKey":"a17x7h7FlsH",
}

查询设备详情

每次请求至多查询20个设备。

/home/paas/device/detail/get
  • 当前版本
版本号 说明
1.0.0 初始版本,属性值列表中的value是JSON结构体(详见出参说明)
1.0.1 属性值列表中的value是String类型的JSON字符串
1.0.2 在1.0.1版本基础上,在出参中增加了节点类型和产品入网类型
1.0.3 在1.0.2版本基础上,在出参中增加了品类key和品类名称

入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
rootSpaceId String 顶层空间id。
iotIds JSONArray 要查询的设备。

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数 类型 备注
data JSONArray 属性详情信息见DeviceInfoDTO

DeviceInfoDTO信息

字段名 类型 备注
spaceId String 空间Id
spaceName String 空间名称
iotId String 设备id
productImage String 产品图片
deviceName String 设备名称
nickName String 设备昵称
productKey String 产品key
productName String 产品名
categoryKey String 品类key
categoryName String 品类名
nodeType String 节点类型(限1.0.2版本及以上)
netType String 产品入网类型(限1.0.2版本及以上)
status Integer 设备状态
isEdgeGateway Boolean 是否边缘网关
attributes JSONArray 属性值列表,属性定义见Attribute

Attribute信息

字段名 类型 备注
attribute String 属性名
value String 属性值

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

要重置的设备ID是ODFL8xIUDLrtAnfNw90v001020ae10

请求参数如下:

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10"
}

返回示例

{
  "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
  "code": 200,
  "message": null,
  "localizedMsg": null,
  "data": [
    {
      "spaceName": "孙子空间Ii",
      "spaceId": "e1e11a41574a4ad8945049e05178d53f",
      "iotId": "5LrQn6zlVQ0o1CITxr06000101",
      "attributes": [

      ],
      "productKey": "a1aF7LtSNk8",
      "isEdgeGateway": false,
      "deviceName": "light0",
      "productName": "带服务的灯",
      "status": 0
    },
    {
      "iotId": "nU0hWEGeqg8TNB5tCcfk000101",
      "attributes": [
        {
          "attribute": "CountDown",
          "value": "{}"
        },
        {
          "attribute": "CountDownList",
          "value": "{}"
        },
        {
          "attribute": "LocalTimer",
          "value": "[]"
        }
      ],
      "productKey": "a1aF7LtSNk8",
      "isEdgeGateway": false,
      "deviceName": "light2",
      "productName": "带服务的灯",
      "status": 0
    }
  ]
}

查询网关的子设备

/home/paas/device/sub/list
  • 当前版本 1.0.0

    入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
iotId String 网关设备ID
pageQuery JSONObject 分页查询参数,见“分页参数”定义。

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数 类型 备注
data JSONArray 分页数据,每个数据项中包含子设备的productKey、deviceName、iotId,以及是否接入人居平台。
total Integer 总条数
pageNo Integer 分页页码
pageSize Integer 分页大小

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

要查询的网关设备ID是ODFL8xIUDLrtAnfNw90v001020ae10

请求参数如下:

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"ODFL8xIUDLrtAnfNw90v001020ae10",
    "pageQuery":{
        "pageNo":1,
        "pageSize":10
    }
}

返回示例

{
  "total":1,
  "data":[
    {
      "iotId":"4I0flISLFCDTMeE63LfG001085c000",
      "deviceName":"gridlink_sub_01",
      "productKey":"a17x7h7FlsH",
      "belongsToHomelink":true
    }
  ],
  "pageNo":1,
  "pageSize":10
}

根据PK、DN查询设备信息

/home/paas/device/info/get

版本1.0.0

入参

字段名 类型 必传 备注
productKey String 设备PK
deviceName String 设备名称

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数 类型 描述
iotId String 设备ID
productKey String 设备PK
deviceName String 设备名称

示例

请求示例

{
   "productKey":"PK",
   "deviceName":"deviceName"
}

返回示例

{
   "code":200,
   "data":{
       "iotId":"iotId",
       "productKey":"PK",
       "deviceName":"deviceName"
   },
   "message":"success"
}

绑定公区设备

绑定公区设备,使设备接入人居平台。

仅对租户下的设备或者授权给该租户的设备有权限。

如果公区设备是边缘网关,会异步处理子设备绑定。如果ISV给后续操作预留等待时间,每设备50ms。

/home/paas/lp/device/bind
  • 当前版本 1.0.0

入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
iotId String 要绑定的设备ID,接口会检查设备的有效性,与productKey和deviceName不可同时为空。
productKey String 要绑定设备的产品的key
deviceName String 要绑定的设备名称 。
target JSONObject 要绑定用户账号列表,格式见“身份信息”定义。列表不允许为空,所有元素的hid类型必须一致。

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数 类型 备注
iotId String 设备iotId

绑定用户与设备

绑定用户设备的逻辑关系。

设备是已经完成配网的设备,见“设备配网接入”节的说明。

其它用户与设备的逻辑关系通过本接口和“解绑用户与设备”的接口维护。

接口支持批量操作,可以实现:

  • 一个设备与一个用户建立逻辑关系;

  • 一个设备与多个用户建立逻辑关系。

一个设备最多与1000个用户建立关系。

接口执行时会绑定尽可能多的关系,单个用户与设备的绑定失败不影响其它用户与设备的绑定。

如果完成后没有一个成功绑定的用户,接口会返回错码和消息,否则返回成功。

/home/paas/user/device/bind
  • 当前版本 1.0.1

入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
iotId String 要绑定的设备ID,接口会检查设备的有效性。
targetList JSONArray 要绑定用户账号列表,格式见“身份信息”定义。列表不允许为空,所有元素的hid类型必须一致。

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数 类型 备注
data JSONArray 这是一个组合结果的列表,每个元素都描述一个用户的绑定结果当输入用户中有重复时,结果列表中也会有重复结果项。

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10

要绑定到两个用户,用户使用了三方账号体系:

  1. 用户1,ID=3008045502161

  2. 用户2,ID=8189058505890,这是个错误的用户ID

请求参数如下:

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "targetList":[
        {
            "hid":"3008045502161",
            "hidType":"OPEN"
        },
        {
            "hid":"8189058505890",
            "hidType":"OPEN"
        }
    ]
}

返回示例

{
    "code":200,
    "message":"success",
    "data":[
        {
            "identity":{
                "hid":"3008045502161",
                "hidType":"OPEN"
            },
            "result":{
                "code":200,
                "message":"success"
            }
        },
        {
            "identity":{
                "hid":"8189058505890",
                "hidType":"OPEN"
            },
            "result":{
                "code":62107,
                "message":"No valid target user was found.",
                "localizedMsg":"没有有效的目标用户。"
            }
        }
    ]
}

表示

  • 第一个hid绑定成功

  • 第二个hid绑定失败,返回错误码是62107

解绑用户与设备

解除设备与用户的逻辑关系。

设备完成配网后,使用绑定用户与设备接口建立用户与设备的逻辑关系。这个接口是绑定操作的逆操作。

接口支持批量操作,可以实现:

  • 一个设备与一个用户解除逻辑关系;

  • 一个设备与多个用户解除逻辑关系。

接口执行时会解绑尽可能多的关系,单个用户与设备的操作失败不影响其它用户与设备的操作。

如果完成后没有一个成功解绑的用户,接口会返回错码和消息,否则返回成功。

/home/paas/user/device/unbind
  • 当前版本 1.0.1

入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
iotId String 要解绑的设备ID,接口会检查设备的有效性。
targetList JSONOArray 要解绑的用户账号列表,格式见“身份信息”定义。列表不允许为空,所有元素的hid类型必须一致。

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数 类型 备注
data JSONArray 这是一个组合结果的列表,每个元素都描述一个用户的解绑结果当输入用户中有重复时,结果列表中也会有重复结果项。

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10

要解绑的两个用户如下,使用了三方账号体系:

  1. 用户1,ID=3008045502161

  2. 用户2,ID=8189058505890,这是个错误的用户ID

请求参数如下:

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "targetList":[
        {
            "hid":"3008045502161",
            "hidType":"OPEN"
        },
        {
            "hid":"8189058505890",
            "hidType":"OPEN"
        }
    ]
}

返回示例

{
    "code":200,
    "message":"success",
    "data":[
        {
            "identity":{
                "hid":"3008045502161",
                "hidType":"OPEN"
            },
            "result":{
                "code":200,
                "message":"success"
            }
        },
        {
            "identity":{
                "hid":"8189058505890",
                "hidType":"OPEN"
            },
            "result":{
                "code":62107,
                "message":"No valid target user was found.",
                "localizedMsg":"没有有效的目标用户。"
            }
        }
    ]
}

授予用户对某设备的权限

授予设备与用户的权限。

接口支持批量操作,可以实现:

  • 设置一个用户在当前设备下的管理员/普通成员权限;

  • 设置多个用户在当前设备下的管理员/普通成员权限;

  • 如果一个用户已是设备管理员,授权为普通用户可以取消用户对当前设备的管理员权限。

设置用户为设备的管理员时,当前用户需与设备有绑定关系

接口执行时会授予尽可能多的权限,单个用户与设备的授权操作失败不影响其它用户与设备的操作。

如果完成后没有一个成功解绑的用户,接口会返回错码和消息,否则返回成功。

/home/paas/user/device/perm/auth
  • 当前版本 1.0.0

入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
iotId String 要授权的设备ID,接口会检查设备的有效性。
targetList JSONOArray 要解绑的用户账号列表,格式见“身份信息”定义。列表不允许为空,所有元素的hid类型必须一致。
roleCode String 要授权的类型
DEVICE_MANAGER 设备管理员权限。有删除设备、修改设备备注名的权限
DEVICE_MEMBER 设备的使用者,可以看到和使用设备,

出参

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数 类型 备注
data JSONArray 这是一个组合结果的列表,每个元素都描述一个用户的解绑结果当输入用户中有重复时,结果列表中也会有重复结果项。

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

控制的设备ID是nOv2JqehdKHQHfVnrJ2L0010366f10

要授权的两个用户如下,使用了三方账号体系:

  1. 用户1,ID=3008045502161

  2. 用户2,ID=8189058505890,这是个错误的用户ID

请求参数如下:

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotId":"nOv2JqehdKHQHfVnrJ2L0010366f10",
    "targetList":[
        {
            "hid":"3008045502161",
            "hidType":"OPEN"
        },
        {
            "hid":"8189058505890",
            "hidType":"OPEN"
        }
    ],
    "DEVICE_MANAGER"
}

返回示例

{
    "code":200,
    "message":"success",
    "data":[
        {
            "identity":{
                "hid":"3008045502161",
                "hidType":"OPEN"
            },
            "result":{
                "code":200,
                "message":"success"
            }
        },
        {
            "identity":{
                "hid":"8189058505890",
                "hidType":"OPEN"
            },
            "result":{
                "code":62107,
                "message":"No valid target user was found.",
                "localizedMsg":"没有有效的目标用户。"
            }
        }
    ]
}

查询用户的设备

查询与用户关联的设备列表。

接口返回使用“绑定用户与设备”接口建立逻辑关系的用户的设备。

/home/paas/user/device/list
  • 当前版本 1.0.0

入参

参数 类型 必填 备注
operator JSONObject 操作员,见“身份信息”定义。
target JSONObject 查询的目标用户,定义见“身份信息”。
pageInfo JSONObject 分页查询参数,见“分页参数”定义。

出参

返回结果使用通用结果类型,data域是分页查询结果对象(下表中的data是分页结果中的数据),见下表的详细说明:

参数 类型 备注
data JSONArray 分页数据,见设备信息定义。
total Integer 总条数
pageNo Integer 分页页码
pageSize Integer 分页大小

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

用户ID:1111299939433

查询该用户的设备列表。

请求参数如下:

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "target": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "pageInfo":{
    "pageNo": 1,
    "pageSize": 20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "iotId": "tMbycP1picrKhT0HQDCk001034b510",
        "spaceNamePath": "/根节点1/",
        "attributeList": [
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1547797068655,
            "attribute": "LightMode",
            "batchId": "ce354176212c47448b6a7e97e2c85705",
            "value": 0
          },
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1548036653624,
            "attribute": "LightSwitch",
            "batchId": "188cde35f2544526b9660abfc60b4b6a",
            "value": 1
          }
        ],
        "thingType": "DEVICE",
        "productKey": "a1mB9mXoz0q",
        "deviceName": "fordev",
        "productName": "带服务的灯_qw",
        "status": 1,
        "productImage": "https://img.alicdn.com/tps/TB1_I0aPXXXXXajXpXXXXXXXXXX-100-82.png",
        "nickName": "dev1",
        "lastOnlineTime": "2019-01-01 12:00:00"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

查询设备的用户

查询与设备有逻辑关系的用户列表。

/home/paas/device/user/list
  • 当前版本 1.0.1

入参

参数 类型 必填 备注
operator JSONObject 操作员,扩展“身份信息”定义。
iotId String 设备ID
pageQuery JSONObject 分页查询参数,见“分页参数”定义。

出参

返回结果使用通用结果类型,data域是分页查询结果对象(下表中的data是分页结果中的数据),见下表的详细说明:

参数 类型 备注
data JSONArray 分页数据,见身份信息定义。
total Integer 总条数
pageNo Integer 分页页码
pageSize Integer 分页大小

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

要查询的设备ID为tMbycP1picrKhT0HQDCk001034b510

查询第1页数据,每页最多20条记录。

请求参数如下:

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "iotId": "tMbycP1picrKhT0HQDCk001034b510",
  "pageQuery": {
    "pageNo":1,
    "pageSize":20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "hid": "1111299939433",
        "hidType": "OPEN"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

查询设备的用户(带角色)

查询与设备有逻辑关系的用户列表,用户信息上带有设备角色信息

  /home/paas/device/userrole/query
  • 当前版本 1.0.0

入参

参数 类型 必填 备注
operator JSONObject 操作员,扩展“身份信息”定义。
iotId String 设备ID
pageQuery JSONObject 分页查询参数,见“分页参数”定义。

出参

返回结果使用通用结果类型,data域是分页查询结果对象(下表中的data是分页结果中的数据),见下表的详细说明:

参数 类型 备注
data JSONArray 分页数据,扩展身份信息
增加role字段说明用户与设备的关系,取值DEVICE_MANAGER或DEVICE_MEMBER
total Integer 总条数
pageNo Integer 分页页码
pageSize Integer 分页大小

示例

例:

当前的操作员的用户ID是1111299939433,使用了三方账号体系。

要查询的设备ID为tMbycP1picrKhT0HQDCk001034b510

查询第1页数据,每页最多20条记录。

请求参数如下:

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "iotId": "tMbycP1picrKhT0HQDCk001034b510",
  "pageQuery": {
    "pageNo":1,
    "pageSize":20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "hid": "1111299939433",
        "hidType": "OPEN",
        "role":"DEVICE_MANAGER"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

results matching ""

    No results matching ""