高级查询——筛选、投影和分页API

三种入口一览

这三个端点都列在交互式API参考（/developers 页面）的 Search 部分， 并且都需要身份验证——参见 Omniscol API。

where 筛选（Mango / MongoDB风格）

/api/search/entity 和 /api/search/query 都接受 where 子句： 一种带有MongoDB风格运算符的结构化筛选。字段可以对应一个直接的值（隐含相等）， 也可以对应一个运算符对象；同一字段上的多个运算符以隐含的与组合。 字段名支持点号表示法，以访问上级上下文（例如 sites.name）。

几个示例：

{ "capacity": { "$gte": 20, "$lte": 50 } }
{ "level": { "$in": ["本科一年级", "本科二年级", "本科三年级"] } }
{ "name": { "$regex": "^实验" } }
{ "city": { "$like": "北京 海淀" } }
{ "$or": [ { "capacity": { "$gte": 50 } }, { "specialisation": "化学" } ] }

投影、排序和分页

在 /api/search/query 上，还有四个参数可让响应保持精简且有序—— 这对仪表盘很重要，对按令牌计费的AI智能体更是如此：

• project——要保留的字段列表（可使用点号表示法）。其余内容全部丢弃。
• sort——一个字段，asc 或 desc。伪字段 _count.<字段> 按数组字段的长度排序。
• limit 和 offset——对结果分页。

响应还会返回一个 meta 块：筛选前有多少元素、通过筛选的有多少、实际返回了多少。

完整示例

找出至少有30个座位的教室，只保留名称和容量，按容量从大到小排序，取前20间：

curl -X POST "https://your-school.omniscol.com/api/search/query" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "call": "os_dashboard_classrooms_get",
        "where": { "capacity": { "$gte": 30 } },
        "project": ["name", "capacity"],
        "sort": { "capacity": "desc" },
        "limit": 20
      }'

call 是要执行的读取端点的内部名称（与 /developers 页面上显示的一致）， params 携带该端点自己的参数，extract_path 在需要时指明结果中要筛选的数组—— 此处省略，系统会自动检测。

查找可用的教室或教师

最常见的集成场景——为内部网站、预订工具或 ETL 提供数据——就是 “谁或什么在某个时间有空？”。availability 端点可直接回答： 它们按实体仅返回所请求日期内空闲的时段，并已将课时、缺勤和必须满足的意愿考虑在内。

查询可用时间有两种方式：

• 限定范围——GET /api/schedules/availability/{datesrange}/{entity} （需要时加上 /{entityId}），针对某一类实体——teachers、 classrooms、groups、resources 等。
• 显式筛选——GET /api/schedules/availability/{datesrange} 加上 filter，用上文介绍的同一种 $where 来限定范围。

{datesrange} 的写法为 YYYYMMDD，用逗号分隔的多段表示不连续的日期—— 很适合“指定的两个星期一”：20261005,20261012。每个返回的时段都带有 day、 start、end 和 time（单位为分钟）：因此“至少3小时”就是您这一侧的 time >= 180 判断。

某个具体时段有空的教师

“10月5日星期一哪些教师有空？”——只需一次限定范围的调用：

curl -G "https://your-school.omniscol.com/api/schedules/availability/20261005/teachers" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode "with_entities=true"

空闲时段先按类别、再按教师分组返回——例如 { "availability": { "teachers": { "t.li": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } }—— 您的工具再选出覆盖所需时段的那一项。

两个星期一都有空、且达到一定规模的教室

在一次调用中同时使用实体筛选和可用时间，并采用语法中有用的子集—— 只对容量使用 $where：

curl -G "https://your-school.omniscol.com/api/schedules/availability/20261005,20261012" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode 'filter={"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}' \
  --data-urlencode "with_entities=true"

Omniscol会返回每间至少有30个座位的教室在这两个星期一的空闲时段。 然后由您的ETL筛选出在每一个日期都有3小时空档（time >= 180）的教室—— 跨多天的组合由您这一侧完成，这样规则保持明确且可验证。

对于每种实体类型，filter 接受简单的标识符列表 （{"classrooms":["A101","B204"]}）、通配符（{"teachers":"*"}）、 简单的字段匹配（{"teachers":[{"email":"…"}]}），或此处展示的结构化 $where。

选择合适的入口

• “这个词出现在哪里？” → POST /api/search。
• “这个名称对应哪个实体？” → POST /api/search/entity。
• “给我座位超过30个的教室，排好序，第一页” → POST /api/search/query。
• “谁或什么在这个时段有空？” → GET /api/schedules/availability/…。

面向AI智能体

这些入口很大程度上正是为AI智能体而设。全文搜索和实体解析会把用户的说法 （“教师李娜”、“班级6年级1班”）转换为精确的标识符； 随后查询编排器只需一次调用即可回答一个带筛选的问题，且只返回所请求的字段—— 而不是多次调用和一份过大的响应。通过 MCP——连接外部AI智能体 连接智能体时， 这些工具也在它可使用的范围之内。

接入内部网站、ETL或合作伙伴工具

第三方工具日常使用的正是这些读取入口。常见形式：

• 向内部网站或仪表盘拉取数据——您的页面使用受限的 API令牌调用读取端点 （可用时间、课时端点、 仪表盘），并显示结果。Omniscol一侧无需安装任何东西。
• 夜间ETL——计划任务获取所需内容（某个日期窗口内的课时、 某位教师的小时数、教室占用情况），并加载到您的信息系统中。 search/query 让每次拉取都经过筛选、投影和分页，响应精简。
• 从您的系统推送——反方向，让Omniscol与您的权威数据源保持一致： 夜间任务可以从您的数据库更新班级和教师 （POST /api/external/classes、POST /api/external/teachers）， 或加载自定义科目目录（POST /api/admin/subjects/custom）。
• SIS / ERP软件——对于Aurion、Auriga等系统，专用连接器才是合适的工具——参见 与外部系统同步。
• 事件驱动——如果希望在变更发生时收到通知，而不是不停轮询， 请注册一个 Webhook——参见 API自定义。

请让每个集成都保持受限：令牌仅限于确实需要的端点，定期更换， 凡是只读取的地方都使用只读权限。参见 Omniscol API。