消息服务.ym 48 KB |
||
目录
私聊、群聊等 IM 服务，以及各种实时协作功能，是当今应用系统的基础需求。 易度的每个工作平台站点，自动会部署一个配套的消息中心。 1 为什么需要消息服务IM 和实时系统构建技术难度大，主要表现在：
消息服务功能：
2 API 说明与约定
3 消息接口3.1 申请建立连接 /api/v1/message/connect要建立实时连接用于接收推送消息时，需要先调用这个接口来申请实时连接所需的信息。 参数：
响应: {
"errcode": 0,
"client_id": "1243rewr32432qw2343t54r8iu",
"topics": {
"default": "account-instance-username-123123123sef"
},
"io_bridge": "http://socket.io.bridge.address.com:1234",
"broker": "http://broker.example.com:9001",
"tcp_broker": "http://broker.example.com:1883"
"use_ssl": false,
"exceeded_instances": [],
"expired_instances": []
}
响应 JSON 字段含义：
3.2 建立长连接消息客户端需要与服务器之间建立长连接，才能够收到实时消息推送。本节内容描述建立长连接的方式。 在申请成功之后，客户端应当在 60 秒内使用 MQTT 协议连接到服务器，并完成以下操作：
完成这些操作，服务器将通过客户端订阅的频道发送一条响应消息，如果消息 status 为 online ，则客户端上线成功。例如: {
"event_name": "connection",
"account": "zopen",
"client_id": "1243rewr32432qw2343t54r8iu",
"user_id": "users.admin",
"instance": "default",
"event_data": {
'status': "online",
'instances': ["default"],
'timestamp': 143244221.21,
'appname': 'Test client'
}
}
如果没有及时完成以上操作，申请的凭证（client_id 和 topic 等）将失效，客户端不能使用这些过期的信息进行连接，需要重新申请。 在实时客户端在线的过程中，服务器可能因为各种原因要求客户端断开连接（例如服务端进行了维护操作并重新启动）。 当客户端收到 event_name 为 connection 并且指定 status 为 offline 的消息时，客户端应当断开连接并重新申请凭证再行连接。 注意：当前 MQTT 服务器支持的 QoS 是 1，最大心跳间隔为 60 秒。您需要在使用 MQTT 库时，指定 keepalive 为小于 60 秒的值。 3.3 消息数据格式消息事件是JSON序列化的对象，基本格式如下: {
"from": {
"name": "admin",
"id": "users.admin"
},
"subject": "消息标题",
"body":"消息正文",
"action": "动作",
"context": {
"uid": "uid",
"title": "title",
"url": "url",
"thumbnail_url": "thumbnail_url",
"object_types": ["DataItem"]
},
"attachments": [
{
"uid": "uid",
"title": "title",
"url": "url",
"thumbnail_url": "thumbnail_url",
"object_types": ["File"]
}
]
}
各字段含义如下：
通过在消息中包含 attachments ，即可实现发送附件的功能。 3.4 触发通知频道事件 /api/v2/message/trigger_notify_event在用户的通知频道中，触发通知事件。 通知频道为系统到人的通讯频道。每个用户有 8 个通知频道分别是：
参数
其中 action 是操作名称，可选值有：
响应: {
"errcode": 0,
"timestamp": 1378234.3545,
"id": "fsdhjkYUIHBf83h_hjf"
}
响应中 timestamp 是消息的时间戳，id 是消息的 ID。如果要精准查询此条消息，请使用这个 ID。 注意：只有 persistent 类型的消息会返回 ID。 3.5 触发私有频道事件 /api/v2/message/trigger_private_event在通知频道中触发指定事件。 系统为授权的任意两个用户之间，建立了通信频道。 特殊的，自己和自己也存在通信频道，方便进行跨设备通讯。 参数
响应: {
"errcode": 0,
"timestamp": 1378234.3545,
"id": "fsdhjkYUIHBf83h_hjf"
}
响应中 timestamp 是消息的时间戳，id 是消息的 ID。如果要精准查询此条消息，请使用这个 ID。 注意：只有 persistent 类型的消息会返回 ID。 3.6 触发群组频道事件 /api/v2/message/trigger_group_event在一个群组频道中，触发指定事件。 群组频道需要预先在工作平台中创建，并将群组人员同步到消息系统。 参数
响应: {
"errcode": 0,
"timestamp": 1378234.3545,
"id": "fsdhjkYUIHBf83h_hjf"
}
响应中 timestamp 是消息的时间戳，id 是消息的 ID。如果要精准查询此条消息，请使用这个 ID。 注意：只有 persistent 类型的消息会返回 ID。 3.7 消息历史查询 /api/v1/message/query参数
响应: [
{
"body": "\u4fdd\u5b58\u65b0\u7248\u672c",
"channel_type": "notify",
"from": {
"id": "users.tester1",
"name": "\u6d4b\u8bd5\u54581"
},
"attachments": [],
"to": ["users.admin"],
"event_name": "notify",
"timestamp": 1488534767.20252,
"instance_id": "message.default.zopen",
"channel_name": "subscribe<>users.admin",
"context": {
"url": "http://192.168.1.211:80/default/desks/users.admin/files/1.xls",
"title": "1.xls",
"thumbnail_url": "",
"uid": 1019908807,
"object_types": ["File", "Item"]
},
"action": "new",
"id": "XlDMx-CISZmpOzAkZaXwMQ",
"subject": null
}
]
3.8 通过消息ID精确查询单条消息 /api/v1/message/get参数
响应: {
"errcode": 0,
"data": {
"body": "\u4fdd\u5b58\u65b0\u7248\u672c",
"channel_type": "notify",
"from": {
"id": "users.tester1",
"name": "\u6d4b\u8bd5\u54581"
},
"attachments": [],
"to": ["users.admin"],
"event_name": "notify",
"timestamp": 1488534767.20252,
"instance_id": "message.default.zopen",
"channel_name": "subscribe<>users.admin",
"context": {
"url": "http://192.168.1.211:80/default/desks/users.admin/files/1.xls",
"title": "1.xls",
"thumbnail_url": "",
"uid": 1019908807,
"object_types": ["File", "Item"]
},
"action": "new",
"id": "XlDMx-CISZmpOzAkZaXwMQ",
"subject": null
}
}
注意：如果找不到这条消息，响应中将包含错误码 30003。 3.9 消息历史数量 /api/v1/message/query_count这个用于消息历史的分页。 参数
响应: {
"errcode": 0,
"count": 200
}
3.10 频道未读消息 /api/v1/message/unread_stat查看各个频道起始未读的 persistent 类型的消息数据 参数：
响应 JSON 内容的 key 是 CHANNEL_TYPE:CHANNEL_NAME 组合的字符串。 响应: {
"errcode": 0,
"private:users.panjy<>users.zhangsan": {"count": 6, "time_start": 14354564.09},
"notify:workflow<>users.panjunyong": {"count": 1, "time_start": 12312435.12},
"group:12345": {"count": 3, "time_start": 1243543.12}
}
注意：如果您使用 edo_client 进行 API 调用，调用成功后会自动将响应中的 errcode 字段移除，避免对响应的 key 做处理时遇到意外情况，保持与旧版本兼容。 3.11 标记已读 /api/v1/message/mark_read标记某个时间之前的所有消息为已读（包括该时间点的消息） 参数：
响应: {
"errcode": 0,
"timestamp": 123
}
响应 JSON 字段含义：
4 密匙管理接口消息中心为每个实例可以设置自己的密匙，方便和第三方的用户系统集成。 4.1 /api/v1/admin/get_secret获取查看密匙。注意：这个密匙普通用户无法得到，只有账户管理员才能得到。 传入参数：
输出密匙: {
"errcode": 0,
"secret_key": "adfkdwe231jxwdw@asfas2d"
}
4.2 /api/v1/admin/refresh_secret更新查看密匙, 得到一个新密匙 传入参数：
输出新的密匙: {
"errcode": 0,
"secret": "xxx"
}
5 会话管理接口5.1 查询站点的在线用户 /api/v1/session/online_users参数：
响应: {
"errcode": 0,
"count": 2,
"users": ["users.admin", "users.zhang3"]
}
当传入 count_only 值为 true 时，响应中不会带有 users 字段。 5.2 查询连接数（在线客户端总数） /api/v1/session/connections查询站点当前的连接总数（在线客户端总数）。 参数：
响应: {
"errcode": 0,
"count": 36
}
5.3 查询用户状态 /api/v1/session/user_state查询指定一组用户的在线状态 参数：
响应: {
"errcode": 0,
"online": ["users.admin", "users.user2"],
"offline": ["users.user1", "users.user3"]
}
响应 JSON 字段含义：
5.4 过时 查询指定一个用户的详细连接信息 /api/v1/session/detail查询指定用户的详细连接情况，包含所有在线客户端的信息。 注意：此接口从 v7.2.0 版本开始不推荐使用，并可能在后续版本中移除。 如果您使用其他工具 / 库进行 API 调用，请适时调整。 如果您使用 edo_client 进行 API 调用，则无需做任何处理：新版本的 edo_client 将自动使用新接口。 参数：
响应: [
{
"ip": "120.120.2.34",
"ua": "Chrome/Gecko Like",
"app": "Web (Javascript)",
"connected": 1490870877,
"client_id": "xxxx"
}
]
响应 JSON 内容中每一项的字段含义：
5.5 查询指定一个用户的详细连接信息 /api/v2/session/detail查询指定用户的详细连接情况，包含所有在线客户端的信息。 注意：此接口从 v7.2.0 版本开始支持。与旧版接口相比，主要修改是增加了 errcode 字段。 参数：
响应: {
"errcode": 0,
"connections": [
{
"ip": "120.120.2.34",
"ua": "Chrome/Gecko Like",
"app": "Web (Javascript)",
"connected": 1490870877,
"client_id": "xxxx"
}
]
}
响应 JSON 内容中， connections 字段包含了此用户所有在线连接的详细信息，其中每一项的字段含义：
5.6 断开指定的连接 /api/v1/session/kill_connection切断指定用户特定客户端的连接，使其进入离线状态。 参数：
响应: {"errcode": 0}
5.7 断开指定用户的所有连接 /api/v1/session/kill_user切断指定用户的所有客户端连接，使这个用户进入离线状态。 参数：
响应: {"errcode": 0}
6 群组管理接口6.1 更新群组信息 / 创建群组 /api/v1/group/update如果群组不存在，将会创建这个群组；如果群组已经存在，将会更新此群组的信息。 参数：
响应: {"errcode": 0}
6.2 删除群组 /api/v1/group/remove参数：
响应: {"errcode": 0}
6.3 将用户加入群组 /api/v1/group/join如果群组不存在，将会创建这个群组，此时群组标题为空。 参数：
响应: {"errcode": 0}
6.4 将用户移出群组 /api/v1/group/leave参数：
响应: {"errcode": 0}
7 消息网关接口7.1 更新消息网关路由表 /api/v3/gateway/update_routes参数:
路由表的数据结构如下: {
"site-id": {
"endpoint": "https://easydo.cn/_message/api/v3/send?account=zopen&instance=default",
"token": "example",
},
...
}
7.2 发送一个来自外部网关的消息 /api/v3/gateway/send参数:
响应内容是这条消息的发送时间: {
"timestamp": <时间戳>,
}
8 API 错误码速查参考 《API返回码》 9 接口变更清单9.1 消息 ID在 v6.4.4 及之后版本支持使用消息ID来精确查找单条消息。
在 v7.2.5 及之后版本中，使用消息ID来精确查找单条消息的功能，分离为单独的接口 /api/v1/message/get 。原有通过 /api/v1/message/query 来查询单条消息的用法仍然兼容，但可能会在后续版本中移除。请适时更新客户端代码。 9.2 通知的公告频道在 v6.4.4 及之后版本中，通知消息增加了一个频道用于支持发送公告，此频道的 category 是 announcement。 9.3 to 和 exclude 参数在 v7.0.0 及之后版本，以下接口中原来处于 event_data 参数值内部的字段 to 和/或 exclude 被提升为整个 API 的参数。
9.4 API 返回值在 v7.2.0 及之后版本，除响应直接是列表类型的 API 外，其他所有 API 的响应都带有 errcode 字段。如果出现 errcode 不为 0 的情况，说明调用出现问题，在 errmsg 中含有错误的简略说明。 9.5 /api/v1/session/detail 接口从 v7.2.0 开始，实现并推荐使用 /api/v2/session/detail 接口。 |
||
|
|
|