agent-foundation/docs/xuebang-query-api.md

学邦通用 GET 查询接口

agent-foundation 负责学邦鉴权、AccessToken 刷新、失败重试、分页和缓存。WorkBuddy 只调用本服务，不接触学邦密钥。

接口目录

GET /api/xuebang/catalog?query=学员

• query 可按接口说明、分类、路径、参数名或参数说明检索。
• 默认只返回 WorkBuddy 可调用的 65 个数据查询接口。
• includeBlocked=true 可查看完整 68 个 GET 接口以及禁用原因。

查询数据

POST /api/xuebang/query
Content-Type: application/json

{
  "operationId": "findListByInstitutionUsingGET_2",
  "parameters": {
    "name": "张老师"
  },
  "fetchAll": true,
  "refresh": false
}

• operationId 必须来自目录接口。
• parameters 只允许传该接口文档声明的参数。
• 可分页接口的 fetchAll 默认为 true，分页在服务端完成。
• refresh=true 会跳过缓存，适合用户明确要求实时数据时使用。
• 不传登录人、员工或校区范围时，按配置中的学邦应用管理员权限查询全部可见数据；只有用户明确指定筛选条件时才传对应参数。
• 相同接口和参数默认缓存 300 秒，可通过 foundation.xuebang.query-cache-seconds 调整。

安全边界

以下 GET 路径收录在完整目录中，但禁止通过通用查询接口调用：

• /token/{clientId}：由后端 Token 组件内部管理。
• /api/user/findUserForLogin：包含登录密码参数。
• /api/wxapp/getStudentToken：会返回学生访问凭证。

完整接口清单见 xuebang-get-api-catalog.md。