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

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

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

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

## 调用前准备

1. 准备有目标工作区访问权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。
2. [选择可解析回填起点的连接器](../connector-data-sources/list-structured-data-sources.md#选择连接器)，从选中记录取得 connector_id 和 source_type。
3. 定位来源对象：
   - [选择来源数据库](../connector-data-sources/list-databases.md#选择来源数据库)，取得 database。
   - 如果所选连接器支持 Schema 层级，[选择来源 Schema](../connector-data-sources/list-schemas.md#选择来源-schema)，取得 schema；否则不填写 schema。
   - [选择来源对象](../connector-data-sources/list-tables.md#选择来源对象)，取得 table 或 collection。
4. 将同一个连接器 ID 填入 connector_id 和 source.connector_id，再填写本次选择的来源对象。
5. 选择回填起点模式。

## 请求体

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

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

::::{tab-set}
:::{tab-item} 默认

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

:::
:::{tab-item} 填写自定义起点

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` 指定类型，再只填写与该类型对应的那一个值字段。

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

:::
::::

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

::::{tab-set}
:class: mo-api-parameter-table

:::{tab-item} 默认

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `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`。 |

:::
:::{tab-item} 填写自定义起点

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `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` 类型的起点值，以字符串传递。 |

:::
::::

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

## 成功响应

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

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

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

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

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

## 错误响应

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

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

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

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

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

## 后续操作

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