API 数据集

最后更新: 2026/9/29

用 HTTP 接口作为数据源：请求配置、五种认证方式、响应 JSON Path、超时、内网访问限制与常见错误。

概述

API 数据集向一个 HTTP 接口发请求，把返回的 JSON 转成数据集。适合取业务系统的接口数据，不需要数据库直连。

功能入口

「新建SQL数据集」拆分按钮 >「API数据集」，打开「编辑API数据集」。对话框底部有「使用指南」「取消」「数据预览」「确定」。设计器的「特性示例」中有示例报表「API数据集-未来七天天气预报」。

操作步骤

填写「数据集名称」「请求URL」，选择「请求方法」。
选择「认证方式」并填写对应字段。
在「请求参数」「请求头」「请求体」标签页配置参数。
在「响应配置」填「JSON Path」，指出数据数组所在位置。
点击「数据预览」，字段通过预览识别；确认无误后点「确定」。

保存和预览时，引用了 ${$x} 的报表参数会自动登记。

属性说明

基本信息

属性	说明	取值/默认值
数据集名称	数据集名称	必填
请求URL	接口地址。可含 `$参数名` 与 `$$config.名称`	必填，仅 http/https
请求方法	请求方式	GET、POST；其他值按 GET 发送

认证方式

方式	字段
无认证	无
Basic Auth	用户名、密码
Bearer Token	Token、前缀（默认 `Bearer`）
API Key	Key、Value，「添加到」Header 或 Query Params
OAuth2	Token URL、Client ID、Client Secret、Grant Type（默认 `client_credentials`）、Scope（默认 `read`）；获取的令牌会缓存，`client_secret` 放在 POST 表单体中

未选择认证方式时报「未定义数据请求的认证方式!」，未填 URL 时报「未定义数据请求的URL!」。

请求参数、请求头

名称/值表格。值可写常量、$参数名 或 ${表达式}。与报表参数同名的行，运行时使用报表参数的值覆盖默认值，但值是表达式时不覆盖。GET 的参数被 URL 编码后追加到 URL，值为空的写成 key=。

请求体

Body 类型	说明
无	不发送请求体
x-www-form-urlencoded	引擎读取并发送
raw	格式可选 JSON、Text、XML。引擎读取 raw 内容，按 JSON 对象解析，解析失败视为空对象，以 `application/json` 发送
form-data	界面可选，但引擎不读取该类型，不要使用

响应配置与高级设置

属性	说明	取值/默认值
JSON Path	取响应中哪一段作为数据；留空表示整个响应。`$.data`、`.data`、`data` 等价	可选
连接超时(ms)	建立连接的超时，单位毫秒	界面允许 1000–60000，新建时默认 10000；模板里未配置或小于等于 0 时后端缺省 3000
读取超时(ms)	等待响应的超时，单位毫秒	界面允许 1000–120000，新建时默认 30000；模板里未配置或小于等于 0 时后端缺省 6000

嵌套 JSON 字段会用点号展开成平铺字段，如 name.common。HTTP 状态码必须是 200，否则报错。

注意：超时字段单位是毫秒。手工编辑模板时若填了小于 1000 的正数（如 5），后端按「秒」理解并乘以 1000（5 即 5000 毫秒）。

示例

某院内接口 https://his.example.com/api/visits，返回：

{"code":0,"data":[{"deptCode":"D01","visitCnt":128},{"deptCode":"D02","visitCnt":96}]}

配置：

项	值
请求URL	`https://his.example.com/api/visits`
请求方法	GET
认证方式	Bearer Token，Token 填写接口令牌
请求参数	`date` = `$visitDate`
JSON Path	`$.data`

预览得到字段 deptCode、visitCnt。visitDate 为报表参数时会随查询表单变化。

注意事项

注意：默认启用地址防护，拒绝回环、链路本地、内网、CGNAT、组播与 IPv6 ULA 地址，且不跟随重定向，报「API 数据集目标地址被禁止（内网/环回/元数据）」或「主机名无法解析」。确需访问内网接口时，可设置系统属性 sightdata.api-dataset.ssrf-guard.enabled=false 或环境变量 SIGHT_DATA_API_SSRF_GUARD=false，风险自负。

注意：自签名证书场景可用系统属性 sightdata.api-dataset.tls.trust-all=true 或环境变量 SIGHT_DATA_API_TLS_TRUST_ALL=true 信任所有证书，会降低安全性。

注意：API 数据集受非 SQL 数据集行数限制，超过时报错。

提示：接口返回较大时，尽量通过请求参数在服务端过滤，而不是在报表中筛选。