先确认一件事:你要拉取的历史记录,到底存在于哪个系统里。很多团队在开始写分页代码前,根本没确认过机器人类型,结果写了半天发现接口权限不对。下面这段判断逻辑建议先看清楚。
在动手实现分页拉取前,需要先确认钉钉机器人消息的历史记录究竟从哪里拿。如果机器人只是通过群聊自定义机器人推送通知,它本身没有读取群聊历史的能力,webhook 地址仅支持告警式的发送请求,无法查询任何历史数据。这时所谓的历史记录只能依赖业务侧自己落库。反之,如果使用的是企业内部应用里的机器人,并开通了消息发送接口和会话存档权限,那么可以通过与钉钉服务端交互的消息查询接口来分页获取历史消息。因此,先判断机器人类型和权限范围,再设计分页方案,否则后期很可能把不该实现的方案反复返工。
判断方法很简单。群聊自定义机器人是在群设置中添加的,只拿到一个 webhook 地址,没有 appKey 和 appSecret,也没有任何消息查询权限。企业内部应用机器人则是在开发者后台创建的,对应一个应用凭证,可以继续申请消息发送和会话存档权限。如果公司内部有专人管理钉钉应用,可以在开发者后台查看当前应用开通了哪些接口权限,确认是否存在查询历史消息相关的权限点。这一步不确定,就不要急着设计接口。
本地落库比依赖远端接口更稳
分页拉取历史消息的可靠做法,是发送消息时把消息 ID、会话 ID、发送时间戳和消息体完整记录到自己的存储系统中。每次用户或业务系统请求历史记录时,直接基于本地数据库分页即可。这样有两个好处,一是完全不受钉钉接口查询范围和频率限制,二是可以对消息做二次加工和聚合展示。如果非要从钉钉远程拉取,则应当在调用前明确知道该接口是否支持按时间倒序、是否返回 hasMore 游标,并且把游标存到下一次请求的参数中。双方方案对比下来,本地落库的复杂度通常远低于依赖外部 API 的分页逻辑。
这里的“本地存储系统”可以是业务数据库、日志表或独立的归档服务。关键点是发送消息成功后,立刻把与发送有关的字段写入一张设计好的表,至少包含:消息 ID、会话 ID、发送时间戳、消息体、消息类型。用户端每次翻页时,直接基于这张表做 LIMIT 分页或游标分页,响应速度比远端查询快,也不会因为钉钉接口频率限制而中断。适合的场景包括:自定义机器人推送后需要在 H5 页面展示通知记录、业务系统需要按某个维度汇总消息、或者需要长期保留消息作为审计数据。
如果确实需要从钉钉远端拉取消息,那就要进入下面这个条件:接口必须支持按时间倒序返回,并且能返回游标。否则你得先把整段数据一次性取回来自己排序,这在消息量大的时候不现实。
必须远程拉取时,用游标和时间窗口
当确实需要调用钉钉服务端接口分页时,建议采用基于游标加时间窗口的方式。即第一次请求传入起始时间戳和空游标,服务端会返回一批消息与下一次游标。此后每次请求都携带同一时间窗口和上次返回的游标,直到游标为空或返回条数小于每页数量。注意游标并非页号,不能通过简单地自增页码来获取后续数据,必须使用上一次返回值。同时,建议将每批拉取数量控制在一个可控的数值内,比如每页 20 到 50 条,避免单次响应过大。拉取完成后,用消息 ID 去重,防止同一消息在边界处被重复拉取。
用请求参数来说明这个过程,大致是这样:第一次请求时,调用方传入 start_time(毫秒级时间戳)、end_time 或相对时间窗口,以及一个空的 next_cursor。服务端返回结果里除了消息列表,还会带一个字符串类型的游标。第二次请求把上次的 next_cursor 原样带上,同时保持同一个时间窗口不变。直到返回的 next_cursor 为空,或者本次返回条数小于每页数量,拉取就算结束。这里需要特别留意:游标是服务端生成的,不是页码,不能自己加一加就完事。如果本地没有保存上一次游标,只能从头开始拉,那样会造成大量重复请求。
// 伪代码示意:游标分页
let cursor = "";
while (true) {
let result = callHistoryApi({
start_time: startTs,
end_time: endTs,
page_size: 50,
next_cursor: cursor
});
saveMessages(result.messages);
if (result.next_cursor === "" || result.messages.length < 50) {
break;
}
cursor = result.next_cursor;
}
拉回来的消息列表先不要直接入库,先按消息 ID 做一次去重。因为边界处消息可能被重复返回,或者在两次请求之间新消息插入导致偏移。去重时保留首次出现的记录即可。
两个边界:权限保留期和时间保留期
即便接口权限和游标逻辑都正确,也还要面对钉钉服务端的保留期限制。这个保留期不是固定的,需要结合当前组织的配置和开通的服务确认。通常来说,历史消息查询只覆盖最近一段时间内的记录,超过保留期的消息即使参数正确也拉不回来。所以设计任务前,需要先确认保留期有多长,最好用一个小时间窗口测试一下最早能拉到的消息时间。比如先查一周前、一个月前的消息,看是否有成功的返回。
另一个边界是权限。普通自定义机器人完全没有读取入口,这个之前已经说清楚了。企业内部应用也未必默认开通会话存档,需要在开发者后台申请并审核。权限点缺失时,接口会返回类似“无权限”的错误码,但不同环境下的错误码可能不同,建议先在钉钉开放平台的错误码表中找到对应解释。
分页拉取时容易踩的坑,以及怎么提前设计
常见的坑主要集中在时区、游标生命周期和消息删除策略上。第一,钉钉服务端返回的时间戳通常是毫秒级 Unix 时间戳,但如果你在本地用北京时间与钉钉的服务器时间做比较,可能因为时区偏移导致起始时间差几个小时,漏掉某天的消息。统一使用毫秒级时间戳,并且在存储时也保持同一个时区基准。第二,游标不能永不过期。如果把游标放在缓存里然后忘记设置失效时间,长时间不拉取后游标可能失效,需要额外设计一个重置逻辑,例如每次成功拉取后更新游标时间,或者定期重新置空。
第三,历史消息的物理删除会造成映射错乱。假设你已经按消息 ID 存储了本地引用,但钉钉端删除了某条消息,下一次游标可能跳过或改变位置。更稳妥的做法是只在本地表中做软删除,保留原始 ID 和状态位,这样即使远端消息消失,本地历史记录依然可以按需展示。
改完后看这几个信号
做完分页逻辑后,不是没有报错就代表成功。建议先观察几个信号:第一,用一段已知的时间范围做对比拉取,确认本地总条数与钉钉端可查询到的消息数一致。第二,检查游标是否一直不为空且最终能结束,如果循环次数超过预期,说明游标可能没有更新,或者请求参数里传错位置。第三,统计去重后的消息 ID 是否有重复,重复率高说明你游标处理有问题。第四,在消息发送间隔内测试边界时间点,比如整点半点,确认首尾消息没有遗漏。
如果这些信号都正常,再考虑把定时同步任务挂上去。同步周期需要比服务端保留期短,否则历史缺口无法弥补。一旦发现拉取有断档,先回退修改游标保存逻辑,其次检查时间窗口是否被扩大或缩小。