# 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**、**客户端密钥**、**客户端凭证传递方式**、可选**授权范围**与**令牌请求附加参数** |

5. 按需展开**高级选项**配置**公共 Headers**、**公共 Query 参数**与**请求超时（秒）**（1–60 的整数）。
6. 如需在保存前检查凭证，勾选**配置验证接口（可选）**，填写只读的**验证接口路径**（以单个 `/` 开头的相对路径）、**请求方法**、可选参数以及**业务状态字段路径**和**预期业务状态值（JSON）**，然后点击**验证连接**。
7. 确认无误后保存连接器。

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

## 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. 点击**创建并开始导入**。提交成功后可在[导入任务](load-tasks.md)中查看执行状态，并在 Catalog 中确认最终写入的数据。

## 验证阶段区分与完成标志

- **连接器中的「验证连接」**：仅检查基础地址与认证凭据对验证路径的连通性。
- **导入配置中的「预览数据」**：校验分页方式、记录路径与字段映射，只拉取首屏样例，不会写入 Catalog 目标表。
- **完成标志**：[导入任务](load-tasks.md)状态变为成功后，打开目标 Catalog 表可看到真实写入的记录行，后续周期任务按游标增量追加。
