数据服务与 API

很多 API 相关问题并不是“系统支不支持”，而是没先分清楚你到底是在做 API 服务、API 查询数据集，还是 API 数据源接入。这页先把高频边界讲清楚。

API 服务、API 查询数据集、API 数据源 有什么区别？

它们解决的是三类不同问题：

能力	更适合做什么
API 服务	把系统里的图表、数据集、数据连接结果发布成可调用接口
API 查询数据集	把一个 HTTP JSON API 直接变成可分析的数据集
API 数据源	把外部 API 平台接成数据连接，供系统持续读取和分析

如果你是想“把 HENGSHI 里的结果提供给外部系统”，优先看 API 服务。
如果你是想“把外部 HTTP API 拉进 HENGSHI”，优先看 API 查询数据集 或 API 数据源。

为什么申请 token 时会报 unauthorized？

一个高频原因是：你带着当前登录态的 cookie 去申请 token。

常见报错：

{
  "error": "unauthorized",
  "error_description": "There is no client authentication. Try adding an appropriate authentication filter."
}

这时优先检查：

1. 请求 /api/oauth2/server/tokens 时是不是还带着有效 cookie
2. 是否在浏览器登录态下直接复用了同一个请求环境

最直接的处理方式通常就是：删掉 Headers 里的 cookie，或者退出登录后再申请。

想给数据集新增自定义字段，有 API 吗？

有。

可以通过下面的接口给数据集新增字段：

POST /api/apps/${appid}/datasets/${datasetid}/fields

典型适用场景：

• 自动补充公式字段
• 批量化创建计算字段
• 外部系统驱动的数据集结构增强

如果你的需求是“程序化批量加字段”，这类 API 比手工在页面里逐个维护更合适。

什么时候该用 API 查询数据集，什么时候该用 API 数据源？

可以先按这个判断：

场景	更适合
只需要把一个 HTTP JSON 接口快速变成数据集	API 查询数据集
要把外部 API 平台接成长期使用的数据连接	API 数据源
要对外暴露 HENGSHI 内部结果	API 服务

如果你的需求只是“给某个接口配 Header、Query、Body、分页，然后尽快做分析”，通常 API 查询数据集 更直接。
如果你的需求是“把一类 API 平台规范化接入，让业务长期复用”，才更像 API 数据源。

自定义 API 数据源一定要写 Groovy 吗？

只有当内置 API 数据源满足不了你时，才需要进入自定义 API 数据源。

而且要注意：从 5.1 开始，页面上填写的 Groovy 脚本默认关闭。如果你要在页面里通过 Groovy 写自定义 API 数据源，需要先在配置里显式开启：

ENABLE_GROOVY_SCRIPT=true

配置后还需要重启服务生效。
如果你们是把 Groovy 脚本上传到服务器并通过 EXT_API_PATH 管理，则不受这个页面开关影响。

API 数据源定义文件最少要实现什么？

最少要实现 4 个函数：

• getApiName
• setOptions
• getPathTables
• fetchTableData

如果这些基础结构都没实现完整，页面里就算能选到 API Name，也很难形成可用的数据连接。

什么情况下应该优先用注册 API，而不是自己从零写后端？

当你只是想把第三方 API 重新封装成标准接口，并顺手利用 HENGSHI 的发布、授权、限流、监控能力时，注册 API 很合适。

它适合：

• 统一接口入口
• 做参数透传或固定传参
• 给第三方 API 套一层受控网关

如果你的真实需求已经变成复杂业务编排、长流程状态机或重计算后端，那就不该只靠注册 API 解决。

API 相关问题，排障时第一优先该看什么？

先分层：

现象	优先排查
token 申请失败	认证参数、cookie、client 配置
外部 HTTP API 拉不进来	Header / Query / Body / 分页 / 认证方式
自定义 API 数据源不生效	Groovy 开关、脚本结构、API Config 解析逻辑
对外发布的 API 返回不对	API 服务里绑定的数据集/图表、默认参数、发布版本

如果连“当前属于哪一类 API 能力”都还没分清，排障通常会越查越乱。

进一步阅读：

• API 服务
• API 查询数据集
• API 数据源