REST API 数据接入¶
REST API 数据接入支持将外部 HTTP/HTTPS 接口返回的 JSON 记录导入 Catalog 数据表。先在连接器中保存服务基础地址和认证配置,再在导入任务中配置接口路径、分页策略、增量游标与目标表映射。
1. 创建 REST API 连接器¶
进入 数据连接 > 连接器,点击 新建连接器。
输入连接器名称,数据源类型选择 REST API,并确认用途包含导入。
填写 API 基础地址(如
https://api.example.com/v1/,需为完整的 HTTP/HTTPS 地址,不含查询参数或#片段)。选择认证方式并填写对应凭据:
认证方式 |
需要配置的内容 |
|---|---|
无需认证 |
无需凭据 |
Bearer Token |
访问令牌 |
API Key |
API Key 位置(请求头或查询参数)、API Key 参数名与 API Key 值 |
HTTP Basic |
用户名与密码 |
OAuth 2.0 · Client Credentials |
令牌获取地址、客户端 ID、客户端密钥、客户端凭证传递方式、可选授权范围与令牌请求附加参数 |
按需展开高级选项配置公共 Headers、公共 Query 参数与请求超时(秒)(1–60 的整数)。
如需在保存前检查凭证,勾选配置验证接口(可选),填写只读的验证接口路径(以单个
/开头的相对路径)、请求方法、可选参数以及业务状态字段路径和预期业务状态值(JSON),然后点击验证连接。确认无误后保存连接器。
编辑已有连接器时,密钥类字段留空表示保留原已保存凭证。
2. 创建 REST API 导入任务¶
进入 数据连接 > 导入任务,选择 结构化,导入来源选择 REST API。
选择已配置好的 REST API 连接器,填写接口路径(以单个
/开头,追加到连接器基础地址之后)。展开高级选项按实际接口协议配置读取方式:
记录路径(可选):当记录数组嵌套在 JSON 对象中时填写字段路径(如
$.data.items);分页方式:支持不分页、页码、偏移量、游标和下一页链接,并对应设置参数名、起始页码/偏移量或响应路径(如
$.paging.next);响应 Schema:可选勾选使用接口返回的 Schema,填写响应中的 Schema 路径(如
$.schema.fields)及格式(列描述或 JSON Schema);未勾选时将根据预览样本自动推断字段类型。
点击预览数据(支持
GET、OPTIONS与勾选只读确认的POST只读查询接口)。预览最多读取第一页的 20 条记录且不会创建导入任务。选择目标表(新建表或写入已有表),核对源字段、目标列名、目标数据类型(支持
BIGINT、DECIMAL、TEXT、VARCHAR、DATE、TIMESTAMP、BOOL、JSON、BLOB、VARBINARY)以及二进制编码(Base64/Hex)。选择一次性导入或周期导入:
周期增量导入时,填写增量筛选 Query 参数名、记录中的增量游标字段、首次读取的游标值,确认游标大于或等于条件,并在目标映射中绑定至少一个主键及非空
BIGINT或TIMESTAMP(6)版本字段;全量覆盖已有表时,导入成功后将替换目标表中的全部已有行。
点击创建并开始导入。提交成功后可在导入任务中查看执行状态,并在 Catalog 中确认最终写入的数据。
验证阶段区分与完成标志¶
连接器中的「验证连接」:仅检查基础地址与认证凭据对验证路径的连通性。
导入配置中的「预览数据」:校验分页方式、记录路径与字段映射,只拉取首屏样例,不会写入 Catalog 目标表。
完成标志:导入任务状态变为成功后,打开目标 Catalog 表可看到真实写入的记录行,后续周期任务按游标增量追加。