CreateSemanticJob - 创建语义任务 - 大数据开发治理平台 DataWorks

保存可复用的语义任务定义。若使用单文件来源，请先申请并完成附件上传；创建成功后用返回的 Name 调用 RunSemanticJob。

接口说明

使用场景

创建并保存一个可复用的语义任务定义。本接口只保存数据源、资源组和参考文件配置，不会立即执行任务。

注意事项

Name 在当前租户内唯一。单文件来源与其他来源的参考文件数量规则不同，具体以 ReferenceFileIds、ReferenceFileUris 字段说明为准。

调试

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

调试

授权信息

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

请求参数

名称	类型	必填	描述	示例值
Name	string	是	语义任务名称，也是后续 RunSemanticJob、DeleteSemanticJob、ListSemanticJobRuns 和 DownloadSemanticResults 的任务标识。名称须在当前租户内唯一。	semantic-job-demo
ProjectId	integer	否	DataWorks 工作空间 ID。除 Source.type=singleTableFile 外均应提供；创建结果的 Data.ProjectId 可复用于 GetSemanticJobDetail、GetSemanticJobLog 和 KillSemanticJob。	100
ResourceGroupId	string	是	运行语义任务使用的资源组标识。RunSemanticJob 不再传该参数，而是使用创建时保存的资源组。	rg-demo
Source	object	是	语义任务的输入数据源配置，必须传入 type；它用于选择待分析的数据，不是任务产出的 semantic_model YAML。domain 为字符串，用于标识本次任务关注的业务域及关注点，例如 sales。支持：1）maxcompute：通过 pinnedScopeInfo 指定范围；数组元素包含 type、name，type=project 时 name 为 MaxCompute 项目名，type=schema 时 project 为项目名、name 为 Schema 名，表级范围时 project 为项目名、schema 可选、name 为表名。2）holo 或 starrocks：除 type 外还需传 dataSourceName、dataSourceEnv，并在请求顶层传入 ProjectId；可用 pinnedScopeInfo 限定 schema 或表范围，元素的 name 为 schema 或表名，表级范围的 schema 为所在库或 Schema。3）singleTableFile：无需 ProjectId，文件引用规则见 ReferenceFileIds 和 ReferenceFileUris。任务成功运行后，请通过 DownloadSemanticResults 获取 semantic_model YAML 等结果文件。示例为 MaxCompute 项目范围。	{"type":"maxcompute","domain":"sales","pinnedScopeInfo":[{"type":"project","name":"mc_project"}]}
ReferenceFileIds	array	否	已上传参考文件 ID 列表。Source.type=singleTableFile 时，与 ReferenceFileUris 二选一，且所选数组必须恰有一个非空元素；该 ID 应来自 UploadSemanticFile 的 Data.FileId，并且文件仅支持 CSV 或 XLSX。其他 Source.type 可传入多个 ID；服务会在创建时校验每个 ID，且可同时传入 ReferenceFileUris。
	string	否	可选的已上传参考文件 ID 列表。	semantic-job-value
ReferenceFileUris	array	否	调用方可访问的参考文件 URI 列表。Source.type=singleTableFile 时，与 ReferenceFileIds 二选一，且所选数组必须恰有一个非空 URI。其他 Source.type 可传入多个 URI，且可同时传入 ReferenceFileIds。使用 UploadSemanticFile 的上传路径时，应在 PUT 上传完成后传其 Data.FileId，而非短期有效的 UploadUrl。
	string	否	可选的可访问参考文件 URI 列表。	semantic-job-value

请根据各请求字段的说明构造调用参数。

返回参数

名称	类型	描述	示例值
	object	创建语义任务的标准响应。Data 为已保存的任务定义，后续调用通过其中的 Name、ProjectId 和参考文件信息衔接。
RequestId	string	请求 ID。用于定位日志和排查问题。	676271D6-53B4-57BE-89FA-72F7AE1418DF
Success	boolean	请求是否成功
Data	object	已保存的语义任务定义。使用 Data.Name 调用 RunSemanticJob、DeleteSemanticJob、ListSemanticJobRuns 和 DownloadSemanticResults。
Id	integer	任务定义的内部唯一 ID，用于标识本次创建的任务。	1
Name	string	已保存的任务名称；后续运行、删除、查询运行记录和下载结果均使用该值。	semantic-job-demo
UserId	string	创建该任务的用户标识。	user-demo
Creator	string	任务创建者标识，等同于 UserId，用于展示创建归属。	user-demo
ProjectId	integer	任务所属 DataWorks 工作空间 ID；用于 GetSemanticJobDetail、GetSemanticJobLog 和 KillSemanticJob 的 ProjectId。	100
Type	string	已保存的 Source.type 数据源类型，用于快速识别任务输入类型。	maxcompute
Source	object	已保存的输入数据源配置，与创建请求中的 Source 对应；运行时据此选择待分析的数据范围。
ReferenceFileIds	array	已关联的上传文件 ID 列表；singleTableFile 运行时读取其中的唯一文件。
	string	由 UploadSemanticFile 返回并完成 PUT 上传后的 FileId。	FID1
ReferenceFileUris	array	已关联的外部参考文件 URI 列表；singleTableFile 运行时读取其中的唯一文件。
	string	调用方提供的可访问参考文件 URI。	https://example.com/reference.pdf
GmtCreate	integer	任务定义创建时间，单位为毫秒的 Unix 时间戳。	1700000000000
GmtModified	integer	任务定义最近修改时间，单位为毫秒的 Unix 时间戳。	1700000000000
ResourceGroupId	string	运行本任务时将使用的资源组标识。	rg-demo

响应字段含义和后续调用关系请参阅各字段说明。

示例

正常返回示例

JSON格式

{
  "RequestId": "676271D6-53B4-57BE-89FA-72F7AE1418DF",
  "Success": true,
  "Data": {
    "Id": 1,
    "Name": "semantic-job-demo",
    "UserId": "user-demo",
    "Creator": "user-demo",
    "ProjectId": 100,
    "Type": "maxcompute",
    "Source": {
      "test": "test",
      "test2": 1
    },
    "ReferenceFileIds": [
      "FID1"
    ],
    "ReferenceFileUris": [
      "https://example.com/reference.pdf"
    ],
    "GmtCreate": 1700000000000,
    "GmtModified": 1700000000000,
    "ResourceGroupId": "rg-demo"
  }
}

错误码

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

变更历史

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

大数据开发治理平台 DataWorks：CreateSemanticJob - 创建语义任务