---
url: /v6.2/api-data-service-faq.md
---
# 数据服务与 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**。

常见报错：

```json
{
  "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 吗？

有。

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

```text
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 数据源，需要先在配置里显式开启：

```properties
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.md)
* [API 查询数据集](dataset-api.md)
* [API 数据源](connecting-ext-api.md)