-
1. 后端处理服务器API
- 1.1 数据库结构
- 1.2 后端处理服务器HTTP 接口
- 1.3. 数据包
-
2. 后端处理服务器应用集成API
- 2.1 设置应用集成
- 2.2 API 格式和签名机制
- 2.3 API 定义
- 3. 客户端扩展机制
-
4. 会话机器人开发指南
- 4.1 机器人应用开发
数据包的基本信息
- 2019-11-04 16:15:23
- 先知
- 10393
- 最后编辑:先知 于 2020-02-04 15:35:27
- 分享链接
本文档主要向大家介绍喧喧里数据包的类型、数据包组、定义对象属性、数据包实例、数据包简写、传输类型简写、定义对象属性、定义对象变量。
一、数据包类型
在喧喧系统中共存在三种数据包:
- 请求数据包:由客户端XXC发送给消息中转XXD 服务器,再由 消息中转 XXD 服务器转发给后端处理服务器XXB;
- 响应数据包:后端处理服务器XXB处理请求数据包后会向 消息中转XXD 服务器返回响应数据包,消息中转XXD 服务器处理之后会分发给客户端XXC;
- 推送数据包:由 消息中转XXD 服务器主动推送给客户端XXC的数据包。
二、数据包组
有时后端会一次性返回一个以上数据包,这些数据包以数据包组的形式返回给 XXD 服务器,XXD 服务器分别处理后再转发给客户端。数据包组以 JSON 对象数组的形式存储,例如:
[ { method: 'userLogin', data : userData, v: '2.4.0' }, { method: 'userGetlist', data: userDataList }, // ... 其他数据包 ]
三、数据包定义对象属性
数据包定义对象为类 JavaScript 纯对象,在传输的过程中会系列化为 JSON 字符串。通常一个数据包定义对象包含如下属性:
属性名称 | 类型 | 说明 |
---|---|---|
method | 字符串 | 必须项,操作方法名称,例如user_login表示登录方法 |
params | 数组 | 可选项,调用操作方法时的参数列表,例如['xuanxuan', 'user', 'password', 'online'] |
v | 字符串 | 可选项,表示发送该数据包方的版本号 |
lang | 字符串 | 可选项,表示客户端发送到服务器端时所使用的语言,例如'zh-cn'、'zh-tw'或'en' |
d | 字符串 | 可选项,表示客户端类型,可选值包括'desktop'(桌面端,默认)和'mobile'(移动端) |
userID | 字符串或数字 | 只有当不是登录验证数据包时为可选项,其他情况为必须项,表示该数据包对应的用户 ID |
rid | 字符串 | 请求 ID,通常在发起请求时为数据包生成一个全局唯一的字符串,用于标识并跟踪此数据包,后端服务器处理一个请求数据包时如果发现有此属性应该在响应数据包中也返回此属性和对应的值 |
在响应数据包和推送数据包对象中还可能包含如下属性:
属性名称 | 类型 | 说明 |
---|---|---|
result | 字符串 | 通常当值为'success'时表示操作成功,值为'fail'时表示操作失败 |
message | 字符串 | 通常当result属性值为'fail'时使用该属性返回操作失败的消息文本 |
data | 任意类型 | 返回响应数据或推送数据 |
users | 数组 | 由用户 ID 组成的数组,表示该数据包应该推送给哪些用户 |
pager | 对象 | 表示当前数据列表的分页信息 |
注意:所有由后端服务器返回给 XXD 服务器的响应数据包中都必须包含此字段,否则 XXD 服务器会将响应数据包发送系统中所有在线客户端。当 XXD 服务器转发给客户端时会从响应数据包对象中去掉users属性。在后文中并不会单独注明此属性。
四、数据包实例
下面为用户登录验证时由 XXD 服务器发送给后端服务器的请求数据包:
{ "method": "userLogin", "params": [ "", "admin", "fcea920f7412b5da7be0cf42b8c93759", "" ], "v":"2.0.0" }
当后端服务器处理完登录验证操作后会随 HTTP 请求向 XXD 服务器返回如下响应数据包:
{ "method": "userLogin", "result": "success", "users": [1], "data": { "id": 1, "account": "admin", "realname": "admin", "avatar": "http://rz.io/data/upload/201704/f_4dedbfc726a12556306452adeb6e4a24.png", "role": "dev", "dept": 52, "status": "online", "admin": "super", "gender": "m", "email": "user@example.com", "mobile": "13311303627", "phone": "7353099", "site": "", "qq": "443221877", "signed": 1538958512 }, "v":"2.0.0" }
五、数据包简写
为了简便描述指定方法的数据包对象,会在后文中简写为方法名(参数列表)形式,其中参数列表有时也会省略不写,例如登录请求数据包可以写为:
userLogin('', 'admin', 'fcea920f7412b5da7be0cf42b8c93759', '')
或者简写为:
userLogin
六、传输类型简写
为了简便描述数据包发送方和接收方会使用如下简写形式:
- xxd → xxb:由 XXD 服务器向后端服务器发送请求数据包;
- xxc → xxd → xxb:由客户端向 XXD 服务器发送请求数据包,XXD 会将请求数据包转发给后端服务器;
- xxb → xxd → xxc:由后端服务器向 XXD 服务器发送响应数据包,XXD 服务器会将响应数据包转发给客户端;
- xxd → xxc:由 XXD 服务器向客户端发送推送数据包;
- xxc → xxd:由客户端向 XXD 服务器发送请求数据包。
七、数据包定义对象格式
数据包定义对象为类 JavaScript 纯对象,在后文中会直接使用 JavaScript 对象来定义数据包。例如一个请求数据包的属性和结构可以表示为:
{ method: 'chatGetList' }
八、数据包定义对象变量
在使用数据包定义对象中会用到一些变量来代表实际使用过程中的数据。下面为一些常用变量名称对应的含义:
userData
变量userData表示一个用户数据对象,该对象包含如下属性:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
id | 数字或字符串 | 必须 | 用户数据在数据库中存档的 ID,通常为数据包主键字段 |
account | 字符串 | 必须 | 用户名 |
realname | 字符串 | 可选 | 用户真实姓名 |
dept | 数字 | 可选 | 用户部门编号 |
role | 字符串 | 可选 | 角色名称 |
admin | 字符串 | 可选 | 当前用户如果是系统管理员,则记录管理员类型,默认使用特殊值'super'表示超级管理员,其他值表示普通用户 |
avatar | 字符串 | 可选 | 用户头像图片地址 |
gender | 字符串 | 可选 | 存储用户性别信息,可选值包括'f'(女性)、'm'(男性)和'u'(未知) |
字符串 | 可选 | 存储用户电子邮件地址 | |
mobile | 字符串 | 可选 | 存储用户移动电话号码 |
phone | 字符串 | 可选 | 存储用户固定电话号码 |
status | 字符串 | 可选 | 存储用户当前状态,可选值包括'online'(在线)、'away'(离开)、'busy'(忙碌)和'offline'(离线) |
deleted | 数字 | 可选 | 当值为1或true时标记当前用户已经被从系统标记为已删除 |
下面为一个用户对象示例:
{ id: '12', account: 'admin', realname: '张三', dept: 34, role: 'manager', admin: 'no', avatar: 'http://example.com/user/avatar/admin.png', gender: 'f', email: 'admin@example.com', mobile: '+8612209098888', phone: '', status: 'online', deleted: 0 }
chatData
变量chatData表示一个系统中的会话数据对象,该对象包含如下属性:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
id | 数字或字符串 | 必须 | 作为表主键,数据库存储 ID,通常为必须为大于 0 的整数,在数据表插入字段时自动生成递增的值 |
gid | 字符串 | 必须 | 用于识别该会话全局唯一字符串,通常会在客户端创建此字段并提交到服务器保存 |
name | 字符串 | 可选 | 会话显示名称,如果是一对一会话则无需提供名称 |
type | 字符串 | 可选 | 会话类型,可选值包括:'system'(系统会话),'one2one'(一对一会话),'group'(多人讨论组),以及系统自定义的类型,例如'project'(禅道项目),'product'(禅道产品)等 |
admins | 字符串 | 可选 | 会话管理员用户名列表,使用用户名,多个管理员用户名使用英文逗号分隔 |
committers | 字符串 | 可选 | 会话允许用户发言(在会话中发布消息)的用户 ID 列表,多个用户 ID 使用英文逗号分隔,其中特殊值'$ADMINS'表示仅允许管理员发言,如果留空或者使用特殊值'$ALL'则表示允许会话中所有人发言 |
subject | 数字 | 可选 | 主题会话关联的主题 ID,仅当会话类型(type)为自定义类型时可用(例如'project'(禅道项目),'product'(禅道产品)等) |
public | 布尔值 | 可选 | 是否为公开讨论组 |
createdBy | 字符串 | 必须 | 创建此会话用户账号,存储在用户表(sys_user)中对应条目的account字段的值 |
createdDate | 时间戳 | 必须 | 创建此会话时服务器上的时间(可以精确到秒或毫秒) |
editedBy | 字符串 | 可选 | 上次编辑此会话的用户账号 |
editedDate | 时间戳 | 可选 | 上次编辑此会话时服务器的时间 |
lastActiveTime | 时间戳 | 可选 | 会话最后一次发送消息时服务器的时间(可以精确到秒或毫秒) |
dismissDate | 时间戳 | 可选 | 会话被管理员解散时服务器的时间(可以精确到秒或毫秒) |
members | 数字数组 | 必须 | 使用数组包含此会话所有成员 ID |
star | 布尔值 | 可选 | 如果为true,表示此用户已经将会话设置为已收藏 |
hide | bool | 可选 | 用户是否将该会话标记为已存档(隐藏) |
mute | bool | 可选 | 用户是否将该会话标记设置为通知免打扰 |
frozen | bool | 可选 | 用户是否将该会话暂时从最近会话列表移除 |
下面为一个会话对象数据:
{ id: 34, gid: '60&74', name: '', type: 'one2one', admins: '', committers: '', subject: 0, public: 0, createdBy: 'sunhao', createdDate: 1453689245, editedBy: '', editedDate: 0, lastActiveTime: 1516612779, dismissDate: 0, star: 0, hide: 0, mute: 0, frozen: 0, category: '', members: [60,74] }
sendMessage
变量sendMessage表示一个等待发送到服务器的会话消息对象,该对象包含如下属性:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
gid | 字符串 | 必须 | 用于识别该会话消息全局唯一字符串,通常会在客户端创建此字段并提交到服务器保存 |
cgid | 字符串 | 必须 | 此消息所属于的会话,存储在会话表(im_chat)中对应条目的gid字段的值,会话根据此值来查询会话中包含的消息 |
user | 数字 | 可选 | 此消息发送用户的 ID,广播类(type字段为'broadcast')的消息没有此值 |
type | 字符串 | 可选 | 消息的类型,可选值包括:'normal'(默认),'broadcast'(广播) |
content | 字符串 | 必须 | 消息的内容,如果消息内容类型不是纯文本,则此值通常为 JSON 对象字符串 |
contentType | 字符串 | 必须 | 消息内容的类型,可选值包括:'text'(默认,支持 Markdown 的文本内容),'plain'(纯文本),'emoticon'(表情),'image'(图片),'file'(文件),也可用为自己自定义的类型名称 |
data | 字符串 | 可选 | 消息的额外数据信息,例如点赞的用户信息,此值通常为 JSON 对象字符串 |
下面为一个纯文本消息对象示例:
{ cgid: '11&7', content: '纯文本消息内容。', contentType: 'plain', gid: 'f62b4a20-5ae2-4c42-a5ae-b4fe7959721e', type: 'normal', user: 11 }
提示:客户端在向服务器通过此数据包发送消息时,确保为新的消息对象生成了全局唯一字符串(RFC4122)作为gid属性。如果你使用 JavaScript 可以使用 uuid 模块来实现。
messageData
变量messageData表示一个会话消息对象(已确定发送成功并且经存储到服务器),该对象包含如下属性:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
id | 数字或字符串 | 必须 | 消息数据在服务器上存储的 ID,通常为数据库主键,会在数据库存储时自动创建 |
date | 时间戳 | 必须 | 消息发送的时间戳(以首次在服务器上存储的时间为准,时间戳支持精确到毫秒或秒) |
gid | 字符串 | 必须 | 用于识别该会话消息全局唯一字符串,通常会在客户端创建此字段并提交到服务器保存 |
cgid | 字符串 | 必须 | 此消息所属于的会话,存储在会话表(im_chat)中对应条目的gid字段的值,会话根据此值来查询会话中包含的消息 |
user | 数字 | 可选 | 此消息发送用户的 ID,广播类(type字段为'broadcast')的消息没有此值 |
type | 字符串 | 可选 | 消息的类型,可选值包括:'normal'(默认),'broadcast'(广播) |
content | 字符串 | 必须 | 消息的内容,如果消息内容类型不是纯文本,则此值通常为 JSON 对象字符串 |
contentType | 字符串 | 必须 | 消息内容的类型,可选值包括:'text'(默认,支持 Markdown 的文本内容),'plain'(纯文本),'emoticon'(表情),'image'(图片),'file'(文件),也可用为自己自定义的类型名称 |
data | 字符串 | 可选 | 消息的额外数据信息,例如点赞的用户信息,此值通常为 JSON 对象字符串 |
下面为一个纯文本消息对象示例:
{ id: '1121', date: 1543481423, cgid: '11&7', content: '纯文本消息内容。', contentType: 'plain', gid: 'f62b4a20-5ae2-4c42-a5ae-b4fe7959721e', type: 'normal', user: 11 }
pagerData
变量pagerData表示一个分页信息对象,该对象拥有如下属性:
属性名称 | 类型 | 说明 |
---|---|---|
recPerPage | 整数 | 表示每页最多记录数目 |
pageID | 整数 | 表示当前记录所属页码 |
recTotal | 整数 | 系统中记录总数目 |
continued | 布尔值 | 如果为true表示客户端是否是接上次请求持续获取其他页面的消息记录数目 |
notifitionData
变量notifitionData表示一个通知消息对象,该对象拥有如下属性:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
gid | 字符串 | 必须 | 用于识别该通知消息全局唯一字符串 |
title | 字符串 | 必须 | 通知消息的标题 |
subtitle | 字符串 | 可选 | 通知消息的副标题 |
content | 字符串 | 可选 | 通知消息的内容文本 |
contentType | 字符串 | 必须 | 可选值包括:'plain'表示纯文本,'text'表示 Markdown 格式的文本 |
url | 字符串 | 可选 | 该通知消息所指向的网页链接 |
actions | 对象数组 | 可选 | 使用 操作对象数组表示该通知支持的操作 |
sender | 对象 | 可选 | 通知的 发送方信息对象 |
通知的操作对象包含如下属性:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
label | 字符串 | 必须 | 操作按钮上显示的文本 |
icon | 字符串 | 可选 | 操作按钮上显示的图标 |
url | 字符串 | 必须 | 点击此操作按钮时要打开的页面链接 |
type | 字符串 | 可选 | 操作按钮类型,影响操作按钮外观,可选值包括'primary'、'success'、'danger'、'warning'、'info'、'important'、'special' |
发送方信息对象包容如下属性:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
id | 字符串或数字 | 必须 | 标识发送方唯一身份的字符串或数字 |
name | 字符串 | 可选 | 发送方在界面上显示的名称 |
avatar | 字符串 | 必须 | 发送方头像图片链接地址 |
变量数组
使用如下格式来表示一个变量数组:
[变量名称]例如[messageData]来表示会话消息对象数组。
微信公众号