通用定义

更新时间:2019-02-19 14:05:57

概述

人居PaaS平台是一套为企业用户提供集阿里云设备接入、APP端开发、SaaS端开发支持于一体的产品。企业用户可以基于人居PaaS平台快速根据业务逻辑实现自己的SaaS平台。

本文档是人居PaaS平台提供的API的手册,说明每个API的参数、结果、使用场景和示例。

下图是人居PaaS平台API概览

API

共88个接口,其中

  • 设备 17个

  • 空间 13个

  • 空间模板 12个

  • 场景 14个

  • 场景模板 22个

  • 锁 10个

使用须知

注意

  1. 服务在使用前,需联系商务同学对appKey授权
  2. 最新api版本1.0.0
  3. 使用appKey和appSecret
  4. 接口支持协议类型 http https
  5. 支持访问格式 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。

results matching ""

    No results matching ""