GetMyBot 知识库

分页

分批读取长列表而不漏记录:页大小、offset 偏移量和 before 游标。

本页内容

客户或消息列表可能很长,API 会按页返回。分批读取后续页面称为分页,程序无需一次下载全部历史。具体接口可用偏移量(跳过已读的条数)或游标(指向上次读到的位置);请查看接口参考。

方式一:offset 与 X-Total-Count

limit 指定最多请求多少条,offset 指定跳过多少条。例如 limit=50&offset=100 请求前 100 条之后最多 50 条:

curl -H "Authorization: Bearer <个人令牌>" \
  "https://your-domain/api/bots/BOT_ID/users?limit=50&offset=100"

响应头 X-Total-Count 给出总条数;响应体是本页数组。每次把 offset 增加实际收到的条数,直到达到 X-Total-Count。

offset 上限

任何支持偏移量的接口都会拒绝 大于 100,000 的 offset,返回 400。偏移量越大,数据库处理被跳过记录的负担也越大。若列表超过 100,000 条,请缩小筛选范围(日期、渠道、状态等),在接口支持时改用游标(例如付款和集合记录列表),或使用该模块的导出功能。

各接口的页大小上限不同

limit 没有统一上限,具体接口可能为 200、500 或 1000,见接口参考。超出上限时,有的接口返回 400,有的则静默改用默认页大小(常为 100)。

始终按实际收到的数组长度增加 offset,不要按请求中的 limit。 若请求 5,000 条却只收到 100 条,按 5,000 前进会跳过大部分记录而不报错。判断结束也应结合 X-Total-Count 和实际条数,不要只看是否遇到空页。

方式二:before 游标与 has_more

按时间排序的列表(如聊天消息)可用 limit 和可选的 before。后者是最后一条已读记录的 ID 或标记:

curl -H "Authorization: Bearer <个人令牌>" \
  "https://your-domain/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

响应包含一页记录和 has_more。为 true 时,将本页最后一条的游标作为下次的 before;变为 false 时即已读到末页。

应该使用哪种方式

由接口决定。目录式列表通常用 offset 和 X-Total-Count;按时间排列的消息流通常用 before 和 has_more。以接口参考中的说明为准。

接下来