报表数据获取指南

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

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

• Reporting：读取报表参数、查询定义和查询结果
• Dataset：直接读取底层数据集记录

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

1. 接口范围

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

2. 对接前准备

2.1 鉴权

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

Token 接口：

POST /api/v3/oauth/tokens

业务接口请求头：

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

要求：

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

2.2 权限范围

读取报表数据时，通常需要以下 Scope：

• reporting.read_all：读取报表中的参数、查询定义和查询结果
• dataset.read_all：直接读取数据集记录

注意：

• Reporting 相关 3 个接口都要求 reporting.read_all。
• Dataset 记录查询接口要求 dataset.read_all。

2.3 分页与查询参数约定

分页

报表查询结果接口和数据集记录接口都支持以下分页参数：

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

报表参数

执行报表查询时，查询参数通过 params 传递，参数值为 JSON 字符串。例如：

params={"semester_id":"202401","grade_ids":["7","8"]}

请求时应对该字符串进行 URL Encode。

数据集动态筛选

查询数据集记录时，动态筛选参数遵循 {field}_{operator} 语法。例如：

• id_in=1,2
• name_like=张三
• status_in=enabled,disabled
• created_at_egt=2026-03-01 00:00:00

3. 数据关系图

report
  ├── parameter
  └── query
        ├── fields
        └── rows

dataset
  └── dataset_record

report query
  └── 通常依赖一个或多个 dataset

关键关系：

• 一个 report 下可以定义多个筛选参数 parameter
• 一个 report 下可以定义多个查询 query
• 执行单个 query 后，返回字段定义 fields 和数据行 rows
• rows 中的键通常与 fields.name 对应
• 报表查询通常基于一个或多个 dataset 计算得出
• 当报表结果不能满足联调或明细分析需求时，可直接查询 dataset 记录

4. 总体调用顺序

推荐调用顺序如下：

1. 通过 OAuth 获取 Token
2. 确认应用已开通 reporting.read_all；如需直接查询数据集，再确认 dataset.read_all
3. 调用报表参数接口，识别必填参数、默认值和可选项
4. 调用报表查询列表接口，确认报表下可执行的查询
5. 按目标查询和参数组合执行报表查询
6. 根据 fields 解析 rows，并转换为下游所需结构
7. 如需校验口径、排查问题或补充明细，再直接查询相关数据集记录

5. 第一步：获取报表参数

接口：

GET /v3/reporting/reports/{id_or_name}/parameters

OpenAPI： 获取报表中定义的参数

说明：

• {id_or_name} 支持传入报表 ID 或报表名称
• 通过报表中心后台页面 url 获取，例如：https://chalk-c3.seiue.com/admin/report-center/reports/8879/7621/detail 中的 7621 就是报表 ID
• 该接口用于获取报表中定义的筛选项及其传参要求

请求参数：

返回字段：

6. 第二步：获取报表下的查询列表

接口：

GET /v3/reporting/reports/{id_or_name}/queries

OpenAPI： 获取报表下的所有查询

说明：

• 一个报表下可能包含多个查询，例如汇总查询、明细查询、透视查询
• 执行查询前，应先获取目标 query_id

请求参数：

返回字段：

7. 第三步：执行报表查询并获取结果

接口：

GET /v3/reporting/reports/{id_or_name}/queries/{query_id}/records

OpenAPI： 执行报表中的单个查询

说明：

• 该接口执行报表中的单个查询并返回结果
• params 使用 JSON 字符串传递, key 对应参数定义中的 name, value 则是实际传入的参数值，如果是 options 类型的参数，则 value 应该是 Option 的 key 而非 label
• 支持分页

请求参数：

返回结构：

fields 中常用字段：

返回示意：

{
  "fields": [
    {
      "kind": "string",
      "position": 0,
      "name": "student_name",
      "label": "学生姓名",
      "is_dynamic": false
    },
    {
      "kind": "decimal",
      "position": 1,
      "name": "total_score",
      "label": "总分",
      "is_dynamic": false
    }
  ],
  "rows": [
    {
      "student_name": "张三",
      "total_score": "632.5"
    }
  ]
}

8. 第四步：直接查询数据集记录

接口：

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

OpenAPI： 查询数据集记录

说明：

• 该接口直接读取数据集记录，不经过报表展示层
• 适用于明细补数、联调验证及报表口径排查
• 支持分页、排序、字段裁剪与关联展开

请求参数：

补充说明：

• 支持任意 {field}_{operator} 形式的动态筛选参数
• expand 取值由目标数据集已开放的关联字段决定