替換變數值

在建構設定檔中使用 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

注意： $COMMIT_SHA 和 $REVISION_ID 都代表與建構相關聯的提交 ID。系統支援這兩種替換方式。

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:
  • $FOO is invalid since it is not a built-in substitution.
  • $$FOO 評估為常值字串 $FOO。
• 參數數量上限為 200 個，參數金鑰的長度上限為 100 個位元組，參數值的長度上限為 4000 個位元組。

您可以使用下列其中一種方式指定變數：$_FOO 或 ${_FOO}：

• $_FOO 和 ${_FOO} 的計算結果都是 _FOO 的值。不過，${} 不用空格就可以成功 substitution，進而允許使用像是 ${_FOO}BAR 這樣的 substitutions。
• $$ allows you to include a literal $ in the template. Thus:
  • $_FOO evaluates 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_LOOSE substitution 選項，因此，即使遺失 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: true
  

  JSON

  {
     "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 中手動執行建構。