Data API

数据资源 API

项	值
平台	graphql.sjtu.edu.cn
认证	OAuth 2.0 Client Credentials + exchange_data
数据方向	只读
难度	极高（部门业务 + 字段级审批）
最后验证	2026-10-25
证据等级	B（官方文档；未实测）

数据资源 API 是校级数据交换接口，覆盖账号、教职工、本科教学、论文和资产等数据。接口名包含 graphql，但最新版使用 REST。

要点

• Base：https://graphql.sjtu.edu.cn/v1
• 认证：Client Credentials，scope exchange_data。
• 权限：按字段审批；只返回申请时获批的类别和字段。
• 分页：first（起始位置，默认 1）+ offset（每次最大 200）。
• 注意：个人无法取得；数据只能用于申请时声明的用途，不能转给第三方。

---

1. 申请

1. 在数据资源 API 文档确定数据类别和字段。
2. 通过数据资源 API 申请流程填写使用部门、业务用途、数据来源、字段清单。
3. 获批后取得应用凭据。
4. 用 Client Credentials 换 exchange_data 的 Access Token。

服务对象是部门/业务系统。学生个人做自用工具通常拿不到；这是「单位级应用」的路线。

---

2. 认证

POST https://jaccount.sjtu.edu.cn/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=exchange_data
&client_id=<appId>
&client_secret=<appSecret>

拿到 access_token 后：

GET https://graphql.sjtu.edu.cn/v1/...
Authorization: Bearer <access_token>

access_token 也可以放 query，但优先放 header。

---

3. 通用响应

{
  "errno": 0,
  "error": null,
  "total": 1,
  "entities": [
    {
      "accountNo": "zhangsan",
      "guid": "...",
      "displayName": "张三",
      "accountStatus": "正常",
      "identityExpireDate": "2023-07-31",
      "userStyle": "student",
      "userId": "...",
      "topOrganizeId": "40100",
      "topOrganizeName": "网络信息中心",
      "timestamp": "2022-08-19 00:00:00",
      "relationList": []
    }
  ]
}

• errno: 0 成功；非 0 失败。
• entities 是数据数组。
• total 是本次返回的数据总数；分页时用它判断是否继续。
• 字段是按申请获批返回的；同样的接口，不同应用看到的字段可能不同。

---

4. 分页

官方规则：

• first：分页查询起始位置，默认为 1。
• offset：分页查询最大偏移量，默认每次最大 200。
• 例：每次 100 条，第一次 first=1&offset=100，第二次 first=101&offset=100。

curl 'https://graphql.sjtu.edu.cn/v1/account?first=1&offset=100' \
  -H "Authorization: Bearer $TOKEN"

注意：

• first 表示起始位置，不是每页条数；offset 才是本次数量。
• offset 最大 200；想取更多要翻页。
• 不要用 page 参数，官方没有。

---

5. 数据类别

类别	代表数据	代表端点	文档
Account	jAccount、身份、账号状态、有效期、组织、关系列表	GET /v1/account/info	graphql/account.html
Faculty	教职工基本资料、岗位、学历等	GET /v1/faculty/profile、/v1/faculty/degree、/v1/faculty/post	graphql/faculty.html
Student / 本科教学	学生基本信息、课程、排课、选课	GET /v1/stu/profile、/v1/course/info、/v1/course/plan、/v1/course/selection	graphql/student.html
Paper	论文、作者、单位、期刊、DOI 等	GET /v1/paper/info	graphql/paper.html
Asset	资产、设备、家具、房屋	GET /v1/asset/info	graphql/asset.html

字段级权限：申请时勾选哪些字段，响应里才可能出现哪些字段。不要假设「文档里有的字段你都能拿到」。查询参数（账号、学年、单位等）按各类别文档；没获批的字段/条件会失败或返回空。

---

6. 错误码

errno	含义	处理
0	成功	-
-1	API 接口异常	重试/报错
1000	请求超时	重试
1001	GraphQL 解析错误	检查查询语法
1002	权限验证失败	检查 token/scope/字段审批
1003	系统内部异常	重试/报错
1004	API 访问限制	当日次数超限；降频/次日再试

错误示例（403）：

{
  "errno": 1002,
  "error": "The interface has no access permission.",
  "total": 0
}

---

7. 旧版 GraphQL

官方还保留旧版 GraphQL 文档（account_graphql.html、faculty_graphql.html、student_graphql.html、paper_graphql.html）。这些是历史/兼容资料：

• 新项目优先用最新版 REST。
• 旧代码里如果看到 graphql.sjtu.edu.cn 的 GraphQL query，先确认它是不是旧版；不要按新文档的 REST 路径硬套。
• 旧 schema 对理解字段关系有价值，但不作为新契约。

---

8. 常见问题

1. 接口名包含 GraphQL，实际使用 REST：不要发送 { query: ... }。
2. 个人拿不到：需要部门/业务主体 + 字段审批。
3. 字段级权限：文档里的字段不等于你能拿到；响应缺字段是正常的。
4. first 表示起始位置：offset 才是本次数量，最大 200。
5. 用途限制：只能用于申请时声明的用途；不得直接或变形后提供给第三方。[官方]
6. 错误码 1004：每日访问次数限制；不要暴力重试。
7. 数据时效：timestamp 字段表示数据时间；做同步要保存它，不要假设实时。
8. 主数据不要持久化滥用：topOrganize 等计算字段可能变；官方提醒不要做持久化使用。
9. Token 放 query 会进日志：优先 header。
10. 不要跨应用共享凭据：每个应用单独申请。

---

9. 最小示例

# 1. Client Credentials 换 Token
curl -X POST 'https://jaccount.sjtu.edu.cn/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'scope=exchange_data' \
  -d "client_id=$APP_ID" \
  -d "client_secret=$APP_SECRET"

# 2. 取账号数据（字段取决于审批）
curl 'https://graphql.sjtu.edu.cn/v1/account/info?first=1&offset=100' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

---

10. 证据与来源

• Base、认证、分页、响应、错误码、数据类别、用途限制：[官方 2026-10-25，developer.sjtu.edu.cn/graphql/overview.html]
• 代表端点（account/faculty/student/paper/asset）：[官方 2026-10-25，developer.sjtu.edu.cn/graphql/*.html]
• Account/Faculty/Student/Paper/Asset 文档：[官方] 对应 graphql/*.html
• 申请流程：[官方] form.sjtu.edu.cn/infoplus/form/data_exchange_api_apply/start

变更记录

• 2026-10-25：首版。明确「REST 不是 GraphQL」、字段级权限、first/offset 语义与用途限制。