CreateKnowledgeBaseBuildTask - 创建知识库构建任务-大数据开发治理平台 DataWorks(DataWorks)-阿里云帮助中心

创建可重复运行的知识构建任务，配置输入范围、触发方式及运行资源。

接口说明

创建知识库构建任务。租户及调用者身份由 POP 认证上下文确定。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

当前API暂无授权信息透出。

请求参数

名称	类型	必填	描述	示例值
KnowledgeBaseId	string	是	任务所属知识库	12345678-1234-4234-8234-123456789abc
Name	string	是	任务名称	项目空间知识构建
Description	string	否	任务描述，最多 1024 个字符；省略时不设置	销售指标与制度文档
ProjectId	integer	是	运行工作空间 ID	67890
Input	object	是	按 Type 选择项目、实体、来源或文件
ProjectIds	array	否	工作空间范围构建选择的 DataWorks 工作空间 ID；非空、去重
	integer	否	工作空间范围构建选择的 DataWorks 工作空间 ID；非空、去重	12345
SourceIds	array	否	本库已登记来源的 ID，去重；是否必填及允许的来源类型由任务输入场景决定，见下表
	string	否	本库已登记来源的 ID，去重；是否必填及允许的来源类型由任务输入场景决定，见下表	src-document-001
Entities	array<object>	否	数据资产范围构建选择的数据库、Schema、表等数据地图实体；非空、去重
	object	否
EntityId	string	否	数据地图返回的元数据实体 ID；客户端原样传递，不自行拼接数据库、Schema 或表标识	maxcompute-table:::project_name:schema_name:table_name
EntityType	string	否	实体层级，如 DATABASE、SCHEMA、TABLE；服务端以数据地图身份校验，不因枚举存在就承诺所有引擎均支持	TABLE
YamlUploadId	string	否	SEMANTIC_MODEL 导入任务使用的本库 YAML 上传会话 ID；创建任务时绑定，不能混用其他输入范围。	upload-yaml-001
KnowledgeObjectIds	array	否	从本库文档对象构建时必填、非空且去重；每项为本库 Type=DOCUMENT 的 KnowledgeObjectId；与外部连接器同步范围 SourceIds 不混用
	string	否	从本库文档对象构建时必填、非空且去重；每项为本库 Type=DOCUMENT 的 KnowledgeObjectId；与外部连接器同步范围 SourceIds 不混用	obj-document-001
Trigger	object	否	手动或周期配置
Mode	string	否	MANUAL 或 PERIODIC；手动任务不自动创建实例	MANUAL
Cron	string	否	仅 PERIODIC 提供；DataWorks 调度 Cron 表达式	0 0 2 * * ?
Enabled	boolean	否	仅 PERIODIC 提供；控制周期自动触发的启停，不是实例状态
RuntimeResource	object	是	资源组与 Builder CU
ResourceGroupId	string	否	真实 Builder 节点使用的 DataWorks 资源组 ID；服务端校验其在任务顶层 ProjectId 对应工作空间内可用	rg-001
Cu	integer	否	Builder 计算规格，取值 4～16；创建省略时有效值为 4，读取返回有效值	4
LlmModel	string	否	具体模型 ID 或 AUTO	model-001
ContentLocale	string	否	内容语言	zh-CN
Type	string	是	已开放的构建类型枚举值： PROJECT_SPACE_BUILD SEMANTIC_GRAPH SEMANTIC_MODEL DOCUMENT_GRAPH DOCUMENT_SYNC DOCUMENT_SYNC_AND_GRAPH	PROJECT_SPACE_BUILD
ClientToken	string	否	创建幂等键	task-create-001

返回参数

名称	类型	描述	示例值
	object	Schema of Response
RequestId	string	本次请求的唯一标识，可用于定位问题。	00000000-0000-4000-8000-000000000001
Success	boolean	请求是否成功
Data	object	成功时返回的业务数据。
TaskId	string	稳定任务 ID	10001
KnowledgeBaseId	string	所属知识库	12345678-1234-4234-8234-123456789abc
Name	string	任务名称	项目空间知识构建
Description	string	任务描述，可选	销售指标与制度文档
Type	string	任务类型：PROJECT_SPACE_BUILD、SEMANTIC_GRAPH、DOCUMENT_GRAPH、DOCUMENT_SYNC、DOCUMENT_SYNC_AND_GRAPH、SEMANTIC_MODEL；SEMANTIC_MODEL 仅用于 YAML 导入。	PROJECT_SPACE_BUILD
LlmModel	string	需要模型的任务可配置具体模型 ID 或 AUTO；创建时省略等价于 AUTO，不调用模型的任务不配置	model-001
ContentLocale	string	本任务内容语言，可选；由任务创建时明确选择	zh-CN
ProjectId	integer	任务运行所在的 DataWorks 工作空间 ID；不同于 Input.ProjectIds 指定的构建资产范围。	67890
Input	object	按任务 Type 指定的输入范围。
ProjectIds	array	工作空间范围构建选择的 DataWorks 工作空间 ID；非空、去重
	integer	工作空间范围构建选择的 DataWorks 工作空间 ID；非空、去重	12345
