通用数据定义

更新时间: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 ""