正确使用API:缓存、Webhook与速率限制

Premium

优化对Omniscol API的调用:使用ETag避免重复获取未变化的数据,缓存响应,通过Webhook接收变更通知,并遵守按IP地址和按API密钥计算的速率限制。

如果集成程序每分钟都向Omniscol查询数据是否有变化,那么大多数情况下得到的响应与上一次调用完全相同。这样既白白消耗了配额,也给服务器增加了负担,却没有获得任何新信息。

本页介绍避免这些多余调用的方法,以及API适用的速率限制。

避免重复获取未变化的数据

API的大多数读取响应都带有ETag头,用于标识响应的某个版本。请将该标识与收到的数据一并保存,并在下次调用时通过If-None-Match头发送:

curl -i -G "https://your-school.omniscol.com/api/schedules/lessons/20261102-20261108" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'If-None-Match: W/"os1.…"'

如果数据没有变化,Omniscol会返回304 Not Modified,且没有响应体,您可以继续使用缓存中保存的数据。否则,您会收到完整的200 OK响应,并附带新的ETag。

ETag是不透明的值:请原样保存并原样回传,包括引号和W/前缀,不要尝试自行构造或解码。它只对应产生它的请求和所用的访问凭据:请勿用于其他URL,也不要配合其他令牌使用。

Cache-Control: private, no-cache头表示该响应可以保存在私有缓存中,但再次使用之前必须向Omniscol重新验证。这正是If-None-Match的作用。

有些响应不带ETag,尤其是依赖当天日期、即使账户数据未修改也可能变化的响应。这类响应每次调用都必须重新获取。

Omniscol发布新版本后,ETag会全部更新,即使数据没有变化。此时第一次调用会收到200响应,之后的调用即可再次获得304响应。

304还能减少服务器端的处理。在大多数情况下,若自上次调用以来账户没有任何数据变化,Omniscol无需重新读取相关数据即可响应,这样的304不会计入您的API密钥配额。而重新读取数据后才得到的304,则与普通响应一样计入配额。

因此,数据未变化时,定期重新验证的成本依然很低。不过它仍受按IP地址计算的总体限制约束。

缓存响应

如果您的应用程序有多个用户或多个界面查看相同的数据,就没有必要为每个用户或界面都向Omniscol发起查询。

请将响应及其ETag保存在您自己掌控的应用缓存中,例如Redis、Memcached或数据库表。这样,您的应用程序就可以从该缓存提供数据,并由缓存通过If-None-Match定期向Omniscol重新验证,或在Webhook通知有变更时重新验证。

缓存键必须包含完整URL、所用的身份验证令牌,以及(如果您使用)GET请求的正文和会改变响应的HTTP头,例如Accept-Language。权限不同的两个令牌可能访问到不同的数据:用一个令牌获得的响应,绝不能提供给无权访问这些数据的用户。

此外,请将每个响应的正文与其ETag一并保存。没有对应的数据,仅凭304响应无法还原出所需的结果。

该应用缓存不同于共享的HTTP缓存:Cache-Control: private指令禁止后者保存这些响应。

用通知代替定期查询

与其定期检查数据是否有变化,不如让Omniscol在发生修改时通知您的应用程序。

该机制基于Webhook,可在API自定义界面中配置(参见API自定义)。Webhook既可以监视某个具体端点,也可以监视涵盖多项修改的事件,例如课表修改。

收到Webhook时使缓存失效

最简单的用法是把Webhook当作失效信号。

收到通知后,您的应用程序将相关数据标记为过期,并向Omniscol重新验证。无需解析修改的具体内容:Webhook只是告知需要重新检查一次。

这种做法可以与前文所述的缓存自然结合。

按差异同步课时

如果您维护着一份同步的课时副本,课表修改事件的附带数据选项可以让您收到差异数据,其中包含新增、修改和删除的课时。

这样,您的应用程序只需应用这些变更,而不必重新获取整份课表。

确保收到通知

Omniscol对每个Webhook只尝试发送一次。最多等待四秒,失败后不会重试,并在日志中记录失败。

因此,您的服务器应尽快返回200 OK或202 Accepted确认收到,再以异步方式完成所需的处理。

同时请保留定期重新验证,作为补漏机制。如果发送Webhook时您的服务器不可用,这种检查可以发现遗漏的修改。得益于304响应,数据为最新时它的成本依然很低。

保护Webhook安全

为确认通知确实来自Omniscol,请配置自定义HTTP头,其值为仅您的应用程序和Omniscol知道的密钥。您的服务器应拒绝未携带预期值的调用。

另有两个HTTP头提供通知的上下文信息:

  • X-School标识相关的Omniscol账户;
  • X-OS-auth包含触发该修改的用户的身份验证令牌。

X-OS-auth中传递的令牌是保密信息。请勿将其记录到日志中,不要转交给其他服务,并严格限制对它的访问。

只请求所需的数据

返回数据较少的响应,通常生成、传输和缓存都更快。

对于课时,请限定请求的时间范围,并按您关心的实体筛选结果(参见课时API)。

对于搜索,search/query端点提供筛选、字段投影和分页(参见高级查询)。

如需更新大量同类元素(班级、教室、科目等),若OpenAPI文档中提供了可以一次请求提交整个集合的端点,请优先使用,而不要发起大量单项调用。

遵守速率限制

API调用适用两项速率限制。达到限制时,Omniscol会返回429 Too Many Requests,并附带Retry-After头,指明重新发起请求前需要等待的秒数。

按IP地址限制

总体限制为每10秒的时间窗口内300个请求,涵盖API的所有端点,包括MCP和信息显示屏。

对于设计合理的集成,这一阈值通常足够。但没有间隔的循环调用,或过多的并行请求,仍可能触及该限制。

按API密钥限制

来自同一API密钥的令牌共享两项配额:

  • 每分钟60个请求;
  • 每天5000个请求。

响应可能带有以下HTTP头,可用于跟踪用量:

  • RateLimit-Policy给出适用的配额,例如60;w=60, 5000;w=86400;
  • RateLimit-Limit给出最接近用尽的那一项限制所对应的配额;
  • RateLimit-Remaining给出该配额下仍可使用的请求数;
  • RateLimit-Reset给出距离该配额重置的秒数。

这些HTTP头可能缺失,特别是在未重新读取数据而得到的304响应中:没有这些头,并不表示配额已用尽。

配额用尽时,429响应的正文中也会通过retry_after字段给出等待时间。

未重新读取数据而得到的304响应不计入这些配额,但仍受按IP地址计算的总体限制约束。

如果这些限制妨碍了对API的正常使用,请联系我们,而不要通过增加密钥数量来绕过。

处理错误与重试

收到429响应后

请先等待Retry-After指明的时间,再重新发起请求。立即重试没有意义,还可能延长受限状态,尤其是在您的应用程序有多个进程同时重试时。

出现服务器错误或超时后

出现5xx错误或超时后,读取请求可以重试,并逐次延长重试间隔:例如依次间隔一秒、两秒、四秒,直到达到最大重试次数。

写入请求的情况不同:即使您始终没有收到响应,修改也可能已经保存。重新执行操作之前,请先核实数据的实际状态,以免重复修改。

收到401响应后

对于401 Unauthorized响应,用同一个令牌重试通常无法解决问题。可能的原因包括:令牌已过期,其所属的API密钥已被删除或已过期,或所请求的端点不在该密钥授权的范围内。

重新发起调用之前,请检查令牌及其关联的授权(参见Omniscol API)。

另请参阅