海康威视AccessControl API分页：序列号不连续时的增量获取方案

问题背景 #

集成海康威视门禁系统时，通过/AccessControl/AcsEvent?format=json接口的AcsEventCond参数实现事件增量获取，原采用序列号区间查询：

{
  "beginSerialNo": lastSerial,
  "endSerialNo": lastSerial + 29,
  "maxResults": 30,
  "major": 0,
  "minor": 0
}

并通过PHP代码检测序列号间隙：

$expected = range($startSerial, $maxRetrieved);
$missing = array_diff($expected, $retrieved);

但实际返回的serialNo存在不连续情况（如1001, 1002, 1004, 1005），需明确正确的分页/增量续传逻辑。

核心问题解答 #

1. 是否应从max(returned serialNo) + 1开始下一次请求？ #

不建议采用这种方式。序列号间隙的成因通常有两种：

• 间隙对应的事件确实不存在（如事件被系统清理、未生成）；
• 间隙对应的事件存在但未被当前请求返回（如分页限制、事件类型过滤规则导致）。

若直接跳到max(returned serialNo)+1，会漏掉间隙中实际存在的事件；若反复查询间隙区间，又会产生大量无效请求，无法保证增量获取的完整性和效率。

2. 是否应完全放弃基于序列号的续传，改用searchResultPosition或时间查询？ #

优先推荐使用searchResultPosition进行续传，时间查询可作为降级方案，而非直接放弃序列号：

• searchResultPosition（官方推荐）：这是海康接口设计的专用分页游标，每次响应结果中会返回该字段。下一次请求时将其传入AcsEventCond，服务端会从上次查询的结束位置继续返回后续事件，完全规避序列号不连续的问题，是最可靠的续传方式。
• 时间查询：存在精度局限性（如同一毫秒内多事件可能漏取、系统时间同步问题），仅适合作为searchResultPosition失效时的降级方案。使用时需设置合理的时间窗口，以最后一条处理事件的时间作为下一次请求的beginTime，同时用serialNo做去重标识。

正确的续传逻辑步骤 #

1. 初始请求：不传入beginSerialNo/endSerialNo，设置合理的maxResults，按需指定major/minor事件类型，请求后保存响应中的searchResultPosition。
   请求示例：

   {
     "maxResults": 30,
     "major": 0,
     "minor": 0
   }
   

2. 后续增量请求：将上一次保存的searchResultPosition传入AcsEventCond，服务端自动返回后续事件，直到返回结果为空（无更多事件）。
   请求示例：

   {
     "searchResultPosition": "上次响应的位置字符串",
     "maxResults": 30,
     "major": 0,
     "minor": 0
   }
   

3. 事件去重：始终用serialNo作为唯一标识存储事件，避免重复处理同一事件。
4. 异常降级：若searchResultPosition失效（如服务端超时清理游标），则切换为时间+序列号兜底的方式：以最后处理事件的时间为beginTime，同时设置beginSerialNo为最后处理的serialNo，确保不会漏查。

内容的提问来源于stack exchange，提问作者Mohamed Hamed