CreateSemanticJob - DataWorks

儲存可重複使用的語義任務定義。若使用單一檔案來源，請先申請並完成附件上傳；建立成功後使用回傳的 Name 呼叫 RunSemanticJob。

介面說明

使用情境

建立並儲存一個可重複使用的語義任務定義。本介面僅儲存資料來源、資源群組和參考檔案設定，不會立即執行任務。

建議流程

當 Source.type=singleTableFile 時，先呼叫 UploadSemanticFile，使用回傳的 Data.UploadUrl 完成 PUT 上傳，再將 Data.FileId 填入 ReferenceFileIds；也可以提供單一可存取 URI。
設定 Source、ProjectId 和 ResourceGroupId，呼叫本介面儲存任務。
使用回應中的 Data.Name 呼叫 RunSemanticJob；任務完成後使用 DownloadSemanticResults 取得產出結果。

注意事項

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": false,
  "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"
  }
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。