# 结构化来源与导入控制公共说明

来源探测、采样、创建任务、触发运行和目标数据写入分别确认。采样或触发请求成功，不表示目标表已完成导入。

## 身份与变量

示例使用公开 `/v5` 地址、`AI_STUDIO_API_KEY` 和 `WORKSPACE_ID`。准备目标工作区的相应资源权限，所有连接器、任务和目标数据属于同一环境。来源接口也接受经校验的任务短期身份，但不能把运行时授权、角色或任务标识从其他环境复制过来。

`CONNECTOR_ID` 从连接器列表取得。Kafka 使用其实际可读的 `KAFKA_TOPIC`；表能力查询使用 `SOURCE_DATABASE` 与 `SOURCE_TABLE`，需要时增加 `source.schema`。`TASK_ID` 来自工作区导入任务列表或创建结果，不能使用一次运行 ID。

## API 枚举与来源限制

| 操作 | 当前允许的来源 | 参数与结果边界 |
| --- | --- | --- |
| 采样 | `SOURCE_TYPE_KAFKA` | 数量 1–100；single 一个主题，multiple 非空主题列表，pattern 非空模式。不传数据库、表、Schema 或集合。 |
| 表能力 | `SOURCE_TYPE_MYSQL`、`SOURCE_TYPE_DORIS` | 必须与连接器实际类型一致，并指定数据库与表。Doris 来源读取能力与 CDC 能力分别判断。 |
| 立即触发 | Kafka、Doris、MySQL、REST API 的周期结构化任务 | active、状态已创建或上传中、已有服务端周期工作流任务；MySQL 不带独立 compute。 |
| 单次全量刷新 | Doris 或 MySQL 周期增量任务 | active、状态已创建或上传中，run_mode=periodic 且 sync_strategy=incremental；MySQL 不带独立 compute。 |

API 使用 `SOURCE_TYPE_*`，Worker 的小写运行类型不是相同输入合同。SDK 和 CLI 不会自动修正这里的小写类型。Kafka 采样响应里的 `next_position` 形状由来源返回，当前接口输入没有位置/游标参数，不将其套成通用分页协议。

## 确认运行结果

运行控制成功返回 `code: OK`、`data: null`，没有在该响应返回本次运行 ID 或完成报告。查询任务运行记录与详情，结合时间、任务引用及错误核对本次执行，再确认目标数据。结果未知时先回查，不能靠每次发起新请求判断上次是否成功。

全量刷新为单次执行设置 `full_refresh`，不修改原周期任务的同步策略。它不是普通文件、Kafka、REST API 或所有失败状态的统一重试入口。任务暂停或依赖不可用时先处理当前状态及依赖。

## 错误与环境

| 动作 | 已确认的业务错误表现 | 处理 |
| --- | --- | --- |
| 来源采样与能力 | 无效来源类型/范围、停用连接器或不支持导入时为 HTTP 400 `ErrParamInvalid` | 保留连接器及环境，核对枚举、匹配类型、主题和数量。 |
| 结构化能力未开放 | 功能开关错误可为 HTTP 200，业务码 `STRUCTURED_LOAD_FEATURE_DISABLED` 或相关来源码 | 读取业务码；不能把 HTTP 200 当成能力开放。 |
| 运行控制 | 不合条件的任务状态/配置可为 HTTP 200 `ErrParamInvalid` | 读取业务码，再查任务及运行记录。权限与资源不存在等可在此之前返回其他状态。 |
| Worker 或来源读取 | 可有安全化的来源诊断与内部服务错误 | 保留请求信息与安全错误字段；不能将内部异常字段编造为稳定公共合同。 |

Genesis `/v1`、Billing 为独立服务。

旧 Reference 的来源浏览、Schema 与回填解析五个动作，以及 REST 草稿/已保存探测/预览三个缺失动作另需逐字段复核。这些接口四页不能视为覆盖全部来源或导入合同。
