数据集数据获取指南

本文说明希悦 OpenAPI 中数据平台数据集相关接口的用途、字段结构及调用顺序。

本手册覆盖以下 2 类接口能力：

• Dataset Metadata：查询数据集元信息，包括字段定义和关联关系
• Dataset Records：查询数据集记录，支持筛选、排序、字段裁剪、关联展开和分页

本文仅覆盖数据读取场景，不包含数据集建模、数据写入及报表查询接口。

1. 接口范围

数据集数据读取相关接口能力如下：

2. 对接前准备

2.1 鉴权

平台使用 OAuth 2.0 获取 access_token。详见 docs/oauth.md。

Token 接口：

POST /api/v3/oauth/tokens
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "scope": "school.{school_id} dataset.read_all"
}

业务接口请求头：

Authorization: Bearer {access_token}
X-School-Id: {school_id}

要求：

• Authorization 用于传递访问令牌。
• X-School-Id 按平台通用约定传递学校上下文。

2.2 权限范围

读取数据集元信息和数据集记录时，需要以下 Scope：

• dataset.read_all：读取所有数据集数据

注意：

• queryDatasets、queryDataset 和 queryDatasetRecords 都要求 dataset.read_all。
• 如果应用同时读取报表查询结果，还需要按报表接口要求开通 reporting.read_all。

2.3 分页与查询参数约定

分页

数据集记录接口支持以下分页参数：

分页响应头约定详见 docs/conventions.md。

动态筛选

查询数据集记录时，动态筛选参数遵循 {field}_{operator} 语法。其中 field 为数据集字段名，operator 为筛选操作符。例如：

• id_in=1,2
• id_egt=1000
• id_elt=2000
• name_like=张三
• status_in=enabled,disabled
• created_at_egt=2026-03-01 00:00:00
• updated_at_elt=2026-03-31 23:59:59

请求时应对中文、空格、冒号等特殊字符进行 URL Encode。

3. 数据关系图

dataset
  ├── fields
  │     ├── field.name
  │     ├── field.type
  │     └── field.primary
  ├── relations
  │     ├── relation.name
  │     ├── relation.ref_name
  │     └── relation.related_by
  └── records
        └── record[field.name]

关键关系：

• 一个 dataset 表示一个可查询的数据集。
• fields 描述数据集字段，记录中的键与 fields.name 对应。
• relations 描述当前数据集可展开的关联字段。
• queryDatasetRecords 返回的是记录数组，每个元素是一行表数据。
• fields 参数用于控制返回字段集合。
• expand 参数用于展开关联数据，取值应来自元信息中的 relations.name。

4. 总体调用顺序

推荐调用顺序如下：

1. 通过 OAuth 获取 Token
2. 确认应用已开通 dataset.read_all
3. 调用 queryDatasets 或 queryDataset 获取数据集元信息
4. 根据 fields 确认可查询字段、字段类型、主键字段和枚举值
5. 根据 relations 确认可展开的关联字段
6. 组装 queryDatasetRecords 请求参数，包括筛选条件、排序、返回字段、关联展开和分页参数
7. 读取记录数组，并按元信息中的字段定义转换为下游所需结构
8. 如需全量同步，关闭分页，按主键 ID 逐段读取，取每段最后一条记录的 ID + 1 作为下一段的起始值，直到返回记录数为 0

5. 第一步：查询数据集元信息列表

接口：

GET /v3/uds/datasets

OpenAPI： 查询数据集元信息列表

说明：

• 该接口用于查询一个或多个数据集的元信息。
• 当开发人员只知道部分数据集名称，或需要一次确认多个数据集结构时，使用该接口。
• 如已明确目标数据集名称，也可以直接调用 GET /v3/uds/datasets/{name}。

请求参数：

返回结构：

请求示例：

GET /v3/uds/datasets?name_in=v3_students,v3_classes
Authorization: Bearer {access_token}
X-School-Id: {school_id}

6. 第二步：查询单个数据集元信息

接口：

GET /v3/uds/datasets/{name}

OpenAPI： 查询单个数据集元信息

说明：

• 该接口用于获取单个数据集的完整表结构。
• 读取记录前，应先通过该接口确认字段名、字段类型和可展开关联。
• 下游系统不应仅依赖字段显示名称 label 解析数据，应使用稳定的字段名称 name。

请求参数：

fields 中常用字段：

relations 中常用字段：

7. 第三步：查询数据集记录

接口：

GET /v3/uds/datasets/{name}/records

OpenAPI： 查询数据集记录

说明：

• 该接口直接读取数据集记录。
• 返回结果中的每一项都是一行表数据。
• 字段集合由数据集定义和 fields 参数共同决定。
• 支持分页、排序、字段裁剪与关联展开。
• 支持任意 {field}_{operator} 形式的动态筛选参数，具体可用字段参考数据集元信息。

请求参数：

请求示例：

GET /v3/uds/datasets/v3_students/records?fields=id,name&expand=class&id_egt=1&id_elt=10000&sort=id&page=1&per_page=20
Authorization: Bearer {access_token}
X-School-Id: {school_id}

8. 常用查询方式

8.1 按 ID 批量查询

适用于已知数据主键，需要补充明细字段的场景。

GET /v3/uds/datasets/v3_students/records?id_in=1,2,3&fields=id,name

要求：

• id_in 使用逗号分隔。
• 如只需要少量字段，应使用 fields 限制返回字段。

8.2 按 ID 段全量同步

适用于需要拉取完整数据集，并控制单次请求范围的数据同步任务。

GET /v3/uds/datasets/v3_students/records?id_egt=1&sort=id&paginated=0&limit=10000

要求：

• id_egt 表示当前 ID 段起始值，首次同步时初始值为 0。
• sort 建议固定为 id，保证每次请求内读取顺序稳定。
• paginated 设为 0，表示关闭分页，单次返回所有满足条件的记录。
• limit 控制单次返回的最大记录数，最大值为 10000，建议设置为 1000～10000。
• 每次请求完成后，取返回数组中最后一条记录的 id + 1 作为下一次请求的 id_egt。
• 当返回记录数为 0 时，表示当前数据集已全部读取完毕。

8.3 按字段条件筛选

适用于按业务字段查询数据的场景。

GET /v3/uds/datasets/v3_students/records?name_like=%E5%BC%A0&status_in=enabled,disabled

要求：

• 筛选字段必须来自元信息中的 fields.name。
• 枚举字段应先查看元信息中的 enum 可选值。
• 多值参数通常使用逗号分隔。

8.4 控制返回字段

适用于减少响应体积、降低下游解析复杂度的场景。

GET /v3/uds/datasets/v3_students/records?fields=id,name

要求：

• fields 使用字段名称，不使用字段显示名称。
• 推荐只返回业务处理所需字段。
• 如果下游按 ID 段同步，应始终返回主键字段。

8.5 展开关联数据

适用于需要同时读取主数据和关联数据的场景。

GET /v3/uds/datasets/v3_students/records?fields=id,name&expand=graduates_in

要求：

• expand 取值应来自元信息中的 relations.name。
• 展开后的关联对象结构由目标关联数据集决定。
• 关联展开会增加响应体积，应仅展开必要关联。