# 预览 REST API 来源样例

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

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

## 调用前准备

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

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
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"}}'
```

:::::
:::::{tab-item} 参数说明

请求体受 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 | 条件成对 | 本次预览的起始增量值。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `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 状态当作本请求状态。详见[错误与环境](objects.md#错误与环境)。
