在替代变量中使用载荷绑定和 bash 参数扩展

本页介绍了如何使用载荷绑定，以及如何将 bash 参数扩展应用于与构建触发器关联的替代变量。如果您不熟悉如何在构建配置中使用替代变量，请参阅替换变量值。

Cloud Build 可让您将触发器的事件载荷的一部分存储为替代变量。事件载荷是调用触发器的事件的正文。与载荷关联的变量称为绑定，可用于由推送和拉取事件调用的构建。通过绑定，您可以访问与构建相关的其他数据，例如与源代码关联的语言以及拉取请求的作者。

此外，Cloud Build 还可让用户将 bash 参数扩展应用于替代变量值。Bash 参数扩展允许您处理与现有变量关联的字符串。您可以通过使用大写字母或替换子字符串来处理字符串。

在 Google Cloud 控制台和 Cloud Build 配置文件中定义或更新构建触发器时，您可以使用载荷绑定并应用 bash 参数扩展。此外，您可以在运行手动构建时应用 bash 参数扩展。

载荷绑定

您可以将触发器的事件载荷的一部分存储为替代变量值。载荷绑定可用作推送和拉取事件调用的构建的变量值，如果您的源代码位于 GitHub 代码库或 Cloud Source Repositories 中，则可以使用载荷绑定来访问 JSON 载荷。如需详细了解 GitHub 事件载荷，请参阅 Webhook 事件载荷。如需详细了解 Cloud Source Repositories 的事件载荷，请参阅 Cloud Source Repositories 通知。

您可以使用指定的前缀来访问来自事件载荷的信息，该前缀表示事件载荷的根。从前缀开始，您可以使用 JSONPath 语法访问载荷并从中拉取数据。根据您的事件类型，可用的载荷前缀如下：

前缀	源	说明
`push`	GitHub	可让您访问推送事件的 JSON 载荷中的字段
`pull_request`	GitHub	可让您访问拉取请求事件的 JSON 载荷中的字段
`issue_comment`	GitHub	可让您访问与拉取请求关联的问题评论事件的 JSON 载荷中的字段
`csr`	Cloud Source Repositories	可让您访问推送事件的 JSON 载荷中的字段

对于与 GitHub 应用关联的任何事件，还可以使用内置变量值 is_collaborator 和 perm_level。系统会通过变量值 push.pusher.name、pull_request.pull_request.user.login 和 issue_comment.comment.user.login 检查推送和拉取事件的用户状态。下表显示了当源代码位于 GitHub 中时如何将下列值添加为触发器的变量值：

变量名称	变量值	变量说明
`_PERM_LEVEL`	`$(perm_level)`	获取用户的权限级别
`_IS_COLLABORATOR`	`$(is_collaborator)`	如果用户是协作者，则输出 `true`

您可以将变量值 is_collaborator 和 perm_level 用于推送事件、拉取请求事件以及受控于评论的拉取请求事件。您不需要这些变量值前面添加前缀。

创建使用载荷绑定的替代变量

如需创建使用载荷绑定的替代变量，请执行以下操作：

打开触发器页面。
如果尚未创建构建触发器，请点击创建触发器。否则，请选择现有的触发器。
在替代变量下，点击添加变量。
按照以下所述惯例为变量添加一个名称：
- 替代变量必须以下划线 (_) 开头，并且只能使用大写字母和数字（遵循正则表达式格式 [A-Z0-9_]+）。这样做可以防止与内置替代变量产生冲突。
- 参数数量的上限为 100 个。参数键的长度上限为 100 个字节，参数值的长度上限为 4000 个字节。
如需详细了解如何定义和使用用户定义的替代变量，请参阅使用用户定义的替代变量。

使用受支持的前缀为变量添加值。

如果您的源代码位于 GitHub 中，您可以使用载荷绑定在替代变量中引用事件载荷中的信息。如需访问推送事件的 JSON 载荷，请使用前缀 push 或 body。在以下示例中，变量值中的 push 前缀用作入口点，以访问 build 的 JSON 载荷中的信息：

变量名称	变量值	变量说明
`_PUSH_NAME`	`$(push.repository.name)`	获取与推送事件关联的代码库的名称
`_COMMITS`	`$(push.commits)`	获取描述每个推送提交的提交对象数组
`_OWNER`	`$(push.repository.owner.name)`	获取代码库所有者的名称
`_URL`	`$(push.repository.html_url)`	获取 GitHub 代码库的网址
`_LANGUAGE`	`$(push.repository.language)`	获取推送中包含的源代码语言

如需查看您可以使用 push 前缀访问的字段列表，请参阅 PushEvent。

如需访问拉取请求事件的 JSON 载荷，请使用前缀 pull_request 或 body。在以下示例中，变量值中的 pull_request 前缀用作入口点来访问构建的 JSON 载荷中的信息：

