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 才是成功结果中的来源状态。

最后更新于