在建構設定檔中使用 substitutions 可在建構時間替換特定變數。
對於值在建構之前仍未知的變數，或者以不同變數值重複使用現有建構要求而言，substitutions 很實用。
Cloud Build 提供內建 substitutions，您也可以定義自己的 substitutions。在建構的 steps 和 images 中使用 substitutions，即可在建構時解析其值。
本頁面說明如何使用預設替代變數，或定義您自己的 substitutions。
使用預設 substitutions
Cloud Build 為所有建構作業提供下列預設替代項目：
$PROJECT_ID：Cloud 專案 ID$BUILD_ID：版本 ID$PROJECT_NUMBER：您的專案編號$LOCATION：與建構相關聯的區域
Cloud Build 為觸發條件叫用的建構作業提供下列預設替換項目：
$TRIGGER_NAME：與觸發條件相關聯的名稱$COMMIT_SHA：與建構相關聯的提交 ID$REVISION_ID：與建構相關聯的提交 ID$SHORT_SHA：COMMIT_SHA的前七個字元$REPO_NAME：存放區名稱$REPO_FULL_NAME：存放區的完整名稱，包括使用者或機構$BRANCH_NAME：分支版本名稱$TAG_NAME：代碼名稱$REF_NAME：分支版本或標記名稱$TRIGGER_BUILD_CONFIG_PATH：建構執行期間使用的建構設定檔路徑；如果建構在觸發事件中內嵌設定，或使用Dockerfile或Buildpack，則為空字串。$SERVICE_ACCOUNT_EMAIL：您用於建構的服務帳戶電子郵件地址。這可能是預設服務帳戶，也可能是使用者指定的服務帳戶。$SERVICE_ACCOUNT：服務帳戶的資源名稱，格式為projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL
Cloud Build 提供下列 GitHub 專屬的預設替換值，可用於提取要求觸發條件：
$_HEAD_BRANCH：提取要求的主分支$_BASE_BRANCH：提取要求的基礎分支$_HEAD_REPO_URL：拉取要求的首要存放區網址$_PR_NUMBER：提取要求編號
如果預設 substitution 無法使用 (例如不適用於無原始碼建構，或使用儲存空間原始碼的建構)，系統會將出現的遺失變數取代為空字串。
使用 gcloud builds submit 啟動建構時，您可以使用 --substitutions 引數指定通常來自已觸發建構的變數。具體而言，您可以手動提供下列項目的值：
$TRIGGER_NAME$COMMIT_SHA$REVISION_ID$SHORT_SHA$REPO_NAME$REPO_FULL_NAME$BRANCH_NAME$TAG_NAME$REF_NAME$TRIGGER_BUILD_CONFIG_PATH$SERVICE_ACCOUNT_EMAIL$SERVICE_ACCOUNT
例如，下列指令使用 TAG_NAME substitution：
gcloud builds submit --config=cloudbuild.yaml \ --substitutions=TAG_NAME="test" 以下範例使用預設替換值 $BUILD_ID、$PROJECT_ID、$PROJECT_NUMBER 和 $REVISION_ID。
YAML
steps: # Uses the ubuntu build step: # to run a shell script; and # set env variables for its execution - name: 'ubuntu' args: ['bash', './myscript.sh'] env: - 'BUILD=$BUILD_ID' - 'PROJECT_ID=$PROJECT_ID' - 'PROJECT_NUMBER=$PROJECT_NUMBER' - 'REV=$REVISION_ID' # Uses the docker build step to build an image called my-image - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-image', '.'] # my-image is pushed to Container Registry images: - 'gcr.io/$PROJECT_ID/my-image' JSON
{ "steps": [{ "name": "ubuntu", "args": [ "bash", "./myscript.sh" ], "env": [ "BUILD=$BUILD_ID", "PROJECT_ID=$PROJECT_ID", "PROJECT_NUMBER=$PROJECT_NUMBER", "REV=$REVISION_ID" ] }, { "name": "gcr.io/cloud-builders/docker", "args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."] }], "images": [ "gcr.io/$PROJECT_ID/my-image" ] } 以下範例顯示建構要求如何使用 docker 建構步驟建構映像檔，然後使用預設 $PROJECT_ID substitution 將映像檔推送至 Container Registry：
在這個例子中：
- 建構要求有一個建構步驟，使用
gcr.io/cloud-builders中的docker建構步驟來建構 Docker 映像檔。- 步驟中的
args欄位會指定要傳送至docker指令的引數，在這個範例中會叫用build -t gcr.io/my-project/cb-demo-img .(將$PROJECT_ID替換為您的專案 ID 之後)。
- 步驟中的
images欄位包含圖片的名稱。如果建構成功，系統會將產生的映像檔推送至 Container Registry。如果建構未成功建立映像檔，建構將會失敗。
YAML
steps: - name: gcr.io/cloud-builders/docker args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."] images: - gcr.io/$PROJECT_ID/cb-demo-img JSON
{ "steps": [{ "name": "gcr.io/cloud-builders/docker", "args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."] }], "images": [ "gcr.io/$PROJECT_ID/cb-demo-img" ] } 使用使用者定義的 substitutions
您也可以定義自己的 substitutions。使用者定義的 substitutions 必須符合下列規則：
- Substitutions 的開頭必須為底線 (
_)，且只能使用大寫字母和數字 (遵循規則運算式_[A-Z0-9_]+)，這樣就能避免與內建替換項目發生衝突。如要使用開頭為$的運算式，您必須使用$$. Thus:$FOOis invalid since it is not a built-in substitution.$$FOO評估為常值字串$FOO。
- 參數數量上限為 200 個，參數金鑰的長度上限為 100 個位元組，參數值的長度上限為 4000 個位元組。
$_FOO和${_FOO}的計算結果都是_FOO的值。不過，${}不用空格就可以成功 substitution，進而允許使用像是${_FOO}BAR這樣的 substitutions。$$allows you to include a literal$in the template. Thus:$_FOOevaluates to the value of_FOO.$$_FOO的評估結果為常值字串$_FOO。$$$_FOO的評估結果為常值字串$，後面接_FOO的值。
如要使用替換值，請在
gcloud指令中使用--substitutions引數，或在設定檔中指定。以下範例顯示具有兩個使用者定義 substitutions 的建構設定，名稱分別為
_NODE_VERSION_1和_NODE_VERSION_2：YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '--build-arg', 'node_version=${_NODE_VERSION_1}', '-t', 'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}', '.'] - name: 'gcr.io/cloud-builders/docker' args: ['build', '--build-arg', 'node_version=${_NODE_VERSION_2}', '-t', 'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}', '.'] substitutions: _NODE_VERSION_1: v6.9.1 # default value _NODE_VERSION_2: v6.9.2 # default value images: [ 'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}', 'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}' ]JSON
{ "steps": [{ "name": "gcr.io/cloud-builders/docker", "args": [ "build", "--build-arg", "node_version=${_NODE_VERSION_1}", "-t", "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}", "." ] }, { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "--build-arg", "node_version=${_NODE_VERSION_2}", "-t", "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}", "." ] }], "substitutions": { "_NODE_VERSION_1": "v6.9.1" "_NODE_VERSION_1": "v6.9.2" }, "images": [ "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}", "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}" ] }如要覆寫您在建構設定檔中指定的 substitution 值，請在
gcloud builds submit指令中使用--substitutions標記。請注意，substitutions 是變數與值的對應，而不是變數與陣列或序列的對應。您可以覆寫預設的替換變數值，但$PROJECT_ID和$BUILD_ID除外。下列指令會覆寫在上述建構設定檔中指定的_NODE_VERSION_1預設值：gcloud builds submit --config=cloudbuild.yaml \ --substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .根據預設，如果有遺失的 substitution 變數或遺失的 substitution，建構會傳回錯誤，但是，您可以設定
ALLOW_LOOSE選項，略過這項檢查。下列程式碼片段會顯示「hello world」，並定義未使用的 substitution。由於已設定
ALLOW_LOOSEsubstitution 選項，因此，即使遺失 substitution，建構也會成功。YAML
steps: - name: 'ubuntu' args: ['echo', 'hello world'] substitutions: _SUB_VALUE: unused options: substitutionOption: 'ALLOW_LOOSE'JSON
{ "steps": [ { "name": "ubuntu", "args": [ "echo", "hello world" ] } ], "substitutions": { "_SUB_VALUE": "unused" }, "options": { "substitution_option": "ALLOW_LOOSE" } }如果您的建構作業是由觸發條件叫用，系統會預設設定
ALLOW_LOOSE選項。在這種情況下，如果有遺失的 substitution 變數或遺失的 substitution，建構不會傳回錯誤。您無法針對觸發條件所叫用的建構作業覆寫ALLOW_LOOSE選項。如果未指定
ALLOW_LOOSE選項，則替換對應或建構要求中的不相符金鑰會導致發生錯誤。舉例來說，如果建構要求包含$_FOO，而替換對應未定義_FOO，則在執行建構作業或叫用觸發條件 (如果觸發條件包含替換變數) 後，您會收到錯誤訊息。即使您未設定
ALLOW_LOOSE選項，下列替換變數仍會一律包含預設的空字串值：$REPO_NAME$REPO_FULL_NAME$BRANCH_NAME$TAG_NAME$COMMIT_SHA$SHORT_SHA
定義替代變數時，不必侷限於靜態字串。您也可以存取觸發條件所叫用的事件酬載。這些值可做為酬載繫結。您也可以對替代變數套用 bash 參數擴充功能，並將產生的字串儲存為新的替代變數。詳情請參閱「在替代變數中使用酬載繫結與 bash 參數擴展」一文。
動態替換
您可以在建構設定檔中將
dynamicSubstitutions選項設為true，藉此在使用者定義的替換項目中參照其他變數的值。如果版本是由觸發事件叫用，dynamicSubstitutions欄位一律會設為true，因此無須在建構設定檔中指定。如果您是手動叫用建構作業，則必須將dynamicSubstitutions欄位設為true，才能在執行建構作業時解讀 bash 參數展開作業。下列建構設定檔顯示替換變數
${_IMAGE_NAME}參照變數${PROJECT_ID}。dynamicSubstitutions欄位已設為true，因此系統會在手動叫用建構作業時套用參照：YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', '${_IMAGE_NAME}', '.'] substitutions: _IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image' options: dynamicSubstitutions: trueJSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "${_IMAGE_NAME}", "." ] } ], "substitutions": { "_IMAGE_NAME": "gcr.io/${PROJECT_ID}/test-image" }, "options": { "dynamic_substitutions": true } }詳情請參閱「套用 bash 參數展開功能」。
將替換項目對應至環境變數
指令碼不直接支援替換，但支援環境變數。您可以將替換項目對應至環境變數，方法是一次自動全部對應，或手動定義每個環境變數。
自動對應替換
在建構層級。如要自動將所有替代項目對應至環境變數，並在整個建構期間使用這些變數，請在建構層級將
automapSubstitutions設為true做為選項。舉例來說，以下建構設定檔顯示使用者定義的替代值$_USER和預設替代值$PROJECT_ID對應至環境變數：YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" options: automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'" } ], "options": { "automap_substitutions": true }, "substitutions": { "_USER": "Google Cloud" } }在步驟層級。如要自動對應所有替換項目，並在單一步驟中將這些項目設為可用的環境變數，請在該步驟中將
automapSubstitutions欄位設為true。在下列範例中，只有第二個步驟會正確顯示替換項目，因為只有這個步驟啟用了自動替換對應功能：YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'", "automap_substitutions": true } ], }, "substitutions": { "_USER": "Google Cloud" }此外，您也可以在整個建構作業中將替換項目設為環境變數，然後在單一步驟中忽略這些變數。請在建構層級將
automapSubstitutions設為true，然後在要略過替換的步驟中將相同欄位設為false。在以下範例中，即使在建構層級啟用對應替換功能，系統也不會在第二個步驟中列印專案 ID，因為automapSubstitutions已在該步驟中設為false：YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" automapSubstitutions: false options: automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'", "automap_substitutions": false } ], "options": { "automap_substitutions": true }, }, "substitutions": { "_USER": "Google Cloud" }
手動對應
您可以手動將替換項目對應至環境變數。每個環境變數都會在步驟層級使用
env欄位定義，且變數的範圍僅限於定義變數的步驟。這個欄位會接受鍵和值的清單。以下範例說明如何將替換項目
$PROJECT_ID對應至環境變數BAR：YAML
steps: - name: 'ubuntu' env: - 'BAR=$PROJECT_ID' script: 'echo $BAR'JSON
{ "steps": [ { "name": "ubuntu", "env": [ "BAR=$PROJECT_ID" ], "script": "echo $BAR" } ] }後續步驟
- 瞭解如何在替代變數中使用酬載繫結與 bash 參數擴展。
- 瞭解如何建立基本的建構設定檔。
- 瞭解如何建立及管理自動建構觸發條件。
- 瞭解如何在 Cloud Build 中手動執行建構。
您可以使用下列其中一種方式指定變數：$_FOO 或 ${_FOO}：