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

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

身份与变量

示例使用公开 /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 草稿/已保存探测/预览三个缺失动作另需逐字段复核。这些接口四页不能视为覆盖全部来源或导入合同。

最后更新于