SourceIds	array	本库已登记来源的 ID，去重；是否必填及允许的来源类型由任务输入场景决定，见下表
	string	本库已登记来源的 ID，去重；是否必填及允许的来源类型由任务输入场景决定，见下表	src-document-001
Entities	array<object>	数据资产范围构建选择的数据库、Schema、表等数据地图实体；非空、去重
	object
EntityId	string	数据地图返回的元数据实体 ID；客户端原样传递，不自行拼接数据库、Schema 或表标识	maxcompute-table:::project_name:schema_name:table_name
EntityType	string	实体层级，如 DATABASE、SCHEMA、TABLE；服务端以数据地图身份校验，不因枚举存在就承诺所有引擎均支持	TABLE
YamlUploadId	string	SEMANTIC_MODEL 导入任务使用的本库 YAML 上传会话 ID；创建任务时绑定，不能混用其他输入范围。	upload-yaml-001
KnowledgeObjectIds	array	从本库文档对象构建时必填、非空且去重；每项为本库 Type=DOCUMENT 的 KnowledgeObjectId；与外部连接器同步范围 SourceIds 不混用
	string	从本库文档对象构建时必填、非空且去重；每项为本库 Type=DOCUMENT 的 KnowledgeObjectId；与外部连接器同步范围 SourceIds 不混用	obj-document-001
RuntimeResource	object	任务运行资源组及 Builder 计算规格。
ResourceGroupId	string	真实 Builder 节点使用的 DataWorks 资源组 ID；服务端校验其在任务顶层 ProjectId 对应工作空间内可用	rg-001
Cu	integer	Builder 计算规格，取值 4～16；创建省略时有效值为 4，读取返回有效值	4
Trigger	object	手动或周期触发配置。
Mode	string	MANUAL 或 PERIODIC；手动任务不自动创建实例	MANUAL
Cron	string	仅 PERIODIC 提供；DataWorks 调度 Cron 表达式	0 0 2 * * ?
Enabled	boolean	仅 PERIODIC 提供；控制周期自动触发的启停，不是实例状态
CreateTime	integer	创建时间	1790200000000
ModifyTime	integer	最近定义修改时间	1790200300000
Code	string	业务错误码；请求失败时用于判断错误类型。	InvalidParameter
Message	string	请求失败时的安全错误信息。	请求参数不合法。

示例

正常返回示例

JSON格式

{
  "RequestId": "00000000-0000-4000-8000-000000000001",
  "Success": true,
  "Data": {
    "TaskId": "10001",
    "KnowledgeBaseId": "12345678-1234-4234-8234-123456789abc",
    "Name": "项目空间知识构建",
    "Description": "销售指标与制度文档",
    "Type": "PROJECT_SPACE_BUILD",
    "LlmModel": "model-001",
    "ContentLocale": "zh-CN",
    "ProjectId": 67890,
    "Input": {
      "ProjectIds": [
        12345
      ],
      "SourceIds": [
        "src-document-001"
      ],
      "Entities": [
        {
          "EntityId": "maxcompute-table:::project_name:schema_name:table_name",
          "EntityType": "TABLE"
        }
      ],
      "YamlUploadId": "upload-yaml-001",
      "KnowledgeObjectIds": [
        "obj-document-001"
      ]
    },
    "RuntimeResource": {
      "ResourceGroupId": "rg-001",
      "Cu": 4
    },
    "Trigger": {
      "Mode": "MANUAL",
      "Cron": "0 0 2 * * ?",
      "Enabled": true
    },
    "CreateTime": 1790200000000,
    "ModifyTime": 1790200300000
  },
  "Code": "InvalidParameter",
  "Message": "请求参数不合法。"
}

错误码

HTTP status code	错误码	错误信息
400	InvalidParameter	The request parameters are invalid.
403	Forbidden	Creating a knowledge base build task requires knowledge base management permission. For PROJECT_SPACE_BUILD, the project administrator role (role_project_admin) is also required for every project in Input.ProjectIds.
403	DataAgentUnavailable	DataAgent is unavailable; check the product edition and usage quota
403	DataAgentNotActivated	Activate DataAgent pay-as-you-go before configuring or starting a knowledge base build
404	ResourceNotFound	The requested resource does not exist or is not visible.
503	ServiceUnavailable	The service is temporarily unavailable.
409	Conflict	The resource state conflicts with this operation.

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。