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

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

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，處理推送事件、提取要求事件，以及以註解設限的提取要求事件。您不需要在這些變數值前面加上前置字元。

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

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

1. 開啟「觸發條件」頁面。

2. 如果尚未建立自動建構觸發條件，請按一下「建立觸發條件」。否則請選取現有的觸發條件。

3. 在「替代變數」下方，按一下「新增變數」。

4. 按照下列慣例，為「變數」新增名稱：

   • 取代項開頭必須為底線 (_)，且只能使用大寫字母和數字 (遵循規則運算式 [A-Z0-9_]+)。這樣可避免與內建取代項發生衝突。

   • 參數數量不能超過 100 個，參數鍵的長度不得超過 100 個位元組，參數值的長度不得超過 4000 個位元組。

   如要進一步瞭解如何定義及使用使用者定義的 substitutions，請參閱「使用使用者定義的 substitutions」。

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

   如果原始碼位於 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 參數擴充套用至內建或使用者定義的替代變數，請按照下列步驟操作：

1. 開啟「觸發條件」頁面。

2. 如果尚未建立自動建構觸發條件，請按一下「建立觸發條件」。否則請選取現有的觸發條件。

3. 在「替代變數」下方，按一下「新增變數」。

4. 按照下列慣例，為「變數」新增名稱：

   • 取代項開頭必須為底線 (_)，且只能使用大寫字母和數字 (遵循規則運算式 [A-Z0-9_]+)。這樣可避免與內建取代項發生衝突。

   • 參數數量不能超過 100 個，參數鍵的長度不得超過 100 個位元組，參數值的長度不得超過 4000 個位元組。

   如要進一步瞭解如何定義及使用使用者定義的 substitutions，請參閱「使用使用者定義的 substitutions」。

5. 為變數新增值，並將支援的 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 的前七個字元

後續步驟

• 瞭解如何代入變數值。
• 瞭解如何建立基本的建構設定檔。
• 瞭解如何建立及管理自動建構觸發條件。
• 瞭解如何手動執行建構。