预览 REST API 来源样例

用已保存连接器的连接信息,读取来源首页的记录与字段样例。

POST https://api.moi.matrixorigin.cn/v5/connectors/{id}/rest-api/preview

调用前准备

准备目标工作区的个人访问令牌及连接器对应操作权限。草稿文件、来源端点与环境边界见公共说明。

请求体

curl -X POST "https://api.moi.matrixorigin.cn/v5/connectors/$CONNECTOR_ID/rest-api/preview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary '{"path":"/records","method":"GET","records_path":"$.data","pagination":{"type":"none"}}'

请求体受 1 MiB 读取上限约束;不提交或覆盖保存的 base_url/auth。使用保存的连接信息及本次端点配置。预览最多取首页的 20 条记录,序列化结果上限 512 KiB,超出返回预览过大错误;它不能验证整个来源、后续分页或导入完成。OPTIONS 可用于来源检查,不保证返回业务记录。

字段

类型

是否必填

说明

id

string

路径必填

当前工作区有效的 REST API 导入连接器 ID。

path

string

是

以 / 开头的来源端点路径,不用完整 URL。

method

string

是

GET、OPTIONS,或显式声明只读的 POST。

read_only_post

boolean

POST 必填

POST 时设为 true;这是调用方声明,不会使来源原本的写操作变成只读。

params

object[]

否

端点查询参数,元素含 name/value 字符串。

headers

object[]

否

端点请求头,元素含 name/value 字符串;不能冲突于连接认证与保留头。

json

string

否

有效 JSON 文本;不是直接嵌套 JSON 对象。不能与 data 同用。

data

object[]

否

表单字段,元素含 name/value 字符串;不能与 json 同用。

records_path

string

否

记录提取路径,示例 $.data;按真实来源响应设置。

schema_path

string

条件成对

与 schema_format 一起提供;必须非空。

schema_format

string

条件成对

columns 或 json_schema。

pagination

object

是

指定 none、page、offset、cursor 或 next_url,详见公共说明。

cursor_param

string

条件成对

增量起点参数名;与 initial_cursor 一起提供,不是普通分页游标。

initial_cursor

string

条件成对

本次预览的起始增量值。

成功响应

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "status_code": 200,
    "records": [],
    "fields": []
  }
}

字段

类型

说明

code

string

成功时为 OK。

msg

string

响应信息。

data

object

本次动作结果。

data.status_code

integer

来源 HTTP 响应状态,和 MOI 本次请求的 HTTP 状态分开。

data.records

object[]

首页有限记录样例;为空不表示来源永远没有数据。

data.fields

object[]

声明或样例推导的字段。

data.fields[].name

string

字段名。

data.fields[].path

string

来源字段路径。

data.fields[].source_type

string

来源类型描述。

data.fields[].suggested_target_type

string

建议目标类型,不等于已创建目标表。

data.fields[].nullable

boolean

字段是否可空。

data.fields[].required

boolean

字段是否要求存在。

错误响应

配置错误与来源执行失败分开处理。MOI 可将来源错误包装为 HTTP 502 ErrConnectorRESTRead;不要将信息中的来源 HTTP 状态当作本请求状态。详见错误与环境。

最后更新于