API自定义：端点覆盖与Webhook

在哪里找到

管理模块，导入/导出界面， **API自定义部分，API**按钮。

该界面仅限Premium账户使用，并受加强身份验证保护：打开窗口前， Omniscol会再次要求输入管理员的密码。由于此界面上的任何操作都会影响您集成的技术约定， 因此设置工作需要与Omniscol团队配合完成。

通用配置

您可以在此定义应用于所有Webhook的HTTP头（格式为 键1:值1;键2:值2）。 这里最适合放置发往您自己服务器的身份验证令牌（例如您的服务器要求的 Authorization: Bearer …）。对于覆盖，身份验证则放在该端点自己的HTTP头中 （见下文）。

端点覆盖

覆盖会重新定义Omniscol API的某个端点，使网页应用改为调用另一个URL。 共有三种用法，从功能最强到最简单。

从您的信息系统实时提供数据

这是功能最强的用法。您将某个读取端点重定向到一个外部URL——通常是对接学校内部信息系统的 ETL。网页应用随后会实时从该系统获取数据，而不是使用Omniscol保存的本地副本。

具体来说：当重定向URL是绝对外部地址时，网页应用会直接调用它， 不再经过Omniscol的服务器，并原样使用返回的响应——就像它来自Omniscol一样。 唯一的要求是您的系统按 Omniscol对该端点期望的格式响应（相同的JSON结构）： 中间没有任何转码。对于该端点，Omniscol的本地副本不再被查询；显示的是您系统中的实时数据。

示例：学校的科目目录从您的信息系统实时提供， 这样学校一侧的任何更新都会立即在Omniscol中可见，无需重新导入。

此处发往您系统的身份验证放在该端点自己的HTTP头中（例如 Authorization: Bearer …），在覆盖所在行中填写。HTTP 方法也可以按端点指定。

将应用自身的某个端点重新接到实时外部数据源，既功能强大，要求也高： 请与您的IT部门一起操作，并与Omniscol团队配合。

插入您自己的服务器或代理

您也可以让调用经过您自己的服务器或代理——例如为了允许跨源资源共享（CORS）， 或在网页应用与Omniscol之间加入自建逻辑。

停用端点

不给端点设置任何重定向URL（方法为 null），即可停用该端点。

请评估其对界面的影响。Omniscol是一个单页网页应用（SPA）， 界面元素由可用的端点驱动：只有当按钮、标签页和菜单所依赖的端点存在时，它们才会显示。 因此，停用端点会让依赖它的界面元素在下次显示时动态消失——如果您停用了某个模块的所有端点， 整个模块就会从导航中消失。这些元素是被移除，而不只是被隐藏， 整个过程无需对代码做任何改动：只需修改配置并重新加载应用。

表格按端点列出：其键（操作的内部代码）、原始URL、HTTP 方法、 重定向的新URL以及专用的 HTTP头。搜索框可帮助您找到要覆盖的端点。

Webhook（出站调用）

Webhook 让Omniscol在某项操作成功之后，向您的URL发送一个HTTP请求。 通过它可以让外部系统实时获知变化——信息显示屏、数字工作空间、人力资源系统、自建同步程序等。

Webhook有两种挂接方式：

• 挂接到某个具体端点（操作的键）；
• 挂接到某个分组事件，一次覆盖一类操作。共有三个分组事件：
  • 课表变更——任何影响当前生效课表的变更，包括副作用： 保存课表、创建、移动或删除课时、发布课表、 只要涉及日期的教师或班级缺勤，以及对已发布课表的结构性移除（教室、科目等）—— 移除某个科目会删除使用该科目的课时，这本身就是一次变更。 仅限于未发布草稿的编辑不会触发它；
  • 教师变更（新增、更新或删除）；
  • 科目变更（自定义科目）。

对于每个Webhook，您需要填写回调URL、HTTP 方法、 **“附带数据”**复选框（是否附上原始请求的正文？）以及专用的 HTTP头。

您的服务器会收到什么

调用以 application/json 发送，除您的HTTP头外还包含：

• 启用“附带数据”选项时，原始请求的正文；
• Omniscol的元数据块：被调用的URL、端点代码、方法、参数、 用户的身份验证令牌、学校标识以及Webhook本身的配置；
• 用于追踪的HTTP头：X-OS-original-query、X-OS-original-endpoint、 X-OS-auth 和 X-School。

对于课表变更事件，当启用“附带数据”时，调用还会包含一份课时差异 （新增、修改、删除的课时）——便于只同步发生变化的部分。

行为

Webhook在用户的操作成功之后于后台发出：它们不会拖慢界面， 即使您的服务器出现故障也不会阻塞界面。未能成功的出站调用会被记入日志， 不会中断Omniscol中的工作。每次调用的超时时间很短（几秒）： 您的服务器应当快速确认收到，其余处理在自己一侧完成。

须知

• Omniscol的API只开放了操作的一个子集；覆盖或Webhook只适用于实际开放的端点。 列表和身份验证请参见 Omniscol API。
• 对于与软件系统（ERP、人力资源系统、数字工作空间）的集成，专用的同步功能通常更合适—— 参见 与外部系统同步。其内部使用的是同一套Webhook机制。
• 如需让AI智能体无需开发即可查阅您的数据，参见 MCP——连接外部AI智能体。