差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录 前一修订版
前一修订版
start:100serverintegration:30chatlog [2017/09/22 07:12]
start:100serverintegration:30chatlog [2018/12/12 07:15]
jk 已恢复为旧版 (2018/11/06 11:33)
行 1: 行 1:
 +====== 聊天记录 ======
  
 +----
 +
 +环信支持 APP 把聊天记录通过 REST 接口导出。
 +
 +===== 聊天记录数据结构 =====
 +
 +<code json>
 +{
 +    "​msg_id":​ "​5I02W-16-8278a",​ //消息ID
 +    "​timestamp":​ 1403099033211,​ //​消息发送时间
 +    "​direction":"​outgoing",​
 +    "​to":​ "​1402541206787",​ //​接收人的username或者接收group的ID
 +    "​from":​ "​zw123",​ //​发送人username
 +    "​chat_type":​ "​chat",​ //​用来判断单聊还是群聊。chat:​ 单聊;groupchat:​ 群聊
 +    "​payload":​ {
 +        "​bodies":​ [ //​消息bodies
 +          {
 +           //​不同的消息类型,bodies数据格式见如下几条
 +          }
 +        ],
 +        "​ext":​ { //​自定义扩展属性
 +            "​key1":​ "​value1", ​  //​你设置的key和value的值
 +       ...
 +         },
 +         "​from":"​zw123",​
 +         "​to":"​1402541206787"​
 +    }
 +}
 +</​code>​
 +
 +==== 文本类型消息 ====
 +
 +<code json>
 +"​bodies":​ [ //​消息bodies
 +   {
 +       "​msg":"​hello from test2",//​消息内容
 +       "​type":"​txt"//​文本消息类型
 +   }
 +]
 +</​code>​
 +
 +==== 图片类型消息 ====
 +
 +<code json>
 +"​bodies":​ [ //​消息bodies
 +   {
 +       "​file_length":​128827,//​图片附件大小(单位:字节)
 +       "​filename":"​test1.jpg",​ //​图片名称
 +       "​secret":"​DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr",​ //​secret在上传图片后会返回,只有含有secret才能够下载此图片
 +       "​size":​{"​height":​1325,"​width":​746},//​图片尺寸
 +       "​type":"​img",//​图片消息类型
 +    "​url":"​https://​a1.easemob.com/​easemob-demo/​chatdemoui/​chatfiles/​65e54a4a-fd0b-11e3-b821-ebde7b50cc4b",​ //​上传图片消息地址,在上传图片成功后会返回UUID ​  
 +   }
 +]
 +</​code>​
 +
 +
 +==== 地址位置类型消息 ====
 +
 +<code json>
 +"​bodies":​ [ //​消息bodies
 +   {
 +       "​addr":"​西城区西便门桥 ",//​要发送的地址
 +       "​lat":​39.9053,//​纬度
 +       "​lng":​116.36302,//​经度 ​
 +       "​type":"​loc"//​位置消息类型 ​   ​
 +   }
 +]
 +</​code>​
 +
 +==== 语音类型消息 ====
 +
 +<code json>
 +"​bodies":​ [ //​消息bodies
 +   {
 +       "​file_length":​6630,//​语音附件大小(单位:字节)
 +       "​filename":"​test1.amr",//​语音名称
 +       "​length":​10,​ //​语音时间(单位:秒)
 +       "​secret":"​DRGM8OZrEeO1vafuJSo2IjHBeKlIhDp0GCnFu54xOF3M6KLr",//​secret在上传文件后会返回  ​
 +       "​type":"​audio",//​语音消息类型
 +    "​url":"​https://​a1.easemob.com/​easemob-demo/​chatdemoui/​chatfiles/​0637e55a-f606-11e3-ba23-51f25fd1215b"//​上传语音远程地址,在上传语音后会返回UUID
 +   }
 +]
 +</​code>​
 +
 +==== 视频类型消息 ====
 +
 +<code json>
 +"​bodies":​ [ //​消息bodies
 +   {
 +       "​file_length":​ 58103,//​视频附件大小(单位:字节)
 +       "​filename":​ "​1418105136313.mp4",//​视频文件名称
 +       "​length":​ 10,//​视频播放长度
 +       "​secret":​ "​VfEpSmSvEeS7yU8dwa9rAQc-DIL2HhmpujTNfSTsrDt6eNb_",//​secret在上传文件后会返回
 +       "​size":​{"​height":​480,"​width":​360},//​视频缩略图尺寸
 +       "​thumb":​ "​https://​a1.easemob.com/​easemob-demo/​chatdemoui/​chatfiles/​67279b20-7f69-11e4-8eee-21d3334b3a97",//​上传视频缩略图远程地址,在上传视频缩略图后会返回UUID
 +       "​thumb_secret":​ "​ZyebKn9pEeSSfY03ROk7ND24zUf74s7HpPN1oMV-1JxN2O2I",//​secret在上传缩略图后会返回
 +       "​type":​ "​video",//​视频消息类型
 +        "​url":​ "​https://​a1.easemob.com/​easemob-demo/​chatdemoui/​chatfiles/​671dfe30-7f69-11e4-ba67-8fef0d502f46"//​上传视频远程地址,在上传视频后会返回UUID ​   ​
 +   }
 +]
 +</​code>​
 +
 +==== 文件类型消息 ====
 +
 +<code json>
 +"​bodies":​ [ //​消息bodies
 +   {
 +       "​file_length":​3279,//​文件附件大小(单位:字节)
 +       "​filename":"​record.md",//​视频文件名称
 +       "​secret":"​2RNXCgeeEee2caV-fSQ1btZXJH4cgr2admVXn560He2PD3RX",//​secret在上传文件后会返回
 +       "​type":"​file",//​文件消息类型
 +       "​url":"​https://​a1.easemob.com/​sxqxwdong/​mychatdemo/​chatfiles/​d9135700-079e-11e7-b000-a7039876610f"//​上传文件远程地址,在上传文件后会返回UUID  ​
 +   }
 +]
 +</​code>​
 +
 +===== 导出聊天记录 =====
 +
 +导出聊天记录接口不是实时接口获得的时间存在一定的延时,不能够作为实时拉取消息的接口使用。
 +
 +目前提供两种方式来导出聊天记录,即下载历史消息文件和拉取历史消息两个接口,**其中拉取历史消息接口为旧有接口并于2017年3月1日起停止使用,建议使用下载历史消息文件接口**。
 +
 +以下所有 API 均需要企业管理员权限才能访问。
 +
 +==== 根据时间条件下载历史消息文件 ====
 +
 +<WRAP round tip>
 +注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见[[start:​450errorcode:​45restastrict|接口限流说明]]。
 +</​WRAP>​
 +
 +  * Path: /​{org_name}/​{app_name}/​chatmessages/​${time}
 +  * HTTP Method: GET
 +  * URL Params: 无
 +  * Request Headers: {“Content-Type”:​”application/​json”,​”Authorization”:​”Bearer ${token}”}
 +  * Response Body: 历史文件的下载地址,可以通过地址下载对应的历史记录文件。
 +  * 可能的错误码:400(要取得历史记录已过期、要取得的历史记录文件还没有生成)、401(未授权[无token、token错误、token过期]、5xx。详见:[[start:​450errorcode:​10restapierrorcode|服务器端 REST API 常见错误码]]
 +  * 查询的时间格式为10位数字形式(YYYYMMDDHH),​例如要查询2016年12月10号7点到8点的历史记录,则需要输入2016121007,​7:​00:​00的信息也会包含在这个文件里
 +  * 因为历史记录文件生成需要一定时间,建议用户在取得历史记录时要间隔一个小时,例如2016/​12/​10 09:​00之后,可以开始下载2016/​12/​10 07:00 ~ 08:​00的消息历史记录
 +  * 接口返回的下载地址30分钟内有效
 +  * 服务端默认保存3天的历史文件,​如需延长存储时间请联系商务经理。
 +
 +Response 示例:
 +<code json>
 +{
 + ....
 + "​uri"​ : "​http://​a1.easemob.com/​easemob-demo/​restapp1/​chatmessages/​2016121214",​
 + "​data"​ : [ {
 + "​url"​ : "​http://​ebs-chatmessage-a1.easemob.com/​history/​1D/​easemob-demo/​restapp1/​2016121214.gz?​Expires=1481532888&​OSSAccessKeyId=LTAIlKPZStPokdA8&​Signature=Zzt%2ByJ7tj%2Bgq3zxLVK4QrbFutto%3D" ​ //​返回的文件下载地址
 + ....
 +}
 +</​code>​
 +
 +curl 示例:
 +
 +<code php>
 +curl -H "​Authorization:​ Bearer YWMtKE9FxsAVEeaakDV5WXc9dQAAAAAAAAAAAAAAAAAAAAF8W6hAc0gR5oUiCYHCfur3AgMAAAFY8Ox2UgBPGgA6gtMo9E-nU8uaqRLXcs63EZi6Iu0QBpw6vta5E8Ix-g"​ -X GET "​http://​a1.easemob.com/​easemob-demo/​restapp1/​chatmessages/​2016121214"​
 +</​code>​
 +
 +==== 根据时间条件拉取历史消息(已停用) ====
 +
 +一次最多返回1000条。
 +
 +<WRAP round tip>
 +注意:在调用程序中,如果返回429或503错误,说明接口被限流了,请稍微暂停一下并重试。详见[[start:​450errorcode:​45restastrict|接口限流说明]]。
 +</​WRAP>​
 +
 +  * Path: /​{org_name}/​{app_name}/​chatmessages
 +  * HTTP Method: GET
 +  * URL Params: 无
 +  * Request Headers: {“Content-Type”:​”application/​json”,​”Authorization”:​”Bearer ${token}”}
 +  * Response Body: 聊天记录(JSON),默认返回10条记录
 +  * 可能的错误码:400(参数 ql 结构错误)、401(未授权[无token、token错误、token过期])、5xx。详见:[[start:​450errorcode:​10restapierrorcode|服务器端 REST API 常见错误码]]
 +  * 服务端默认保存3天的历史消息记录,​如需延长存储时间请联系商务经理。
 +
 +Response 示例:
 +
 +<code json>
 +{
 + ....
 + "​count"​ : 10, //​返回的数量
 + "​cursor"​ : "​asdsdfaee",​ //​游标,用于分页查询
 + "​entities"​ : [
 + {
 + 聊天记录entity
 + }
 + ...
 + ]
 + ....
 +}
 +</​code>​
 +
 +=== 示例1:根据 timestamp 查询聊天记录 ===
 +
 +在URL后面加上参数 ''​ql=select * where timestamp>​1403164734226''​ 或者 ''​ql=select * where timestamp<​1403164734226''​。"​="​后的参数需要转义。
 +
 +  * 如只取最近的消息可以只用 ''​timestamp>​1403166586000''​,然后记录获取到的最后一条消息的 timestamp,作为下次获取时使用的 timestamp,按此方法往下查询。
 +  * 需要导出聊天记录的,可以结合 cursor 分页来查询出所需要的聊天记录。聊天记录查询接口返回数据已经按照 timestamp 字段做了升序排序。
 +  * 不能使用 and、or 等操作符来组成这种查询 ''​ql=select * where timestamp<​1403164734226 and timestamp>​1403166586000''​。
 +
 +curl 示例:
 +
 +<code php>
 +curl -X GET -i -H "​Authorization:​ Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ"​ "​https://​a1.easemob.com/​easemob-demo/​chatdemoui/​chatmessages?​ql=select+*+where+timestamp>​1403164734226"​
 +</​code>​
 +
 +=== 示例2:分页获取数据 ===
 +
 +使用 limit 参数获取数据完毕后,如果后边还有数据,会返回一个不为空的 cursor 回来,使用这个 cursor 就能进行分页获取了。
 +
 +分页示例:根据之前获取数据返回的 cursor 继续获取后面的20条数据。在 URL 后面加上参数 cursor,ql语句保持不变。
 +
 +**(一分钟最多调用10次,每次 limit 最大值为1000。)**
 +
 +curl 示例:
 +
 +<code php>
 +curl -X GET -i -H "​Authorization:​ Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ"​ "​https://​a1.easemob.com/​easemob-demo/​chatdemoui/​chatmessages?​ql=select+*+where+timestamp>​1403164734226&​limit=20&​cursor=MTYxOTcyOTYyNDpnR2tBQVFNQWdHa0FCZ0ZHczBKN0F3Q0FkUUFRYUdpdkt2ZU1FZU9vNU4zVllyT2pqUUNBZFFBUWFHaXZJUGVNRWVPMjdMRWo5b0w4dEFB"​
 +</​code>​
 +
 +----
 +<WRAP group>
 +<WRAP half column>
 +上一页:[[start:​100serverintegration:​20users|用户体系集成]]
 +</​WRAP>​
 +
 +<WRAP half column>
 +下一页:[[start:​100serverintegration:​40fileoperation|文件上传下载]]
 +</​WRAP>​
 +</​WRAP>​