本頁面由 Cloud Translation API 翻譯而成。

在替代變數中使用酬載繫結與 bash 參數擴展

本頁面說明如何使用酬載繫結，並將 bash 參數擴充套用至與建構觸發條件相關聯的替代變數。如果您不熟悉如何在建構設定中使用替換變數，請參閱「替換變數值」。

Cloud Build 可讓您將觸發事件酬載的部分儲存為替換變數。事件酬載是叫用觸發條件的事件主體。與酬載相關聯的變數稱為繫結，可供推送和拉取事件一併叫用的版本使用。綁定可讓您存取與建構相關的其他資料，例如與原始碼相關聯的語言，以及提取要求的作者。

Cloud Build 也允許使用者將 bash 參數擴充套用至替代變數值。Bash 參數擴充功能可讓您操作與現有變數相關聯的字串。您可以透過大寫字母或替換子字串來操作字串。

您可以在 Google Cloud 控制台和 Cloud Build 設定檔中，定義或更新建構觸發條件時使用酬載繫結，並套用 bash 參數擴展。此外，您也可以在執行手動建構時套用 bash 參數擴充功能。

酬載繫結

您可以將觸發事件酬載的部分儲存為替代變數值。酬載繫結可做為變數值，用於由推送和提取事件叫用的建構作業，並可用於存取 JSON 酬載，前提是原始碼位於 GitHub 存放區或 Cloud Source Repositories 中。如要進一步瞭解 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 來處理推送事件、拉取要求事件，以及受留言限制的拉取要求事件。您不需要在這些變數值前面加上前置字串。

使用酬載繫結建立替代變數

如要建立使用酬載繫結的替代變數，請按照下列步驟操作：

開啟「觸發條件」頁面。
如果您尚未建立版本觸發條件，請按一下「建立觸發條件」。否則請選取現有的觸發條件。
在「Substitution variables」(替代變數) 下方，按一下「Add variable」(新增變數)。
按照下列概略說明的規則為「變數」新增名稱：
- Substitutions 的開頭必須為底線 (_)，且只能使用大寫字母和數字 (遵循規則運算式 [A-Z0-9_]+)，這樣就能避免與內建替換項目產生衝突。
- 參數數量不能超過 100 個，參數金鑰的長度上限為 100 個位元組，參數值的長度上限為 4000 個位元組。
如要進一步瞭解如何定義及使用使用者定義的替換值，請參閱「使用使用者定義的替換值」一文。

使用支援的前置字串，為變數新增值。

如果原始碼位於 GitHub 中，您可以使用酬載繫結，在替換變數中參照事件酬載中的資訊。如要存取推播事件的 JSON 酬載，請使用前置字串 push 或 body。在以下範例中，變數值中的 push 前置字會用作進入點，用於存取建構的 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 前置字會用作進入點，用於存取建構的 JSON 酬載資訊。

變數名稱	變數值	變數說明
`_REPO_NAME`	`$(csr.name)`	取得存放區名稱
`_REPO_URL`	`$(csr.url)`	取得存放區的網址
`_CREATED_REPO`	`$(csr.createRepoEvent)`	指出使用者建立了存放區
`_REF_EVENT_NAME`	`$(csr.refUpdateEvent.refUpdates['*'].refName)`	參照的名稱 (例如「refs/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 參數擴展套用至內建或使用者定義的替代變數，請按照下列步驟操作：

開啟「觸發條件」頁面。
如果您尚未建立版本觸發條件，請按一下「建立觸發條件」。否則請選取現有的觸發條件。
在「Substitution variables」(替代變數) 下方，按一下「Add variable」(新增變數)。
按照下列概略說明的規則為「變數」新增名稱：
- Substitutions 的開頭必須為底線 (_)，且只能使用大寫字母和數字 (遵循規則運算式 [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
   }
 }

dynamicSubstitutions 欄位 (在上例中設為 true) 可解讀 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 的前七個字元