MCP Tools Reference: dataform.googleapis.com

工具：create_workspace

在给定的 Dataform 代码库中创建新的开发工作区。

工作区是代码库的一个隔离的可修改结账。如果您需要跨多个文件编写或修改流水线代码，并在提交之前对其进行验证，请使用工作区。使用 write_file 和 remove_file 工具修改工作区中的文件，使用 commit_workspace_changes 工具记录结果，并使用 push_git_commits 工具将已提交的更改发布到代码库。

请勿使用 commit_repository_changes 工具进行标准流水线开发。该工具直接写入代码库，仅适用于笔记本或已保存的查询等单文件资源，并且在连接到远程 Git 主机的代码库上会失败。

前提条件：父代码库必须存在。

parent 参数值必须采用 projects/{project_id}/locations/{location}/repositories/{repository} 格式。

workspace_id 参数值是工作区要使用的 ID。

workspace 参数值用于保存要创建的工作区。

以下代码示例展示了如何使用 curl 调用 create_workspace 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_workspace",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

CreateWorkspace 请求消息。

CreateWorkspaceRequest

JSON 表示法 
{
  "parent": string,
  "workspace": {
    object (Workspace)
  },
  "workspaceId": string
}
字段
parent

string

必需。要在其中创建工作区的代码库。必须采用 projects/*/locations/*/repositories/* 格式。
workspace

object (Workspace)

必需。要创建的工作区。
workspaceId

string

必需。要用于工作区的 ID，该 ID 将成为工作区资源名称的最后一个组成部分。

工作区

JSON 表示法 
{
  "name": string,
  "createTime": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "depth": integer,

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

  // Union field _disable_moves can be only one of the following:
  "disableMoves": boolean
  // End of list of possible types for union field _disable_moves.

  // Union field _original_branch can be only one of the following:
  "originalBranch": string
  // End of list of possible types for union field _original_branch.

  // Union field _enable_branch_management can be only one of the following:
  "enableBranchManagement": boolean
  // End of list of possible types for union field _enable_branch_management.

  // Union field _shallow can be only one of the following:
  "shallow": boolean
  // End of list of possible types for union field _shallow.
}
字段
name

string

标识符。工作区的名称。
createTime

string (Timestamp format)

仅限输出。工作区的创建时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
dataEncryptionState

object (DataEncryptionState)

仅限输出。相应工作区受 KMS 密钥保护时，Git 代码库的数据加密状态。
privateResourceMetadata

object (PrivateResourceMetadata)

仅限输出。表示相应资源是否为用户级范围的元数据。对于 Workspace 资源，user_scoped 字段始终为 true。
depth

integer

可选。仅限输入。不可变。相应工作区要结账的 Git 代码库的最大深度。如果已定义且大于 0，则 Git 代码库将创建为具有给定深度的浅克隆；否则，将执行完整克隆。此字段仅适用于已启用分支管理的 GitHub、GitLab 和第一方代码库。

联合字段 _internal_metadata。

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

string

仅限输出。用于在内部提供资源的所有元数据信息。例如：时间戳、标志、状态字段等。此字段的格式为 JSON 字符串。

联合字段 _disable_moves。

_disable_moves 只能是下列其中一项：
disableMoves

boolean

可选。如果设置为 true，则在关联的代码库移动时，工作区不会随之移动。而是会被删除。

联合字段 _original_branch。

_original_branch 只能是下列其中一项：
originalBranch

string

可选。仅限输入。不可变。相应工作区中远程仓库内所有拉取/推送操作的默认上游分支的名称。如果为空，则使用代码库中的 HEAD 分支。

联合字段 _enable_branch_management。

_enable_branch_management 只能是下列其中一项：
enableBranchManagement

boolean

不可变。控制工作区的分支结账功能的启用状态。

如果设置为 True，则允许工作区检出分支。

联合字段 _shallow。

_shallow 只能是下列其中一项：
shallow

boolean

仅限输出。如果设置为 true，则工作区是作为浅克隆创建的。如果深度字段设置为大于 0 的值，则设置为 true，否则设置为 false。

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 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，则表示相应资源是用户级范围的，即属于工作区或源自工作区。

输出架构

表示 Dataform Git 工作区。

工作区

JSON 表示法 
{
  "name": string,
  "createTime": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "depth": integer,

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

  // Union field _disable_moves can be only one of the following:
  "disableMoves": boolean
  // End of list of possible types for union field _disable_moves.

  // Union field _original_branch can be only one of the following:
  "originalBranch": string
  // End of list of possible types for union field _original_branch.

  // Union field _enable_branch_management can be only one of the following:
  "enableBranchManagement": boolean
  // End of list of possible types for union field _enable_branch_management.

  // Union field _shallow can be only one of the following:
  "shallow": boolean
  // End of list of possible types for union field _shallow.
}
字段
name

string

标识符。工作区的名称。
createTime

string (Timestamp format)

仅限输出。工作区的创建时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
dataEncryptionState

object (DataEncryptionState)

仅限输出。相应工作区受 KMS 密钥保护时，Git 代码库的数据加密状态。
privateResourceMetadata

object (PrivateResourceMetadata)

仅限输出。表示相应资源是否为用户级范围的元数据。对于 Workspace 资源，user_scoped 字段始终为 true。
depth

integer

可选。仅限输入。不可变。相应工作区要结账的 Git 代码库的最大深度。如果已定义且大于 0，则 Git 代码库将创建为具有给定深度的浅克隆；否则，将执行完整克隆。此字段仅适用于已启用分支管理的 GitHub、GitLab 和第一方代码库。

联合字段 _internal_metadata。

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

string

仅限输出。用于在内部提供资源的所有元数据信息。例如：时间戳、标志、状态字段等。此字段的格式为 JSON 字符串。

联合字段 _disable_moves。

_disable_moves 只能是下列其中一项：
disableMoves

boolean

可选。如果设置为 true，则在关联的代码库移动时，工作区不会随之移动。而是会被删除。

联合字段 _original_branch。

_original_branch 只能是下列其中一项：
originalBranch

string

可选。仅限输入。不可变。相应工作区中远程仓库内所有拉取/推送操作的默认上游分支的名称。如果为空，则使用代码库中的 HEAD 分支。

联合字段 _enable_branch_management。

_enable_branch_management 只能是下列其中一项：
enableBranchManagement

boolean

不可变。控制工作区的分支结账功能的启用状态。

如果设置为 True，则允许工作区检出分支。

联合字段 _shallow。

_shallow 只能是下列其中一项：
shallow

boolean

仅限输出。如果设置为 true，则工作区是作为浅克隆创建的。如果深度字段设置为大于 0 的值，则设置为 true，否则设置为 false。

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 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，则表示相应资源是用户级范围的，即属于工作区或源自工作区。

工具注释

工具注释会发送给 MCP 客户端，用于描述指定工具的基本风险。大多数客户端会将这些提示视为不受信任的，但它们可用于确定何时向用户发送确认提示。

除了标题字符串之外，还定义了以下布尔值提示：

  • readOnlyHint：如果为 true，则工具不会修改其环境。默认值：false。
  • destructiveHint：如果为 true，则工具可以执行破坏性操作。如果为 false，则该工具只能执行添加操作。默认值：true。
  • idempotentHint：如果为 true，则使用相同实参重复调用该工具不会对其环境产生任何额外影响。默认值：false。
  • openWorldHint：如果为 true，则工具可以与外部实体的“开放世界”进行交互。如果为 false，则该工具只能与内部实体互动。例如，网络搜索工具是开放世界工具，而内存工具不是开放世界工具。

破坏性提示：❌ | 等幂性提示：❌ | 只读提示：❌ | 开放世界提示：❌