47 lines
1.6 KiB
Markdown
47 lines
1.6 KiB
Markdown
|
# 学邦通用 GET 查询接口
|
||
|
|
|
||
|
|
`agent-foundation` 负责学邦鉴权、AccessToken 刷新、失败重试、分页和缓存。WorkBuddy 只调用本服务，不接触学邦密钥。
|
||
|
|
|
||
|
|
## 接口目录
|
||
|
|
|
||
|
|
```http
|
||
|
|
GET /api/xuebang/catalog?query=学员
|
||
|
|
```
|
||
|
|
|
||
|
|
- `query` 可按接口说明、分类、路径、参数名或参数说明检索。
|
||
|
|
- 默认只返回 WorkBuddy 可调用的 65 个数据查询接口。
|
||
|
|
- `includeBlocked=true` 可查看完整 68 个 GET 接口以及禁用原因。
|
||
|
|
|
||
|
|
## 查询数据
|
||
|
|
|
||
|
|
```http
|
||
|
|
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](xuebang-get-api-catalog.md)。
|