MCP Tools Reference: dataform.googleapis.com

工具：create_workflow_invocation

在指定的 Dataform 存放區中，建立新的工作流程叫用。

parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。

compilation_result 或 workflow_config 參數值為必填項。

  • 如果使用 compilation_result，參數值必須採用 projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result} 格式。
  • 如果使用 workflow_config，參數值必須採用 projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config} 格式。

先決條件：如要觸發叫用，請先使用 create_compilation_result 工具建立 compilation_result，或使用 create_workflow_config 工具建立 workflow_config。您無法直接從原始存放區程式碼觸發叫用。

工作流程呼叫會以服務帳戶執行，該帳戶取決於編譯來源：

  • 如果使用 compilation_result，請設定 invocationConfig.serviceAccount 參數值。如果省略這個值，系統會使用存放區的預設 service_account。
  • 如果使用 workflow_config，請勿設定 invocationConfig 參數。系統會自動以該工作流程設定中設定的服務帳戶執行呼叫。

服務帳戶不得為預設的 Dataform 服務代理程式。服務帳戶必須具備執行工作流程的必要權限，且使用者必須獲得授權，才能以所選服務帳戶的身分執行作業。這項授權通常是透過「服務帳戶使用者」角色 (roles/iam.serviceAccountUser) 授予，可授予服務帳戶本身或包含該帳戶的專案。

下列程式碼範例說明如何使用 curl 呼叫 create_workflow_invocation MCP 工具。

Curl 要求 
curl --location 'https://dataform.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "create_workflow_invocation",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

CreateWorkflowInvocation 要求訊息。

CreateWorkflowInvocationRequest

JSON 表示法 
{
  "parent": string,
  "workflowInvocation": {
    object (WorkflowInvocation)
  }
}
欄位
parent

string

