REST API 数据接入

REST API 数据接入支持将外部 HTTP/HTTPS 接口返回的 JSON 记录导入 Catalog 数据表。先在连接器中保存服务基础地址和认证配置,再在导入任务中配置接口路径、分页策略、增量游标与目标表映射。

1. 创建 REST API 连接器

  1. 进入 数据连接 > 连接器,点击 新建连接器。

  2. 输入连接器名称,数据源类型选择 REST API,并确认用途包含导入。

  3. 填写 API 基础地址(如 https://api.example.com/v1/,需为完整的 HTTP/HTTPS 地址,不含查询参数或 # 片段)。

  4. 选择认证方式并填写对应凭据:

认证方式

需要配置的内容

无需认证

无需凭据

Bearer Token

访问令牌

API Key

API Key 位置(请求头或查询参数)、API Key 参数名与 API Key 值

HTTP Basic

用户名与密码

OAuth 2.0 · Client Credentials

令牌获取地址、客户端 ID、客户端密钥、客户端凭证传递方式、可选授权范围与令牌请求附加参数

  1. 按需展开高级选项配置公共 Headers、公共 Query 参数与请求超时(秒)(1–60 的整数)。

  2. 如需在保存前检查凭证,勾选配置验证接口(可选),填写只读的验证接口路径(以单个 / 开头的相对路径)、请求方法、可选参数以及业务状态字段路径和预期业务状态值(JSON),然后点击验证连接。

  3. 确认无误后保存连接器。

编辑已有连接器时,密钥类字段留空表示保留原已保存凭证。

2. 创建 REST API 导入任务

  1. 进入 数据连接 > 导入任务,选择 结构化,导入来源选择 REST API。

  2. 选择已配置好的 REST API 连接器,填写接口路径(以单个 / 开头,追加到连接器基础地址之后)。

  3. 展开高级选项按实际接口协议配置读取方式:

    • 记录路径(可选):当记录数组嵌套在 JSON 对象中时填写字段路径(如 $.data.items);

    • 分页方式:支持不分页、页码、偏移量、游标和下一页链接,并对应设置参数名、起始页码/偏移量或响应路径(如 $.paging.next);

    • 响应 Schema:可选勾选使用接口返回的 Schema,填写响应中的 Schema 路径(如 $.schema.fields)及格式(列描述或 JSON Schema);未勾选时将根据预览样本自动推断字段类型。

  4. 点击预览数据(支持 GET、OPTIONS 与勾选只读确认的 POST 只读查询接口)。预览最多读取第一页的 20 条记录且不会创建导入任务。

  5. 选择目标表(新建表或写入已有表),核对源字段、目标列名、目标数据类型(支持 BIGINT、DECIMAL、TEXT、VARCHAR、DATE、TIMESTAMP、BOOL、JSON、BLOB、VARBINARY)以及二进制编码(Base64 / Hex)。

  6. 选择一次性导入或周期导入:

    • 周期增量导入时,填写增量筛选 Query 参数名、记录中的增量游标字段、首次读取的游标值,确认游标大于或等于条件,并在目标映射中绑定至少一个主键及非空 BIGINT 或 TIMESTAMP(6) 版本字段;

    • 全量覆盖已有表时,导入成功后将替换目标表中的全部已有行。

  7. 点击创建并开始导入。提交成功后可在导入任务中查看执行状态,并在 Catalog 中确认最终写入的数据。

验证阶段区分与完成标志

  • 连接器中的「验证连接」:仅检查基础地址与认证凭据对验证路径的连通性。

  • 导入配置中的「预览数据」:校验分页方式、记录路径与字段映射,只拉取首屏样例,不会写入 Catalog 目标表。

  • 完成标志:导入任务状态变为成功后,打开目标 Catalog 表可看到真实写入的记录行,后续周期任务按游标增量追加。

最后更新于