REST API 来源公共说明¶
草稿探测、已保存连接器探测和样本预览分别处理配置与结果。探测会访问来源验证端点;预览会读取来源样例;两者都不会创建导入任务或写入目标表。
身份与配置文件¶
使用目标工作区的个人访问令牌、WORKSPACE_ID 及相应连接器操作权限。草稿探测读取本地配置文件:把含 rest_api 的 JSON 对象文件路径设置为 REST_CONFIG_JSON,安装 jq;示例将文件对象放在请求的 config 中,不转成 JSON 字符串。
已保存动作的 CONNECTOR_ID 来自同一工作区的连接器列表,须为 active、来源类型 REST API 且具有导入用途。保存后使用服务端保存的连接信息和凭据;不能通过探测请求体临时覆盖。不要用连接器详情的回显值替代原始秘密配置重新提交草稿。
草稿配置¶
字段 |
类型 |
条件与说明 |
|---|---|---|
|
string |
HTTP 或 HTTPS 地址,必须有主机;不含 URL 用户信息、查询、片段、反斜线或空白。 |
|
object |
指定下表中的认证类型及其必需字段。 |
|
integer |
必填,1–60 秒。 |
|
object[] |
全局请求头,每项含字符串 |
|
object[] |
全局查询参数,每项含字符串 |
|
boolean |
探测动作要求 true。 |
|
string |
以 |
|
string |
GET 或 POST。 |
|
object[] |
当前探测端点的请求头或查询参数。 |
|
string |
POST 时为 json 或 form;不能省略后假定默认 JSON。 |
|
string |
有效 JSON 文本,不能与表单 data 同用。 |
|
object[] |
表单 name/value 对,POST form 使用。 |
|
boolean |
GET 如启用此项须提供非空有效 json;关闭时配置解码会移除 GET JSON body。 |
|
string |
与 success_value 成对;在来源 JSON 中选择一个值。 |
|
string |
有效 JSON 文本;比较值和 JSON 类型, |
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 |
核对配置对象、认证类型、超时、端点、用途及状态。 |
来源拒绝、记录/Schema 提取失败、验证条件未满足、预览过大、超时或连接问题 |
HTTP 502 |
来源 HTTP 状态可能写在消息中,与 MOI 的 HTTP 502 分别判断;不按来源 HTTP 200 推断预览业务成功。 |
本地化或其他内部服务异常 |
可为 HTTP 500 或对应服务错误 |
保留请求信息,按实际公开错误处理,不依赖私有 Worker 诊断。 |
响应不会把 Worker 请求标识、执行状态和原始内部异常作为稳定公开字段返回;相关安全化表现已由 handler 本地用例检查。预览的 data.status_code 才是成功结果中的来源状态。