這是必要旗標，要建立工作流程調用的存放區。格式必須為 projects/*/locations/*/repositories/*。
workflowInvocation

object (WorkflowInvocation)

這是必要旗標，要建立的工作流程叫用資源。

WorkflowInvocation

JSON 表示法 
{
  "name": string,
  "invocationConfig": {
    object (InvocationConfig)
  },
  "state": enum (State),
  "invocationTiming": {
    object (Interval)
  },
  "resolvedCompilationResult": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "pipelineConfig": {
    object (PipelineConfig)
  },

  // Union field compilation_source can be only one of the following:
  "compilationResult": string,
  "workflowConfig": string
  // End of list of possible types for union field compilation_source.

  // Union field _internal_metadata can be only one of the following:
  "internalMetadata": string
  // End of list of possible types for union field _internal_metadata.
}
欄位
name

string

僅供輸出。工作流程調用名稱。
invocationConfig

object (InvocationConfig)

不可變動。如未設定，系統會使用預設的 InvocationConfig。
state

enum (State)

僅供輸出。這個工作流程調用的目前狀態。
invocationTiming

object (Interval)

僅供輸出。這項工作流程調用的時間詳細資料。
resolvedCompilationResult

string

僅供輸出。用來建立這項調用的已解析編譯結果。格式為 projects/*/locations/*/repositories/*/compilationResults/*。
dataEncryptionState

object (DataEncryptionState)

僅供輸出。只有在存放區有 KMS 金鑰時才設定。
privateResourceMetadata

object (PrivateResourceMetadata)

僅供輸出。中繼資料，指出這項資源是否為以使用者為範圍。WorkflowInvocation 資源「僅限user_scoped來自彙整結果，且彙整結果屬於以使用者為範圍。
pipelineConfig

object (PipelineConfig)

僅供輸出。管道選項，用於定義管道類型和 Git 存放區中的路徑。
聯集欄位 compilation_source。要用於這次叫用的編譯結果來源。compilation_source 只能是下列其中一個設定：
compilationResult

string

不可變動。要用於這個叫用的編譯結果名稱。格式必須為 projects/*/locations/*/repositories/*/compilationResults/*。
workflowConfig

string

不可變動。要叫用的工作流程設定名稱。格式必須為 projects/*/locations/*/repositories/*/workflowConfigs/*。

聯集欄位 _internal_metadata。

_internal_metadata 只能是下列其中一項：
internalMetadata

string

僅供輸出。所有在內部用於提供資源的中繼資料資訊。例如時間戳記、旗標、狀態欄位等。這個欄位的格式為 JSON 字串。

InvocationConfig

JSON 表示法 
{
  "includedTargets": [
    {
      object (Target)
    }
  ],
  "includedTags": [
    string
  ],
  "transitiveDependenciesIncluded": boolean,
  "transitiveDependentsIncluded": boolean,
  "fullyRefreshIncrementalTablesEnabled": boolean,
  "serviceAccount": string,

  // Union field _query_priority can be only one of the following:
  "queryPriority": enum (QueryPriority)
  // End of list of possible types for union field _query_priority.
}
欄位
includedTargets[]

object (Target)

選用。要納入的動作 ID 集。
includedTags[]

string

選用。要納入的標記集。
transitiveDependenciesIncluded

boolean

選用。如果設為 true，系統會執行所含動作的轉換依附元件。
transitiveDependentsIncluded

boolean

選用。如果設為 true，系統會執行所含動作的轉換附屬元件。
fullyRefreshIncrementalTablesEnabled

boolean

選用。如果設為 true，系統會全面重新整理所有累加型資料表。
serviceAccount

string

選用。用來執行工作流程調用的服務帳戶。

聯集欄位 _query_priority。

_query_priority 只能是下列其中一項：
queryPriority

enum (QueryPriority)

選用。指定在 BigQuery 中執行查詢的優先順序。詳情請參閱 https://cloud.google.com/bigquery/docs/running-queries#queries。

目標

JSON 表示法 
{
  "database": string,
  "schema": string,
  "name": string
}
欄位
database

string

選用。動作的資料庫 (Google Cloud 專案 ID)。
schema

string

選用。database 中的動作結構定義 (BigQuery 資料集 ID)。
name

string

選用。動作名稱，位於 database 和 schema 內。

時間間隔

JSON 表示法 
{
  "startTime": string,
  "endTime": string
}
欄位
startTime

string (Timestamp format)

選用。間隔的開始時間 (含)。

如果指定了這個值，符合此間隔的時間戳記必須等於或晚於開始時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

選用。間隔的結束時間 (不含)。

如果指定，符合這個間隔的時間戳記必須早於結束時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

時間戳記

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
欄位
seconds

string (int64 format)

代表自 Unix 紀元 1970-01-01T00:00:00Z 起算的世界標準時間秒數。必須介於 -62135596800 和 253402300799 之間 (含)，對應至 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59Z。
nanos

integer

以奈秒為單位的非負秒數小數。這個欄位是時間長度的奈秒部分，並非秒數的替代值。如果秒數值為負數，且包含小數，奈秒值仍須為非負數，且會往前計算時間。必須介於 0 至 999,999,999 之間 (含)。

DataEncryptionState

JSON 表示法 
{
  "kmsKeyVersionName": string
}
欄位
kmsKeyVersionName

string

這是必要旗標，用於加密資源資料的 KMS 金鑰版本名稱。

PrivateResourceMetadata

JSON 表示法 
{
  "userScoped": boolean
}
欄位
userScoped

boolean

僅供輸出。如果是 true，這個資源就是以使用者為範圍，也就是工作區或來自工作區。

PipelineConfig

JSON 表示法 
{
  "pipelineType": enum (PipelineType),
  "path": string
}
欄位
pipelineType

enum (PipelineType)

這是必要旗標，管道類型。
path

string

這是必要旗標，定義管道的 Git 存放區相對路徑。舉例來說，如果是 Dataform 管道，這是 workflow_settings.yaml 或 dataform.json 所在資料夾的路徑。

QueryPriority

BigQuery 查詢執行優先順序類型。

列舉
QUERY_PRIORITY_UNSPECIFIED 預設值。這個值不會使用。
INTERACTIVE 系統會在 BigQuery 中執行查詢，優先順序為互動式。詳情請參閱 https://cloud.google.com/bigquery/docs/running-queries#queries。
BATCH 系統會以批次優先順序在 BigQuery 中執行查詢。詳情請參閱 https://cloud.google.com/bigquery/docs/running-queries#batchqueries。

狀態

代表工作流程調用的目前狀態。

列舉
STATE_UNSPECIFIED 預設值。這個值不會使用。
RUNNING 工作流程叫用目前正在執行中。
SUCCEEDED 工作流程叫用成功。終端狀態。
CANCELLED 已取消工作流程叫用作業。終端狀態。
FAILED 工作流程叫用失敗。終端狀態。
CANCELING 工作流程叫用作業正在取消，但部分動作仍在執行。

PipelineType

管道類型。日後可能會延長。如果是 UNSPECIFIED，系統會擲回錯誤。

列舉
PIPELINE_TYPE_UNSPECIFIED 預設值。這個值不會使用。
DATAFORM 一般的 Dataform 管道。
SQL SQL 單一檔案資產。
NOTEBOOK 筆記本單一檔案資產。

輸出內容的結構定義

代表單一編譯結果的叫用。

WorkflowInvocation

JSON 表示法 
{
  "name": string,
  "invocationConfig": {
    object (InvocationConfig)
  },
  "state": enum (State),
  "invocationTiming": {
    object (Interval)
  },
  "resolvedCompilationResult": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "pipelineConfig": {
    object (PipelineConfig)
  },

  // Union field compilation_source can be only one of the following:
  "compilationResult": string,
  "workflowConfig": string
  // End of list of possible types for union field compilation_source.

  // Union field _internal_metadata can be only one of the following:
  "internalMetadata": string
  // End of list of possible types for union field _internal_metadata.
}
欄位
name

string

僅供輸出。工作流程調用名稱。
invocationConfig

object (InvocationConfig)

不可變動。如未設定，系統會使用預設的 InvocationConfig。
state

enum (State)

僅供輸出。這個工作流程調用的目前狀態。
invocationTiming

object (Interval)

僅供輸出。這項工作流程調用的時間詳細資料。
resolvedCompilationResult

string

僅供輸出。用來建立這項調用的已解析編譯結果。格式為 projects/*/locations/*/repositories/*/compilationResults/*。
dataEncryptionState

object (DataEncryptionState)

僅供輸出。只有在存放區有 KMS 金鑰時才設定。
privateResourceMetadata

object (PrivateResourceMetadata)

僅供輸出。中繼資料，指出這項資源是否為以使用者為範圍。WorkflowInvocation 資源「僅限user_scoped來自彙整結果，且彙整結果屬於以使用者為範圍。
pipelineConfig

object (PipelineConfig)

僅供輸出。管道選項，用於定義管道類型和 Git 存放區中的路徑。
聯集欄位 compilation_source。要用於這次叫用的編譯結果來源。compilation_source 只能是下列其中一個設定：
compilationResult

string

不可變動。要用於這個叫用的編譯結果名稱。格式必須為 projects/*/locations/*/repositories/*/compilationResults/*。
workflowConfig

string

不可變動。要叫用的工作流程設定名稱。格式必須為 projects/*/locations/*/repositories/*/workflowConfigs/*。

聯集欄位 _internal_metadata。

_internal_metadata 只能是下列其中一項：
internalMetadata

string

僅供輸出。所有在內部用於提供資源的中繼資料資訊。例如時間戳記、旗標、狀態欄位等。這個欄位的格式為 JSON 字串。

InvocationConfig

JSON 表示法 
{
  "includedTargets": [
    {
      object (Target)
    }
  ],
  "includedTags": [
    string
  ],
  "transitiveDependenciesIncluded": boolean,
  "transitiveDependentsIncluded": boolean,
  "fullyRefreshIncrementalTablesEnabled": boolean,
  "serviceAccount": string,

  // Union field _query_priority can be only one of the following:
  "queryPriority": enum (QueryPriority)
  // End of list of possible types for union field _query_priority.
}
欄位
includedTargets[]

object (Target)

選用。要納入的動作 ID 集。
includedTags[]

string

選用。要納入的標記集。
transitiveDependenciesIncluded

boolean

選用。如果設為 true，系統會執行所含動作的轉換依附元件。
transitiveDependentsIncluded

boolean

選用。如果設為 true，系統會執行所含動作的轉換附屬元件。
fullyRefreshIncrementalTablesEnabled

boolean

選用。如果設為 true，系統會全面重新整理所有累加型資料表。
serviceAccount

string

選用。用來執行工作流程調用的服務帳戶。

聯集欄位 _query_priority。

_query_priority 只能是下列其中一項：
queryPriority

enum (QueryPriority)

選用。指定在 BigQuery 中執行查詢的優先順序。詳情請參閱 https://cloud.google.com/bigquery/docs/running-queries#queries。

目標

JSON 表示法 
{
  "database": string,
  "schema": string,
  "name": string
}
欄位
database

string

選用。動作的資料庫 (Google Cloud 專案 ID)。
schema

string

選用。database 中的動作結構定義 (BigQuery 資料集 ID)。
name

string

選用。動作名稱，位於 database 和 schema 內。

時間間隔

JSON 表示法 
{
  "startTime": string,
  "endTime": string
}
欄位
startTime

string (Timestamp format)

選用。間隔的開始時間 (含)。

如果指定了這個值，符合此間隔的時間戳記必須等於或晚於開始時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

選用。間隔的結束時間 (不含)。

如果指定，符合這個間隔的時間戳記必須早於結束時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

時間戳記

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
欄位
seconds

string (int64 format)

代表自 Unix 紀元 1970-01-01T00:00:00Z 起算的世界標準時間秒數。必須介於 -62135596800 和 253402300799 之間 (含)，對應至 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59Z。
nanos

integer

以奈秒為單位的非負秒數小數。這個欄位是時間長度的奈秒部分，並非秒數的替代值。如果秒數值為負數，且包含小數，奈秒值仍須為非負數，且會往前計算時間。必須介於 0 至 999,999,999 之間 (含)。

DataEncryptionState

JSON 表示法 
{
  "kmsKeyVersionName": string
}
欄位
kmsKeyVersionName

string

這是必要旗標，用於加密資源資料的 KMS 金鑰版本名稱。

PrivateResourceMetadata

JSON 表示法 
{
  "userScoped": boolean
}
欄位
userScoped

boolean

僅供輸出。如果是 true，這個資源就是以使用者為範圍，也就是工作區或來自工作區。

PipelineConfig

JSON 表示法 
{
  "pipelineType": enum (PipelineType),
  "path": string
}
欄位
pipelineType

enum (PipelineType)

這是必要旗標，管道類型。
path

string

這是必要旗標，定義管道的 Git 存放區相對路徑。舉例來說，如果是 Dataform 管道，這是 workflow_settings.yaml 或 dataform.json 所在資料夾的路徑。

QueryPriority

BigQuery 查詢執行優先順序類型。

列舉
QUERY_PRIORITY_UNSPECIFIED 預設值。這個值不會使用。
INTERACTIVE 系統會在 BigQuery 中執行查詢，優先順序為互動式。詳情請參閱 https://cloud.google.com/bigquery/docs/running-queries#queries。
BATCH 系統會以批次優先順序在 BigQuery 中執行查詢。詳情請參閱 https://cloud.google.com/bigquery/docs/running-queries#batchqueries。

狀態

代表工作流程調用的目前狀態。

列舉
STATE_UNSPECIFIED 預設值。這個值不會使用。
RUNNING 工作流程叫用目前正在執行中。
SUCCEEDED 工作流程叫用成功。終端狀態。
CANCELLED 已取消工作流程叫用作業。終端狀態。
FAILED 工作流程叫用失敗。終端狀態。
CANCELING 工作流程叫用作業正在取消，但部分動作仍在執行。

PipelineType

管道類型。日後可能會延長。如果是 UNSPECIFIED，系統會擲回錯誤。

列舉
PIPELINE_TYPE_UNSPECIFIED 預設值。這個值不會使用。
DATAFORM 一般的 Dataform 管道。
SQL SQL 單一檔案資產。
NOTEBOOK 筆記本單一檔案資產。

工具註解

工具註解會傳送至 MCP 用戶端，說明特定工具的基本風險。大多數用戶端會將這些提示視為不受信任，但可用於決定何時向使用者傳送確認提示。

除了標題字串外，以下布林提示的定義如下：

  • readOnlyHint：如果為 true，工具不會修改環境。預設值：false。
  • destructiveHint：如果為 true，工具可以執行破壞性動作。如果為 false，工具只能執行加法動作。預設值：true。
  • idempotentHint：如果為 true，以相同引數重複呼叫工具，對環境不會有額外影響。預設值：false。
  • openWorldHint：設為 true 時，工具可以與外部實體的「開放世界」互動。如果為 false，工具只能與內部實體互動。舉例來說，網頁搜尋工具屬於開放世界，記憶體工具則不屬於開放世界。

破壞性提示：❌ | 等冪提示：❌ | 唯讀提示：❌ | 開放世界提示：❌