变量名称	变量值	变量说明
`_PULL_REQUEST_ID`	`$(pull_request.pull_request.id)`	获取拉取请求的 ID
`_PULL_REQUEST_TITLE`	`$(pull_request.pull_request.title)`	获取拉取请求的标题
`_PULL_REQUEST_BODY`	`$(pull_request.pull_request.body)`	获取拉取请求的正文
`_USERNAME`	`$(pull_request.pull_request.user.login)`	获取拉取请求的发送者的用户名
`_MERGE_TIME`	`$(pull_request.pull_request.merged_at)`	获取拉取请求的合并时间

如需查看您可以使用 pull_request 前缀访问的字段列表，请参阅 PullRequestEvent。

如需访问提交事件的 JSON 载荷，请使用前缀 commit。在以下示例中，变量值中的 commit 前缀用作入口点来访问构建的 JSON 载荷中的信息：

变量名称	变量值	变量说明
`_COMMIT_URL`	`$(commit.url)`	获取与提交内容关联的网址
`_COMMIT_USER`	`$(commit.author.login)`	获取提交内容作者的用户名
`_COMMIT_MESSAGE`	`$(commit.commit.message)`	获取与提交内容相关的提交消息
`_COMMIT_DATE`	`$(commit.commit.committer.date)`	获取与提交内容关联的日期
`_COMMIT_ADDITIONS`	`$(commit.files['*'].additions)`	获取与提交内容中文件相关联的附加项的数量

如需查看可使用 commit 前缀访问的字段列表，请参阅获取提交内容。

如果您为拉取请求调用的触发器启用评论控制，则调用该触发器的事件为 IssueCommentEvent 且关联的前缀是 issue_comment。在以下示例中，变量值中的 issue_comment 前缀用作入口点来访问构建的 JSON 载荷中的信息：

变量名称	变量值	变量说明
`_PULL_REQUEST_ID`	`$(issue_comment.issue.id)`	获取拉取请求的 ID
`_PULL_REQUEST_TITLE`	`$(issue_comment.issue.title)`	获取拉取请求的标题
`_STATE`	`$(issue_comment.state)`	获取拉取请求的状态（例如打开、关闭等）
`_LABELS`	`$(issue_comment.issue.labels)`	获取与拉取请求关联的标签列表
`_LABELS_URL`	`$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)`	获取与匹配说明的标签关联的网址

如需查看您可以使用 issue_comment 前缀访问的字段列表，请参阅 IssueCommentEvent。

如果您的源代码位于 Cloud Source Repositories 中，则可以使用载荷绑定在替代变量中引用事件载荷中的信息。如需从推送事件访问 JSON 载荷，请使用前缀 csr 或 body。在以下示例中，变量值中的 csr 前缀用作入口点，以访问 build 的 JSON 载荷中的信息。

变量名称	变量值	变量说明
`_REPO_NAME`	`$(csr.name)`	获取代码库的名称
`_REPO_URL`	`$(csr.url)`	获取代码库的网址
`_CREATED_REPO`	`$(csr.createRepoEvent)`	指示用户是否创建了代码库
`_REF_EVENT_NAME`	`$(csr.refUpdateEvent.refUpdates['*'].refName)`	参考的名称（例如“ref/heads/primary-branch”）

如需查看您在 Cloud Source Repositories 中可以访问的其他字段，请参阅通知数据。

Bash 参数扩展

您可以将 bash 参数扩展应用于默认变量和用户定义的变量。受支持的操作示例包括子字符串替换、字符串分割和大小写设置。例如，您可能希望替换默认变量中的子字符串，并将其用作映像标记。

您可以为替代变量指定的 bash 参数扩展如下所示：

Bash 展开	说明
`${var}`	扩展 `var` 中存储的字符串值
`${var^}`	将字符串中的第一个字符大写
`${var^^}`	将字符串中的所有字符都大写
`${var,}`	将字符串中的第一个字符小写
`${var,,}`	将字符串中的所有字符都小写
`${var:position}`	移除字符串中的前 `position` 个字符
`${var:position:length}`	从 `position` 中指定的数值开始对字符串进行分割，最多包含 `length` 中指定的数值
`${var/substring/replacement}`	将 `substring` 中指定的值的最左侧实例替换为 `replacement` 中指定的值
`${var//substring/replacement}`	将 `substring` 中指定的值的所有实例替换为 `replacement` 中指定的值
`${var/#substring/replacement}`	只有当 `substring` 是 `var` 的前缀时，才将 `substring` 中指定的值的第一个实例替换为 `replacement` 中指定的值
`${var/%substring/replacement}`	只有当 `substring` 是 `var` 的后缀时，才将 `substring` 中指定的值的最后一个实例替换为 `replacement` 中指定的值
`${#var}`	检索字符串的长度
`${var:-default}`	除非已定义 `var`，否则将 `var` 评估为 `default`

您还可以指定匹配以下 bash 参数扩展的模式：

Bash 展开	说明
`${var#pattern}`	移除字符串左侧的字符，直到包含指定的 `pattern` 最左侧的实例
`${var##pattern}`	移除字符串左侧的字符，直到包含指定的 `pattern` 最右侧的实例
`${var%pattern}`	移除字符串右侧的字符，直到包含指定的 `pattern` 的第一个实例
`${var%%pattern}`	移除字符串左侧的字符，直到包含指定的 `pattern` 最右侧的实例

