配置追踪更新频率的 7 种方式:数据更新更及时,API 请求更少
通过设置新鲜度目标、根据货件状态调整轮询频率、在支持的情况下使用 Webhook、协调遗漏的更新、缓存共享结果、批量处理计划任务,并在发生错误或触及速率限制时退避,来配置跟踪更新频率。对于开发人员和运营团队而言,目标并不是尽可能缩短间隔,而是在不重复请求未发生变化的数据的前提下,将有用的货件变化传入系统。

这些控制通常属于将跟踪服务商连接到订单管理系统、支持平台或面向客户的跟踪页面的应用程序。一些服务商也提供自己的刷新控制。请将这两个层级分开:更改应用程序的请求计划,并不一定会改变服务商检查承运商的频率。
首先,确定你可以控制哪一种更新频率
货件更新在客户看到之前要经过多个阶段。承运商记录事件,跟踪服务获取事件,应用程序接收或检索事件,界面显示事件。任何阶段出现延迟,都可能使跟踪信息看起来过时。
- 承运商事件可用性:承运商记录并发布扫描记录或状态变化的时间。
- 服务商刷新频率:跟踪服务检查或接收承运商信息的频率。
- 应用程序检索频率:系统请求信息或处理传入通知的频率。
- 显示刷新频率:网站、应用程序或支持工具刷新本地视图的频率。
更频繁地轮询服务商可以缩短第三个延迟,但无法保证承运商会产生更新的扫描记录,也无法强制上游刷新,除非有文档明确说明某个接口会执行该操作。在更改计划之前,请确认 API 请求读取的是已存储的跟踪数据、发起刷新,还是执行其他操作。
对于 17TRACK 集成,请从 Tracking API 概览和官方 API 文档开始。确认计划使用的操作的行为,包括更新交付、请求限制和任何刷新控制。下面的调度模式是应用程序端的建议,并不表示每个间隔都是可配置的 17TRACK 设置。
1. 在选择间隔之前设定新鲜度目标
定义每个业务流程需要多快获知新可用事件。配送异常队列可能需要比历史货件仪表板更严格的目标。让两者使用相同的轮询间隔会浪费请求,或使更紧急的流程得不到充分服务。
区分两项测量:距上次成功检索的时间,以及最新货件事件的时间。一次成功的请求可能返回旧事件,因为没有任何变化。这与集成失败、近期未检索到数据是不同的情况。
使用小型配置策略,而不是将间隔分散写入代码中:
- 新鲜度目标:服务商数据可用与应用程序接收数据之间可接受的延迟。
- 正常轮询间隔:适用于符合条件货件的默认间隔。
- 最大协调间隔:货件在没有成功验证的情况下可以持续的最长时间。
- 请求预算:扣除重试、协调和其他 API 操作后可用的容量。
例如,逐个检查 12,000 个货件,每小时一次,在不计重试的情况下每天会产生 288,000 个计划查找请求。每四小时检查一次则会产生 72,000 个。这些只是示例计算,不是服务商限制或推荐间隔;批处理和推送交付会改变计算结果。
选择满足流程新鲜度目标的最长间隔,然后测试上游数据是否足够新鲜,能够使该间隔发挥作用。
2. 随货件状态变化调整间隔
单一计划忽略了货件的实际行为。等待首次扫描的包裹、正在经历长途运输的包裹,以及即将配送的包裹,不一定需要同等程度的关注。
| 货件状况 | 建议的调度方式 | 防护措施 |
|---|---|---|
| 等待初始承运商信息 | 使用有上限的检查;如果没有变化,则延长间隔。 | 不要仅凭缺少扫描记录就认定货件失败。 |
| 正常运输中 | 针对相关服务或路线使用基准间隔。 | 保持最大的协调间隔。 |
| 即将配送 | 当及时更新能够支持实际操作时,考虑缩短间隔。 | 衡量额外请求是否返回新信息。 |
| 异常或长时间无活动 | 优先调查,并使用有上限的监控计划。 | 更快的轮询不会解决根本异常。 |
| 已送达或已完成 | 完成关闭检查后,从例行轮询中移除。 | 为更正和合理的重新开放留出空间。 |
明确将服务商状态映射到内部生命周期。不要假设退回货件、配送尝试失败和配送完成都应停止监控。它们可能需要不同的运营决策。
为每个货件存储下一次可检查时间戳,并在有意义的事件到达时重新计算。这样可以使调度过程可审计,并避免依赖将每条记录一视同仁的计时器。
3. 在服务商支持时使用 Webhook 获取变化
轮询是在询问是否发生了变化。Webhook 允许服务商在更新可用时通知应用程序。在支持所需事件和交付行为的情况下,应将推送交付作为主要接收路径,而不是反复查询每个活跃货件。
Webhook 不会消除上游延迟,也会带来交付处理要求。在实施之前,请确认服务商文档中规定的身份验证机制、确认规则、重试行为和事件标识符。
- 使用文档规定的机制验证传入请求。
- 在确认成功接收之前,持久化存储或入队有效通知。
- 以幂等方式处理通知,避免重复交付触发重复的客户消息。
- 处理延迟和乱序事件,避免使用较旧信息覆盖较新状态。
- 监控处理失败情况以及队列通知的时间。
除非服务商明确保证,否则不要假设 Webhook 一定只交付一次或始终按时间顺序交付。将货件的事件历史与当前规范化状态分开保存,以便评估延迟信息,而不是盲目应用。
4. 添加定向协调,而不是再运行一轮完整轮询
基于 Webhook 的集成仍然需要恢复路径。你的端点可能不可用,工作程序可能在接收后失败,或者内部映射错误可能阻止更新到达订单记录。
协调用于检查你存储的状态是否与服务商状态一致。它应关注需要验证的记录,而不是在整个货件群体上重新创建高频轮询。
有用的协调对象包括通知处理失败的货件、超过最大验证间隔的记录,以及受已知故障影响的货件。单独存在的旧承运商事件并不一定说明遗漏了更新。
发生故障后,将受影响的记录加入队列,并在受控的请求预算内处理完毕。对重叠的恢复任务去重;当成功更新已经解决差异时,取消冗余工作。避免为每个活跃货件同时发起请求。
将上次成功验证的时间戳与最新事件时间戳分开跟踪。否则,一个近期没有扫描记录的包裹可能会反复符合协调条件,即使系统刚刚确认服务商没有新信息。
5. 缓存跟踪数据,并在使用者之间共享请求
跟踪页面、支持仪表板、通知工作程序和订单系统可能都会请求同一个货件。应提供共享的应用程序记录,而不是让每个使用者独立查询跟踪服务商。
在本地存储最新的已知货件状态,以及检索时间和相关事件时间戳。让调度器或 Webhook 处理程序更新该记录。客户刷新页面不应自动强制发起另一个上游请求。
除了缓存外,还要使用请求合并:如果多个使用者同时请求同一个过期记录,只允许一个刷新操作,让其他使用者使用或等待其结果。正确限定缓存键和访问检查,确保数据不会跨越账户边界。
如果端点支持 ETag 或 Last-Modified 等 HTTP 验证器,条件请求可能会减少响应正文传输。不过,条件请求仍然是请求,并且仍可能计入服务商配额。HTTP 缓存语义定义于 RFC 9111;具体跟踪端点是否支持必须单独确认。
让界面中的新鲜度易于理解。“上次检查”应描述检索时间,而“最新货件事件”应描述承运商事件。将一个时间戳显示得仿佛同时代表两者,可能会误导客户。
6. 批量处理符合条件的查找,并随时间分散请求
当相关查找端点支持在一次请求中处理多个跟踪记录时,批处理可以减少 HTTP 请求数量。请确认所需操作支持批处理:批量注册并不自动意味着支持批量检索。
还要区分传输效率和计费方式。一个包含多个记录的 HTTP 请求,仍可能根据服务商规则消耗多个配额单位或产生多次计费查找。
实用的调度器应当:
- 选择下一次可检查时间已到的记录。
- 排除已完成、已暂停或已经入队的记录。
- 在文档规定的端点和负载限制内分组符合条件的记录。
- 通过共享速率限制器分发工作。
- 记录每个项目的结果,并在适当时仅重试失败或未解决的项目。
将工作分散在调度窗口内,而不是每小时整点运行所有任务。添加有上限的随机偏移量,通常称为抖动,以减少同步突发流量。偏移量应足够小,以满足每个流程的新鲜度目标。
当等待填满批次会延迟紧急更新时,批处理的作用会降低。允许时间敏感的工作在未组成完整批次时继续执行,同时将其控制在同一总体速率预算内。
7. 适应速率限制、失败和低价值检查
正常更新间隔不应同时作为错误重试间隔。不可用的端点需要受控重试,而不是在失败之上再叠加一整轮计划请求。
HTTP 429 表示“请求过多”,其响应可能包含 Retry-After 字段,如 RFC 6585 所述。该字段的 HTTP 语义定义于 RFC 9110。在服务商提供有效 Retry-After 值时,应遵循适用的服务商指示和该值。否则,对可重试失败使用带抖动的有界指数退避。
不要无限重试身份验证失败或无效的跟踪输入。应将其转交修正。对于会改变服务器端状态的操作,在因超时情况不明确而自动重复请求之前,先确认重试安全性。
单独调整正常轮询。如果连续成功检查都没有返回新信息,可以在货件新鲜度范围内考虑延长间隔。当有意义的事件将包裹推进到更具时效性的阶段时,再次缩短间隔。
在所有共享相关配额的工作程序之间应用速率限制。独立的工作程序限制可能分别看似合规,但合并流量却超过账户级别的限额。
同时验证新鲜度和效率
在广泛应用之前,先在受控的货件组上测试策略。比较具有相似承运商、路线和生命周期特征的流程,避免货件构成变化被误认为调度改进。
- 有效更新产出:成功检查中增加有意义信息的比例。
- 验证时长:距上次成功检查服务商状态的时间。
- 接收延迟:从服务商数据可用到应用程序接收的时间(如果该可用时间可观测)。
- 请求压力:请求量、速率限制响应、重试次数和队列深度。
- 恢复质量:通过协调恢复的遗漏变化,以及清除失败所需的时间。
不要将承运商事件到应用程序接收的时间标记为纯粹的集成延迟。它可能包含应用程序无法直接控制的上游发布和收集延迟。有效的策略应在保持重要运营变化处于既定新鲜度目标内的同时,减少不必要的检索。
常见问题
货件跟踪的最佳轮询间隔是多少?
不存在通用间隔。应根据流程的新鲜度目标、上游更新行为、API 限制和请求预算来选择。先设定有文档记录的基准,衡量成功检查的价值,再根据生命周期状态进行调整,而不是让所有货件都更快轮询。
刷新跟踪页面会强制进行新的承运商检查吗?
不一定。页面可能读取应用程序缓存或服务商存储的跟踪数据。浏览器刷新、API 查找和上游承运商刷新是不同的操作。只有在文档规定的行为支持该说法时,才能将刷新描述为实时刷新。
Webhook 可以完全取代轮询吗?
当服务商支持必要的更新时,Webhook 可以取代大量例行轮询。但仍应保留有上限的协调流程,用于处理失败和不确定状态。还需要进行多少检查,取决于交付保证、恢复选项以及遗漏更新的后果。
配送完成后什么时候应停止跟踪请求?
完成关闭检查后,将已送达货件从例行主动轮询中移除。根据业务流程和服务商行为,决定是否需要有限的验证期。同时保留处理更正的能力,不要让每个已完成货件都无限期地留在计划中。
减少 HTTP 请求一定会降低 API 费用吗?
不会。计费可能取决于货件、跟踪记录、操作或其他合同计费单位,而不是 HTTP 请求数量。在将财务节省归因于批处理、缓存或采用 Webhook 之前,请确认适用的计量规则。
来源
- 17TRACK Tracking API 概览 — 用于评估跟踪集成的官方入口。
- 17TRACK API 文档 — 用于在配置应用程序端调度之前验证支持的操作和集成要求。
- RFC 9110:HTTP 语义 — HTTP 方法语义、条件请求和 Retry-After。
- RFC 9111:HTTP 缓存 — 缓存行为和响应验证。
- RFC 6585:其他 HTTP 状态代码 — 429 请求过多响应的定义。


