正确使用API:缓存、Webhook与速率限制
Premium如果集成程序每分钟都向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)。