文档中心

数据智能体 DataAgent（私有化）

结构化知识库导入

发起结构化数据导入

发起结构化数据导入

调用本接口自动确保 OpenSearch 索引就绪后，发起本地文件或 Prep 数据集导入并返回统一任务引用。

调用方：开放平台应用、外部 Agent 或集成服务。
前置条件：调用者拥有知识库编辑权限、资产字段配置有效并提供 Idempotency-Key。

接口说明

接口名称：start_structured_import_structured_knowledge_v1_kbs__kb_id__assets__asset_id__imports_post
接口地址：/structured_knowledge/v1/kbs/{kb_id}/assets/{asset_id}/imports
请求方式：POST

请求参数

参数名	类型	是否必传	描述
Idempotency-Key	String	是	调用方生成的写请求幂等键；同一租户、操作和请求体重试时必须保持不变

Path

参数名	类型	是否必传	描述
kb_id	String	是	结构化知识库 ID，由创建知识库或查询知识库列表接口返回
asset_id	String	是	结构化数据资产 ID，由创建资产或查询资产列表接口返回

请求体

参数名	类型	是否必传	描述
source_type	String	是	文件类型 EXCEL CSV CLICKHOUSE HIVE
source_config	Object	是	配置，详情请参见下文 source_config 表
mode	String	否	INITIAL APPEND UPSERT
unique_key_fields	Array	否	本次追加或覆盖导入使用的唯一标识列；兼容旧参数 primary_key_fields

source_config

参数名	类型	是否必传	描述
source_type	String	是	文件类型 EXCEL CSV CLICKHOUSE HIVE
file_id	String	否	Excel/CSV 上传后的文件 ID
dataset_id	String	否	Prep 数据集 ID
dataset_name	String	否	创建资产时记录的 Prep 数据集名称
database_name	String	否	CK/Hive 库名
table_name	String	否	CK/Hive 表名
partition_type	String	否	分区类型 NON_PARTITION FULL_PARTITION INCREMENTAL_PARTITION
partition_fields	Array	否	分区字段，最多两个
task_name	String	否	Prep 导入任务名称
auto_update_config	Object	否	Prep 输入算子增量配置及 scheduleConf 定时配置。详情请参见下文 auto_update_config 表
sheet_config	Object	否	Excel/CSV sheet 解析配置。详情请参见下文 sheet_config 表

auto_update_config

参数名	类型	是否必传	描述
isIncrement	Boolean	否	是否按增量字段读取数据；false 表示由 Prep 执行全量读取
incrementField	String	否	增量读取使用的源表字段名，仅 isIncrement=true 时必填
incrementFieldType	String	否	增量字段类型，由 Prep 用于解释增量游标值
timeFormat	String 或 Object	否	时间型增量字段的格式配置，具体格式遵循 Prep 输入算子协议
timeRange	Number	否	增量读取向前回溯的时间范围，单位由 Prep 输入算子配置解释
batchSize	Number	否	Prep 单批读取或写入的建议行数，必须大于等于 1
writeMode	writeMode	否	Prep 写入模式：full 为全量覆盖，incremental 为增量写入
scheduleConf	Object	是	Prep 调度配置。详情请参见下文 scheduleConf 表

scheduleConf

参数名	类型	是否必传	描述
scheduleType	Number	是	0 表示手动执行，1 表示定时执行
scheduleTimeType	Number	否	Prep 调度时间类型，当前固定为 0
scheduleFrequency	String	否	定时频率，当前支持 daily/monthly
scheduleTimeSettings	Array	否	daily 为 [HH:mm]，monthly 为 [日期, HH:mm]
dependencyNodes	Array	否	由 Verag 调用 Prep 获取，前端只能传空数组

sheet_config

参数名	类型	是否必传	描述
sheet_name	String	否	Excel sheet 名称
header_row_index	Number	否	表头所在行，从 1 开始
data_start_row_index	Number	否	数据起始行，从 1 开始

响应参数

参数名	类型	是否必传	描述
code	Number	是	响应码：0=成功，非0=失败
msg	String	否	Code非0时，返回错误信息
message	String	否	错误信息
data	Object	是	数据。详情请参见下文 data 表

data

参数名	类型	是否必传	描述
asset_id	String	是	执行导入的数据资产 ID
source_type	String	是	文件类型 EXCEL CSV CLICKHOUSE HIVE
task_ref	String	是	统一任务引用；local: 表示本地文件任务，prep:<asset_id> 表示 Prep 任务
status	String	是	状态 PENDING RUNNING SUCCEEDED PARTIAL_FAILED FAILED

最近更新时间：2026.09.11 14:59:46

这个页面对您有帮助吗？

有用

有用

无用

无用