通用定义
更新时间:2019-02-19 14:05:57
概述
人居PaaS平台是一套为企业用户提供集阿里云设备接入、APP端开发、SaaS端开发支持于一体的产品。企业用户可以基于人居PaaS平台快速根据业务逻辑实现自己的SaaS平台。
本文档是人居PaaS平台提供的API的手册,说明每个API的参数、结果、使用场景和示例。
下图是人居PaaS平台API概览
共88个接口,其中
设备 17个
空间 13个
空间模板 12个
场景 14个
场景模板 22个
锁 10个
使用须知
注意
- 服务在使用前,需联系商务同学对appKey授权
- 最新api版本1.0.0
- 使用appKey和appSecret
- 接口支持协议类型 http https
- 支持访问格式 post**
业务实体
用户
用户是人居PaaS平台的重要业务实体,可以和设备、空间、模块之间创建逻辑关系。通常,用户是企业SaaS平台的用户。
用户可以是使用了默认账号系统的用户,直接和人居PaaS对接。也可以使用了自有账号系统的用户,通过WebOA SDK批量导入用户。
用户在系统用Identity类型表示,hid字段代表用户标识,hidType字段代表用户账号类型。
使用默认账号系统时,hidType为OA。使用自有账号系统时,hidType为OPEN。
用户在接口中根据场景会使用operator、target等表示,代表操作员、操作目标等。
租户
租户是IoT平台对于B端用户创建的唯一的身份,所有与人居对接过的企业或者开发者,都会有唯一的租户ID作为标识。
租户之间,数据是隔离的。
设备
设备是智能人居开放平台的重要实体,代表一个实际的物理设备。
设备先由配网绑定接入到租户,然后通过设备&用户的绑定解绑**接口维护用户与设备的逻辑关系。
设备在接口定义中会使用device表示,用iotId表示设备的标识。
空间
空间是设备在现实世界中位置的抽象,例如,小区,单元,幢,房屋,房间,停车场等是属于不同类型的空间,当一个设备与空间绑定后,代表设备“存在”于这个空间中。
空间模板是一种固定的空间框架,用来简化空间的创建,用户可以使用一个空间模板创建出一组配置好的空间。空间可以独立创建出来,也可以通过空间模板创建出多个相似的空间。根据空间模板创建出来的空间具有与模板相同的结构。
空间与空间模板在接口中会使用space和spacetemplate表示。
场景
与空间类似,场景包括场景模板和场景实例,以下场景实例简称场景。场景为用户提供多设备联动、编排的能力,是智能家居的体现 。场景可以理解为一组设备联动规则,联动规则分触发器(trigger)、边界条件(condition)和动作(action)三部分:
trigger触发器,列在trigger中的每一项有任一项满足时就会尝试触发场景执行;
condition边界条件,当trigger触发后,如果列在condition中的每一项条件全部满足的时候,才会触发场景;
action是执行器,它是被控制的功能的集合,其中每一项在场景执行时会并发执行;
一个场景必须要包含action部分,而trigger,condition部分不是必选的。
场景会在满足trigger和condition时自动触发,也可以被手动触发。手动触发场景时,会无视trigger的存在,但仍然会判断是否满足condition。
使用场景,是为了能够自动调用设备服务、设置设备属性、给App发消息、触发其他场景、上报设备消息。不过我们也支持手动触发场景。被控制的功能包括设置物的属性,调用物的服务,向移动端发消息,触发其他场景执行,控制其他场景部署,向三方mq发消息等功能。
场景与场景模板在接口中会使用scene和scenetemplate表示。
错误码
统一错误码
返回值 | 信息 | 描述 |
---|---|---|
200 | success | 成功 |
400 | request error | 请求错误 |
401 | request auth error | 请求认证错误 |
403 | request forbidden | 请求被禁止 |
404 | service not found | 服务未找到 |
429 | too many requests | 太多请求 |
460 | request parameter error | 请求参数错误 |
500 | service error | 服务端错误 |
503 | service not available | 服务端错误 |
781 | Deny access to resources. | 无权访问资源 |
业务错误码
返回值 | 信息 | 描述 |
---|---|---|
62101 | Device not exists. | 设备不存在。 |
62102 | Target device has been bound. | 目标设备已经绑定过。 |
62103 | No matching group was found. | 没有查询到匹配的分组;内部错误 |
62104 | Failed to execute commands. | 控制设备失败 |
62105 | The type of device's command is invalid. | 设备命令类型不合法。 |
62106 | Failed to set properties to device. | 设备控制-设备属性设置值失败。 |
62107 | No valid target user was found. | 没有找到目标用户。 目标用户ID无效,没有查到相关信息 |
62108 | User without successful binding. | 没有绑定成功的用户。 批量绑定用户时,一个也没有成功,返回此错误。 |
62109 | Unbinding the main identity's device is not allowed. | 不允许解绑设备与主账号的绑定关系。 由于uc解绑设备与用户时,如果用户是主账号会解绑所有相关设备和member用户。所以暂时不允许解绑主账号。 |
62110 | No device binding data. | 没有设备绑定数据。 可能设备还没有完成配网流程,或在配网绑定时出错,导致数据不完整。 |
62111 | Device binding data is abnormal. | 设备绑定数据异常。 |
62112 | Tenant has no right to access DEVICE. | 租户没有设备的访问权限。 |
62113 | User does not have device permissions. | 用户没有设备权限。 |
62114 | User has no right to access DEVICE. | 用户没有设备的访问权限 |
62115 | Product not exist. | 产品不存在。 |
62116 | Device binding failed. | 设备绑定到空间失败 |
62117 | Device unbinding failed. | 设备从空间解绑失败 |
62200 | Device is not bound to the space | 设备没有与空间绑定 |
62201 | Some of deleted products do not belong to the space | 要删除的产品不属于当前空间模板 |
62202 | Nothing is modified | 修改空间模板时空间模板信息未更新 |
62203 | Space template access denied | 当前用户无权访问当前空间模板 |
62204 | Space not exist | 空间实例不存在 |
62205 | The type of device's command is invalid. | 设备命令类型不合法。 |
62206 | Space template has been bound | 要绑定的空间模板已全被绑定过,无需继续绑定 |
62207 | Space template doesn't exist | 模板id无效,找不到对应模板 |
62208 | Space template code invalid | 空间类型无效 |
62300 | Scene template service error | 场景模板服务错误 |
62301 | Scene template param error | 场景模板接口参数错误 |
62302 | Creating scene template error | 场景模板创建错误 |
62303 | Updating scene template error | 更新模板服务错误 |
62304 | Deleting scene template error | 删除模板服务错误 |
62305 | Product list search error | 查询产品列表错误 |
62400 | Device is not bound to the user | 设备没有与用户绑定 |
62401 | Space is not bound to the user | 空间没有与用户绑定 |
62402 | Invalid user info. | 无效的用户身份信息 |
62403 | No user info found. | 未能找到第三方用户信息。 |
62500 | Identity information error. | 身份信息错误。 |
62501 | No main identity info found. | 没有找到主账号信息。 |
62502 | No tenant info found. | 没有找到租户信息。 |
62503 | No identity info found. | 没有找到用户信息。 |
62504 | Device relation service error. | 设备关系服务异常。 |
62505 | Only part of the batch operation succeeds. | 批量操作部分成功。 |
62600 | Creating static password error. | 创建静态密码失败 |
62601 | Updating static password error.... | 更新静态密码失败 |
62602 | Fetching static password error | 获取静态密码失败 |
62603 | Updating static password rule error | 更新静态密码规则失败 |
62604 | Updating dynamic password rule error | 更新动态密码规则失败 |
62065 | Fetching dynamic password error. | 获取动态密码失败 |
62606 | Locking lock error. | 锁定门锁失败 |
62607 | Unlocking lock error. | 解锁门锁失败 |
62608 | Rule data must be json and not empty. | ruleData为必填项且格式为JSON |
通用定义
通用返回结果
通用返回结果是所有接口的返回类型,用来封装错误码或返回数据。所有接口的结果都是下面的结构。
参数 | 类型 | 备注 |
---|---|---|
code | Integer | 通用错误码 + API错误码 200 - 代表执行成功 非200 - 代表执行失败,错误信息见message字段 |
message | String | 提示信息 success - 代表接口执行成功,一般是code=200时,信息是success 其它信息 - 当code值为非200时,是对错误的详细描述。 |
data | Object | data域是数据域,定义有下面四种情况: 无数据,这时没有data字段,表示接口的返回值中没有结果; 数据为对象类型,表示为JSONObject,具体定义要根据接口而定; 数据为数组类型,表示为JSONArray,表示结果是一系列值,值的类型要根据接口而定; 数据为值类型,表示为具体的封装类型,如String, Integer, Long, Byte, Double,具体根据接口而定; |
分页参数
分页参数会出现在请求参数和返回结果中
在请求参数中代表请求分页的页数(pageNo)和每页的记录数(pageSize);
在响应结果中的页数(pageNo)和每页的记录数(pageSize)与请求参数一致,同时还有total字段代表数据总数。
所有的分页接口除特殊说明外,都遵循下面的约束
参数 | 类型 | 备注 |
---|---|---|
pageNo | Integer | 请求的页码 非必填,默认为1,有效范围 [1, ∞) |
pageSize | Integer | 每页的记录数 非必填,默认为20,有效范围[1,100] |
身份信息
身份信息(identity)通常用来指定具体的用户,在接口中像操作员和操作对象都使用身份信息封装。
例如:“用户A”要把“用户B”和“设备”建立逻辑关系,用户A是操作员,用户B是要绑定的对象,都统一用identity类型封装。
参数 | 类型 | 备注 |
---|---|---|
hid | String | 用户ID,必填 |
hidType | String | 用户ID的类型,可选,默认值为OPEN OPEN:指hid是自有账号系统的用户ID 其它支持的类型待扩展 |
列表参数
接口中JSONArray类型的入参,如果没有特殊说明,最大限制都为100。
例如,用户绑定设备时,一次最多绑定100个设备。
ID参数
标识类参数,不做特殊说明的情况下,类型均为字符串,最大长度为64。