# REST API 来源公共说明

草稿探测、已保存连接器探测和样本预览分别处理配置与结果。探测会访问来源验证端点；预览会读取来源样例；两者都不会创建导入任务或写入目标表。

## 身份与配置文件

使用目标工作区的个人访问令牌、`WORKSPACE_ID` 及相应连接器操作权限。草稿探测读取本地配置文件：把含 `rest_api` 的 JSON 对象文件路径设置为 `REST_CONFIG_JSON`，安装 jq；示例将文件对象放在请求的 `config` 中，不转成 JSON 字符串。

已保存动作的 `CONNECTOR_ID` 来自同一工作区的连接器列表，须为 active、来源类型 REST API 且具有导入用途。保存后使用服务端保存的连接信息和凭据；不能通过探测请求体临时覆盖。不要用连接器详情的回显值替代原始秘密配置重新提交草稿。

## 草稿配置

| 字段 | 类型 | 条件与说明 |
| --- | --- | --- |
| `rest_api.base_url` | string | HTTP 或 HTTPS 地址，必须有主机；不含 URL 用户信息、查询、片段、反斜线或空白。 |
| `rest_api.auth` | object | 指定下表中的认证类型及其必需字段。 |
| `rest_api.request_timeout_seconds` | integer | 必填，1–60 秒。 |
| `rest_api.headers` | object[] | 全局请求头，每项含字符串 `name` 和 `value`。 |
| `rest_api.params` | object[] | 全局查询参数，每项含字符串 `name` 和 `value`。 |
| `rest_api.probe.enabled` | boolean | 探测动作要求 true。 |
| `rest_api.probe.path` | string | 以 `/` 开头的端点路径；不能以 `//` 开头或包含反斜线、查询、片段及空白。查询使用 params。 |
| `rest_api.probe.method` | string | GET 或 POST。 |
| `rest_api.probe.headers`、`params` | object[] | 当前探测端点的请求头或查询参数。 |
| `rest_api.probe.body_type` | string | POST 时为 json 或 form；不能省略后假定默认 JSON。 |
| `rest_api.probe.json` | string | 有效 JSON 文本，不能与表单 data 同用。 |
| `rest_api.probe.data` | object[] | 表单 name/value 对，POST form 使用。 |
| `rest_api.probe.get_json_body` | boolean | GET 如启用此项须提供非空有效 json；关闭时配置解码会移除 GET JSON body。 |
| `rest_api.probe.success_path` | string | 与 success_value 成对；在来源 JSON 中选择一个值。 |
| `rest_api.probe.success_value` | string | 有效 JSON 文本；比较值和 JSON 类型，`true` 与字符串 `"true"` 不相同。 |

| auth.type | 必需字段 | 可选字段 |
| --- | --- | --- |
| none | 无其他必需字段 | 无。 |
| bearer | token | 无。 |
| api_key | name、api_key、location | location 为 header 或 query。 |
| http_basic | username、password | 无。 |
| oauth2_client_credentials | access_token_url、client_id、client_secret、client_auth | client_auth 为 basic 或 body；scope 及 token_params（name/value 对）按来源需要配置。 |

来源认证与普通请求头分开设置。不能在自定义请求头中设置 Host、Cookie 或 Proxy-Authorization；使用对应认证时，也不能在自定义头或查询中重复设置其认证位置。探测 GET/POST 由来源定义，尤其 POST 的副作用需要调用方确认，不能把“验证请求”当作来源必定只读。

## 预览端点与分页

预览使用已保存的 base_url 和认证，当前请求只定义端点、提取与分页设置。GET、OPTIONS 或显式 `read_only_post: true` 的 POST 可用；声明只读并不会约束来源服务自身的写入行为。

| pagination.type | 必需字段 | 说明 |
| --- | --- | --- |
| none | 无其他字段 | 不配置翻页。 |
| page | param、start | start 必须显式提供且不小于 0。 |
| offset | param、start、step | start 显式提供且不小于 0，step 至少 1。 |
| cursor | param、next_path | 来源响应中的下一游标路径。 |
| next_url | next_path | 来源响应中的下一 URL 路径；完整导入另有同源检查。 |

`total_path` 可用于数字分页总量；本预览只取首页，不证明后续页可读取。分页 cursor 与可选的 `cursor_param`/`initial_cursor` 增量起点不是同一配置；后一组须一起提供。

显式 Schema 使用成对的 `schema_path` 和 `schema_format`（columns 或 json_schema）；来源声明与记录不匹配时应处理错误，不能当作可忽略的类型建议。没有显式 Schema 时使用样例推导字段；建议目标类型不代表已建表或已完成列映射。

预览最多取首页的 20 条记录，整个序列化结果上限 512 KiB。返回记录和字段是受限样例，不提供已读完所有来源的保证。不要把宽整数、金额等原始 JSON 数值先转换为有精度损失的客户端浮点数。

## 错误与环境

| 情况 | 本请求的响应 | 处理 |
| --- | --- | --- |
| 无效配置或不合条件的保存连接器 | 通常 HTTP 400 `ErrParamInvalid`；认证、资源或服务错误可有其他状态 | 核对配置对象、认证类型、超时、端点、用途及状态。 |
| 来源拒绝、记录/Schema 提取失败、验证条件未满足、预览过大、超时或连接问题 | HTTP 502 `ErrConnectorRESTRead` 及本地化信息 | 来源 HTTP 状态可能写在消息中，与 MOI 的 HTTP 502 分别判断；不按来源 HTTP 200 推断预览业务成功。 |
| 本地化或其他内部服务异常 | 可为 HTTP 500 或对应服务错误 | 保留请求信息，按实际公开错误处理，不依赖私有 Worker 诊断。 |

响应不会把 Worker 请求标识、执行状态和原始内部异常作为稳定公开字段返回；相关安全化表现已由 handler 本地用例检查。预览的 `data.status_code` 才是成功结果中的来源状态。