您可以指定的模式包括：

格式	说明
`*`	匹配零个或更多个字母数字字符
`?`	匹配任何单个字母数字字符
`[ccc]`	匹配 `ccc` 中的任何单个字符，包括 `a-z` 或 `0-9` 之间的范围
`[^c]`	匹配不在 `c` 中的任何字母数字字符，包括 `lo` <= `c` <= `hi` 的字符范围
`c`	匹配任何字母数字字符 `c`
`\c`	匹配任何字符 `c`，包括非字母数字字符，例如 `*`、`?` 或 `\`

应用 bash 参数扩展

如需将 bash 参数扩展应用于内置或用户定义的替代变量，请执行以下操作：

打开触发器页面。
如果尚未创建构建触发器，请点击创建触发器。否则，请选择现有的触发器。
在替代变量下，点击添加变量。
按照以下所述惯例为变量添加一个名称：
- 替代变量必须以下划线 (_) 开头，并且只能使用大写字母和数字（遵循正则表达式格式 [A-Z0-9_]+）。这样做可以防止与内置替代变量产生冲突。
- 参数数量的上限为 100 个。参数键的长度上限为 100 个字节，参数值的长度上限为 4000 个字节。
如需详细了解如何定义和使用用户定义的替代变量，请参阅使用用户定义的替代变量。

为变量添加一个值，并将受支持的 bash 参数扩展应用于内置替代变量或其他用户定义的替代变量。

在以下示例中，内置替代变量 $BRANCH_NAME 的默认值为 Feature_Secret_Project_#v2。下表展示了可应用于 $BRANCH_NAME 的 bash 参数扩展的示例：

变量名称	Bash 扩展	变量值	说明
`_BRANCH_LOWERCASE`	`${$BRANCH_NAME,,}`	`feature_secret_project_#v2`	将字符串中的所有字符设为小写
`_BRANCH_NO_SUFFIX`	`${_BRANCH_LOWERCASE%_\#v2}`	`feature_secret_project`	删除与指定模式匹配的字符串右侧的所有字符
`_BRANCH_NO_PREFIX`	`${_BRANCH_NO_SUFFIX#*_}`	`secret_project`	删除第一个下划线前面的所有字符
`_BRANCH_FOR_IMAGE_NAME`	`${_BRANCH_NO_PREFIX//_/-}`	`secret-project`	将所有下划线替换为短划线
`_IMAGE_NAME`	`my-app-${_BRANCH_FOR_IMAGE_NAME}-prod`	`my-app-secret-project-prod`	使用上文定义的 `_BRANCH_FOR_IMAGE_NAME` 变量构造映像的名称

假设 _IMAGE_NAME 在触发器中定义为上表中指定的值 my-app-secret-project-prod。此值现在将替换构建配置文件中的 _IMAGE_NAME 的任何定义。在以下示例中，当调用构建触发器时，_IMAGE_NAME (my-app-secret-project-prod) 的指定变量值会替换 _IMAGE_NAME (test-image) 的默认值。

YAML

 steps:
 - name: 'gcr.io/cloud-builders/docker'
   args: ['build',
          '-t',
          'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
          '.']
 substitutions:
     _IMAGE_NAME: test-image #default value
 images: [
     'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
 ]
 options:
     dynamicSubstitutions: true

JSON

 {
   'steps': [
     {
       'name': 'gcr.io/cloud-builders/docker',
       'args': [
         'build',
         '-t',
         'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
         '.'
       ]
     }
   ],
   'substitutions': {
     '_IMAGE_NAME': 'test-image' #default value
   },
   'images': [
     'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
   ],
   "options": {
     "dynamic_substitutions": true
   }
 }

在上述示例中设置为 true 的 dynamicSubstitutions 字段允许解读 bash 参数扩展。如果由触发器调用您的构建，则 dynamicSubstitutions 字段始终设置为 true，无需在构建配置文件中指定。如果是手动调用您的构建，则必须将 dynamicSubstitutions 字段设置为 true，以便在运行构建时解读 bash 参数扩展。

将 bash 参数扩展与载荷绑定结合使用

您可以将 bash 参数扩展应用于与载荷绑定关联的变量，方法是创建新变量来引用包含您的绑定的变量，或将绑定与 bash 参数扩展捆绑在一起。下表列出了如何将 bash 参数扩展与载荷绑定结合使用的示例：

变量名称	变量值	变量说明
`_URL`	`$(push.repository.html_url)`	获取代码库的网址
`_URL_CAPITAL`	`${_URL^^}`	使用 bash 参数扩展将网址中的所有字符都设为大写
`_APP_NAME`	`my-app-${_URL_CAPITAL}`	向代码库的大写网址添加前缀
`APP_NAME_ID`	`my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7}`	创建一个应用名称，其中包含代码库网址和载荷 ID 的前七个字符

后续步骤

了解如何替换变量值。
了解如何创建基本构建配置文件。
了解如何创建和管理构建触发器。
了解如何手动运行构建。