预览 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 可用于来源检查,不保证返回业务记录。
字段 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
路径必填 |
当前工作区有效的 REST API 导入连接器 ID。 |
|
string |
是 |
以 / 开头的来源端点路径,不用完整 URL。 |
|
string |
是 |
GET、OPTIONS,或显式声明只读的 POST。 |
|
boolean |
POST 必填 |
POST 时设为 true;这是调用方声明,不会使来源原本的写操作变成只读。 |
|
object[] |
否 |
端点查询参数,元素含 name/value 字符串。 |
|
object[] |
否 |
端点请求头,元素含 name/value 字符串;不能冲突于连接认证与保留头。 |
|
string |
否 |
有效 JSON 文本;不是直接嵌套 JSON 对象。不能与 data 同用。 |
|
object[] |
否 |
表单字段,元素含 name/value 字符串;不能与 json 同用。 |
|
string |
否 |
记录提取路径,示例 $.data;按真实来源响应设置。 |
|
string |
条件成对 |
与 schema_format 一起提供;必须非空。 |
|
string |
条件成对 |
columns 或 json_schema。 |
|
object |
是 |
指定 none、page、offset、cursor 或 next_url,详见公共说明。 |
|
string |
条件成对 |
增量起点参数名;与 initial_cursor 一起提供,不是普通分页游标。 |
|
string |
条件成对 |
本次预览的起始增量值。 |
成功响应¶
{
"code": "OK",
"msg": "OK",
"data": {
"status_code": 200,
"records": [],
"fields": []
}
}
字段 |
类型 |
说明 |
|---|---|---|
|
string |
成功时为 OK。 |
|
string |
响应信息。 |
|
object |
本次动作结果。 |
|
integer |
来源 HTTP 响应状态,和 MOI 本次请求的 HTTP 状态分开。 |
|
object[] |
首页有限记录样例;为空不表示来源永远没有数据。 |
|
object[] |
声明或样例推导的字段。 |
|
string |
字段名。 |
|
string |
来源字段路径。 |
|
string |
来源类型描述。 |
|
string |
建议目标类型,不等于已创建目标表。 |
|
boolean |
字段是否可空。 |
|
boolean |
字段是否要求存在。 |
错误响应¶
配置错误与来源执行失败分开处理。MOI 可将来源错误包装为 HTTP 502 ErrConnectorRESTRead;不要将信息中的来源 HTTP 状态当作本请求状态。详见错误与环境。