替換變數值

在建構設定檔中使用 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', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/my-image', '.']

# my-image is pushed to Artifact Registry
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/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 將映像檔推送至 Artifact Registry：

在這個例子中：

  • 建構要求有一個建構步驟，使用 gcr.io/cloud-builders 中的 docker 建構步驟來建構 Docker 映像檔。
    • 步驟中的 args 欄位會指定要傳送至 docker 指令的引數，在這個範例中會叫用 build -t gcr.io/my-project/cb-demo-img . (將 $PROJECT_ID 替代為您的專案 ID 之後)。

  • images 欄位包含映像檔的名稱。如果建構成功，系統會將產生的映像檔推送至 Artifact Registry。如果建構未成功建立映像檔，建構將會失敗。

YAML

steps:
- name: gcr.io/cloud-builders/docker
  args: ["build", "-t", "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img", "."]
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img'

JSON

{
  "steps": [{
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img", "."]
    }],
  "images": [
    "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img"
  ]
}

使用使用者定義的 substitutions

您也可以定義自己的 substitutions。使用者定義的 substitutions 必須符合下列規則：

  • Substitutions 的開頭必須為底線 (_)，且只能使用大寫字母和數字 (遵循規則運算式 _[A-Z0-9_]+)。這樣可避免與內建 Substitutions 發生衝突。如要使用以 $ 開頭的運算式，您必須使用 $$. For example:
    • $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。
    • $$ lets you include a literal $ in the template. For example:
      • $_FOO evaluates to the value of _FOO.
      • $$_FOO 的計算結果為字串常值 $_FOO。
      • $$$_FOO 的值為常值字串 $，後面接 _FOO 的值。

      如要使用 substitutions，請在 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',
          '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
          '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
          '--build-arg',
          'node_version=${_NODE_VERSION_2}',
          '-t',
          '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}',
          '.']
substitutions:
    _NODE_VERSION_1: v6.9.1 # default value
    _NODE_VERSION_2: v6.9.2 # default value
images: [
    '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
    '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}'
]

      JSON

      {
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_1}",
            "-t",
            "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}",
            "."
        ]
    }, {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_2}",
            "-t",
            "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}",
            "."
        ]
    }],
    "substitutions": {
        "_NODE_VERSION_1": "v6.9.1",
        "_NODE_VERSION_2": "v6.9.2",
    },
    "images": [
        "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}",
        "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/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 選項，substitution 對應或建構要求中的不相符鍵就會導致錯誤。舉例來說，如果建構要求包含 $_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 參數擴充。

      下列建構設定檔顯示參照變數 ${PROJECT_ID} 的替代變數 ${_IMAGE_NAME}。dynamicSubstitutions 欄位設為 true，因此手動叫用建構時會套用參照：

      YAML

      steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
    _IMAGE_NAME: '${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/test-image'
options:
    dynamicSubstitutions: true

      JSON

      {
    "steps": [
      {
          "name": "gcr.io/cloud-builders/docker",
          "args": [
            "build",
            "-t",
            "${_IMAGE_NAME}",
            "."
          ]
      }
    ],
    "substitutions": {
      "_IMAGE_NAME": "${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/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"
    }
  ]
}

      後續步驟