通用数据定义

更新时间：2019-07-31 16:54:31

这里列出API中经常出现的通用参数说明。

通用返回结果

通用返回结果是所有接口的返回类型，用来封装错误码或返回数据。所有接口的结果都是下面的结构。

参数 类型 备注
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
OA: 指对接内建账号系统的用户ID
OA_PHONE: 指对接内建账号系统的账号的手机号
IOT: 指IOT内部账号系统的用户ID

在大部分的API中，第一个参数是operator，是操作员信息。语义上代表是“谁”在操作这个服务。
在一些创建类接口中（如创建空间），如果没有其它身份标识说明操作的目标，会用这个参数代表的用户关联到创建的实体上。
而实际应用中，一种用户法是在云端创建一个默认的操作员，填写这个参数。或者，把App端或Web端登录的用户，映射到operator上。

填值：

  • 如果是自建账号，hid=${openId}，hidType=OPEN

  • 如果是内置账号，hid=${phone}，hidType=OA_PHONE

    • C端使用：登录账号的手机号保存在上下文，作为与B端交互的身份标识。B端根据上传的手机号拼装身份信息参数。

列表参数

接口中JSONArray类型的入参，如果没有特殊说明，最大限制都为100。

例如，用户绑定设备时，一次最多绑定100个设备。

ID参数

标识类参数，不做特殊说明的情况下，类型均为字符串，最大长度为64。
支持大小写字母、数字、横线(-）和下划线(_)的组合。横线和下划线不能出现在开头和结尾，且不能连续出现。

举例来说，有效的ID

  • abc123

  • abc

  • 123

  • abc-abc

  • abc_abc_abc

  • abc-abc_abc

无效的ID

  • -abc123

  • abc123-

  • _abc

  • abc_

  • abc--abc

  • abc-_abc

  • abc__abc

results matching ""

    No results matching ""