OldSixLi

Appearance

页面导航
精简

数据模块 API 文档 ​

基础前缀：/external/private/api/data 鉴权：DEFrame-UserId、DEFrame-TenantId、DEFrame-ExtendedInfo 文档版本基准：4f46278（2026-08-11）

统一响应体结构：

json
{
  "code": 0,
  "message": "success",
  "data": {},
  "ext": null
}

1. 获取分类树 ​

名称：数据分类树 作用：返回当前租户下所有数据分类的树形结构（含子分类）。

  • 请求方式：GET
  • 路径：/external/private/api/data/categories/tree

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "cat-001",
      "name": "能源数据",
      "parentId": null,
      "createdAt": "2026-08-01T10:00:00",
      "updatedAt": "2026-08-01T10:00:00",
      "children": [
        {
          "id": "cat-002",
          "name": "电力数据",
          "parentId": "cat-001",
          "createdAt": "2026-08-01T10:05:00",
          "updatedAt": "2026-08-01T10:05:00",
          "children": []
        }
      ]
    }
  ],
  "ext": null
}

2. 创建分类 ​

名称：新建数据分类 作用：在当前租户下创建一个数据分类节点（可指定父分类）。

  • 请求方式：POST
  • 路径：/external/private/api/data/categories
  • 请求体：
json
{
  "name": "新能源数据",
  "parentId": "cat-001"
}

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": "cat-003",
  "ext": null
}

3. 更新分类 ​

名称：更新数据分类 作用：修改指定分类的名称。

  • 请求方式：PUT
  • 路径：/external/private/api/data/categories/{categoryId}
  • 请求体：
json
{
  "name": "新能源数据-改"
}

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": null,
  "ext": null
}

4. 删除分类 ​

名称：删除数据分类 作用：删除指定分类节点。

  • 请求方式：DELETE
  • 路径：/external/private/api/data/categories/{categoryId}

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": null,
  "ext": null
}

5. 复制分类 ​

名称：复制数据分类 作用：将源分类复制到目标父分类下（可重命名）。

  • 请求方式：POST
  • 路径：/external/private/api/data/categories/copy
  • 请求体：
json
{
  "sourceCategoryId": "cat-002",
  "targetParentId": "cat-001",
  "newName": "电力数据-副本"
}

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": "cat-004",
  "ext": null
}

6. 查询文件列表 ​

名称：分页文件列表 作用：按分类、名称关键字分页查询文件列表。

  • 请求方式：GET
  • 路径：/external/private/api/data/files
  • 查询参数：categoryId（可选）、name（可选）、page（默认 1）、size（默认 10）

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "records": [
      {
        "id": "file-001",
        "categoryId": "cat-002",
        "categoryName": "电力数据",
        "name": "负荷曲线.csv",
        "size": 102400,
        "fileType": "CSV",
        "status": 2,
        "parseError": null,
        "createdAt": "2026-08-01T11:00:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "ext": null
}

7. 上传文件到对象存储 ​

名称：文件上传（MinIO） 作用：将文件流上传至 MinIO 对象存储，返回存储地址。

  • 请求方式：POST
  • 路径：/external/private/api/data/files/upload
  • 请求体：multipart/form-data，字段 file

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "storageUrl": "minio://bucket/path/负荷曲线.csv",
    "fileSize": 102400,
    "fileExtension": "csv"
  },
  "ext": null
}

8. 保存文件元数据 ​

名称：登记文件 作用：将已上传（或外部）存储地址登记为数据文件记录。

  • 请求方式：POST
  • 路径：/external/private/api/data/files
  • 请求体：
json
{
  "categoryId": "cat-002",
  "storageUrl": "minio://bucket/path/负荷曲线.csv",
  "fileName": "负荷曲线.csv",
  "fileSize": 102400
}

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": "file-001",
  "ext": null
}

9. 预览文件内容 ​

名称：文件预览 作用：返回文件前若干行的内容（表头 + 数据矩阵）。

  • 请求方式：GET
  • 路径：/external/private/api/data/files/{fileId}/preview
  • 查询参数：rows（默认 10）

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "data": [
      ["2026-08-01 00:00", "120.5"],
      ["2026-08-01 01:00", "118.2"]
    ],
    "totalRows": 8760,
    "headers": ["time", "load"]
  },
  "ext": null
}

10. 删除文件 ​

名称：删除数据文件 作用：删除指定文件记录及其存储。

  • 请求方式：DELETE
  • 路径：/external/private/api/data/files/{fileId}

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": null,
  "ext": null
}

11. 批量删除文件 ​

名称：批量删除文件 作用：按文件 ID 列表批量删除。

  • 请求方式：POST
  • 路径：/external/private/api/data/files/batch-delete
  • 请求体：
json
{
  "fileIds": ["file-001", "file-002"]
}

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": null,
  "ext": null
}

12. 重试解析文件 ​

名称：重试文件解析 作用：对解析失败的文件重新触发解析流程。

  • 请求方式：POST
  • 路径：/external/private/api/data/files/{fileId}/retry-parse

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": null,
  "ext": null
}

13. 搜索文件 ​

