解析结构化导入回填起点¶

解析数据库结构化导入任务的回填起点。

POST https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/backfill-start/resolve

调用前准备¶

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。
选择可解析回填起点的连接器，从选中记录取得 connector_id 和 source_type。
定位来源对象：
- 选择来源数据库，取得 database。
- 如果所选连接器支持 Schema 层级，选择来源 Schema，取得 schema；否则不填写 schema。
- 选择来源对象，取得 table 或 collection。
将同一个连接器 ID 填入 connector_id 和 source.connector_id，再填写本次选择的来源对象。
选择回填起点模式。

请求体¶

将 $AI_STUDIO_API_KEY、$WORKSPACE_ID 和示例中的来源对象替换为实际值。

输入示例

默认

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/backfill-start/resolve" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"connector_id\": \"$CONNECTOR_ID\",
    \"source\": {
      \"connector_id\": \"$CONNECTOR_ID\",
      \"source_type\": \"$SOURCE_TYPE\",
      \"database\": \"$DATABASE\",
      \"table\": \"$TABLE\"
    },
    \"start_mode\": \"auto\"
  }"

填写自定义起点

source 用于定位一个来源对象，不代表另一个连接器。使用同一条连接器记录中的 connector_id 和 source_type 填写顶层和 source 中对应字段。

始终填写选中对象的 database。
对象包含 schema 时填写 source.schema。
表对象填写 source.table；MongoDB 集合填写 source.collection，不填写 source.table。
自动解析： 将 start_mode 设为 auto，不传非空的 custom_start_value。接口返回解析出的回填起点。
自定义起点： 将 start_mode 设为 custom，并传入 custom_start_value。先填写 kind，再填写与该类型对应的值字段。 start_mode 为 custom 时，custom_start_value 表示一个带类型的值：用 kind 指定类型，再只填写与该类型对应的那一个值字段。

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/backfill-start/resolve" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"connector_id\": \"$CONNECTOR_ID\",
    \"source\": {
      \"connector_id\": \"$CONNECTOR_ID\",
      \"source_type\": \"SOURCE_TYPE_MYSQL\",
      \"database\": \"appdb\",
      \"table\": \"orders\"
    },
    \"start_mode\": \"custom\",
    \"custom_start_value\": {
      \"kind\": \"int64\",
      \"int64_value\": \"100\"
    }
  }"

参数说明

默认

参数	类型	是否必填	说明
`connector_id`	string	是	要解析回填起点的连接器 ID。与 `source.connector_id` 使用相同的值。
`source`	object	是	要解析回填起点的单个数据库对象。
`source.connector_id`	string	是	来源对象所属连接器 ID。
`source.source_type`	string	是	来源连接器的结构化来源类型。
`source.database`	string	是	对象所属数据库名称。
`source.schema`	string	否	对象所属 Schema；对象结果包含该字段时填写。
`source.table`	string	表时必填	表名称。
`source.collection`	string	集合时必填	集合名称。
`watermark`	JSON	否	预留的水位线配置字段；当前起点解析不依赖此字段。
`start_mode`	string	是	起点模式：`auto` 自动解析，`custom` 使用自定义起点。
`custom_start_value`	JSON	custom 时必填	自定义起点值。`auto` 模式下省略或传入 `null`。

填写自定义起点

参数	类型	是否必填	说明
`connector_id`	string	是	要解析回填起点的连接器 ID；与 `source.connector_id` 使用相同的值。
`source`	object	是	要解析回填起点的来源表。
`source.connector_id`	string	是	来源表所属连接器 ID。
`source.source_type`	string	是	来源连接器的结构化来源类型。
`source.database`	string	是	来源表所属数据库名称。
`source.table`	string	是	来源表名称。
`start_mode`	string	是	固定为 `custom`，表示使用自定义起点。
`custom_start_value`	object	是	自定义起点。
`custom_start_value.kind`	string	是	值类型标识；示例使用 `int64`。
`custom_start_value.int64_value`	string	是	`int64` 类型的起点值，以字符串传递。

成功响应¶

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "start_position": {
      "kind": "int64",
      "int64_value": "100"
    },
    "display_value": "100"
  }
}

字段说明

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。
`data.start_position`	JSON	已解析的回填起点，保留来源类型值对象的 JSON 表示。
`data.display_value`	string	回填起点的展示值；无展示值时可能省略。

错误响应¶

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "参数错误信息",
  "data": null
}

字段说明

字段	类型	说明
`code`	string	错误代码。
`msg`	string	可读错误信息。
`data`	null	错误响应中为 `null`。

后续操作¶

当前版本不能将 data.start_position 用于创建数据库结构化导入任务：structured_load_config.backfill.enabled 为 true 时，创建请求会被拒绝。不要将本接口的成功响应视为已创建或可立即创建回填任务。

最后更新于 2026 年 9 月 1 日