名称：按名称搜索文件 作用：按文件名关键字搜索，结果按分类分组返回。

  • 请求方式：GET
  • 路径：/external/private/api/data/files/search
  • 查询参数：keyword（必填）

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "cat-002",
      "name": "电力数据",
      "parentId": "cat-001",
      "createdAt": "2026-08-01T10:05:00",
      "updatedAt": "2026-08-01T10:05:00",
      "children": [
        {
          "id": "file-001",
          "categoryId": "cat-002",
          "name": "负荷曲线.csv",
          "size": 102400,
          "fileType": "CSV",
          "status": 2,
          "parseError": null,
          "storageUrl": "minio://bucket/path/负荷曲线.csv",
          "createdAt": "2026-08-01T11:00:00",
          "updatedAt": "2026-08-01T11:00:00"
        }
      ]
    }
  ],
  "ext": null
}

14. 获取数据源状态 ​

名称：数据源状态 作用：返回当前 KaiwuDB 数据源连接状态与基本信息。

  • 请求方式：GET
  • 路径：/external/private/api/data/sources/status

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "CONNECTED",
    "name": "kaiwudb-prod",
    "host": "10.0.0.12",
    "port": 26257,
    "database": "energy",
    "schema": "public",
    "username": "kiap"
  },
  "ext": null
}

15. 获取数据源（别名） ​

名称：获取数据源信息 作用：与 /sources/status 等价，返回数据源状态信息。

  • 请求方式：GET
  • 路径：/external/private/api/data/sources

响应体：同接口 14。

16. 测试数据源连接 ​

名称：测试连接 作用：用给定连接配置测试 KaiwuDB 连通性（不持久化）。

  • 请求方式：POST
  • 路径：/external/private/api/data/sources/test-connection
  • 请求体：
json
{
  "name": "kaiwudb-test",
  "host": "10.0.0.12",
  "port": 26257,
  "database": "energy",
  "username": "kiap",
  "password": "******",
  "schema": "public"
}

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": null,
  "ext": null
}

17. 配置数据源 ​

名称：配置数据源 作用：保存并连接 KaiwuDB 数据源配置，返回数据源 ID。

  • 请求方式：POST
  • 路径：/external/private/api/data/sources/config
  • 请求体：同接口 16。

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": "ds-001",
  "ext": null
}

18. 断开数据源 ​

名称：断开数据源 作用：断开并清理当前 KaiwuDB 数据源连接。

  • 请求方式：POST
  • 路径：/external/private/api/data/sources/disconnect

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": null,
  "ext": null
}

19. 获取 Schema 列表 ​

名称：KaiwuDB Schema 列表 作用：返回已连接 KaiwuDB 的 schema 列表。

  • 请求方式：GET
  • 路径：/external/private/api/data/schemas

说明：依赖 KaiwuDB 连接，未连接时返回 500。

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "schemaName": "public",
      "description": "默认 schema"
    }
  ],
  "ext": null
}

20. 获取表列表 ​

名称：KaiwuDB 表列表 作用：返回已连接 KaiwuDB 的时序表列表。

  • 请求方式：GET
  • 路径：/external/private/api/data/tables

说明：依赖 KaiwuDB 连接，未连接时返回 500。

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "tableName": "power_load",
      "description": "电力负荷时序表",
      "variablesCount": 12,
      "status": 1
    }
  ],
  "ext": null
}

21. 获取标签列表 ​

名称：表标签列表 作用：返回指定表的标签（tag）元信息。

  • 请求方式：GET
  • 路径：/external/private/api/data/tags
  • 查询参数：tableName（必填）

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "name": "station_id",
      "type": "STRING",
      "isPrimary": true,
      "description": "站点编号",
      "filters": ["st-001", "st-002"]
    }
  ],
  "ext": null
}

22. 获取列列表 ​

名称：表字段列表 作用：返回指定表的字段（列）元信息。

  • 请求方式：GET
  • 路径：/external/private/api/data/columns
  • 查询参数：tableName（必填）

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "name": "load",
      "type": "DOUBLE",
      "description": "负荷值"
    }
  ],
  "ext": null
}

23. 查询表数据 ​

名称：时序数据点查询 作用：分页查询指定 KaiwuDB 表的时序数据点，支持时间范围、点过滤与标签过滤。

  • 请求方式：GET
  • 路径：/external/private/api/data/data
  • 查询参数：tableName（必填）、page（默认 1）、size（默认 10）、startTime（可选）、endTime（可选）、points（可选，多个）、标签过滤使用 tagFilters[标签名]=值 形式

响应体：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "records": [
      {
        "timestamp": "2026-08-01T00:00:00Z",
        "tags": { "station_id": "st-001" },
        "data": { "load": "120.5" }
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "ext": null
}

24. 导出表数据 ​

名称：时序数据导出 作用：将指定 KaiwuDB 表数据导出为 CSV（或其他格式）文件流下载。

  • 请求方式：GET
  • 路径：/external/private/api/data/data/export
  • 查询参数：tableName（必填）、startTime、endTime、points、format（默认 csv）、标签过滤同接口 23
  • 响应：application/octet-stream 文件流（无统一 JSON 响应体）