Halaman ini diterjemahkan oleh Cloud Translation API.

Mengganti nilai variabel

Gunakan substitutions di file konfigurasi build untuk mengganti variabel tertentu pada waktu build.

Substitusi berguna untuk variabel yang nilainya tidak diketahui hingga waktu build, atau untuk menggunakan kembali permintaan build yang sudah ada dengan nilai variabel yang berbeda.

Cloud Build menyediakan penggantian bawaan atau Anda dapat menentukan penggantian Anda sendiri. Gunakan substitutions di steps dan images build Anda untuk menyelesaikan nilainya pada waktu build.

Halaman ini menjelaskan cara menggunakan penggantian default atau menentukan penggantian Anda sendiri substitutions.

Menggunakan penggantian default

Cloud Build menyediakan substitusi default berikut untuk semua build:

$PROJECT_ID: ID project Cloud Anda
$BUILD_ID: ID build Anda
$PROJECT_NUMBER: nomor project Anda
$LOCATION: region yang terkait dengan build Anda

Cloud Build menyediakan substitusi default berikut untuk build yang dipanggil oleh pemicu:

$TRIGGER_NAME: nama yang terkait dengan pemicu Anda
$COMMIT_SHA: ID commit yang terkait dengan build Anda
$REVISION_ID: ID commit yang terkait dengan build Anda
$SHORT_SHA : tujuh karakter pertama dari COMMIT_SHA
$REPO_NAME: nama repositori Anda
$REPO_FULL_NAME: nama lengkap repositori Anda, termasuk pengguna atau organisasi
$BRANCH_NAME: nama cabang Anda
$TAG_NAME: nama tag Anda
$REF_NAME: nama cabang atau tag Anda
$TRIGGER_BUILD_CONFIG_PATH: jalur ke file konfigurasi build yang digunakan selama eksekusi build; jika tidak, string kosong jika build Anda dikonfigurasi inline pada pemicu atau menggunakan Dockerfile atau Buildpack.
$SERVICE_ACCOUNT_EMAIL: email akun layanan yang Anda gunakan untuk build. Ini adalah akun layanan default atau akun layanan yang ditentukan pengguna.
$SERVICE_ACCOUNT: nama resource akun layanan, dalam format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

Cloud Build menyediakan penggantian default khusus GitHub berikut yang tersedia untuk pemicu permintaan pull:

$_HEAD_BRANCH : cabang head pull request
$_BASE_BRANCH : cabang dasar pull request
$_HEAD_REPO_URL : URL repositori head pull request
$_PR_NUMBER : nomor pull request

Jika penggantian default tidak tersedia (seperti pada build tanpa sumber, atau pada build yang menggunakan sumber penyimpanan), maka kemunculan variabel yang tidak ada akan diganti dengan string kosong.

Saat memulai build menggunakan gcloud builds submit, Anda dapat menentukan variabel yang biasanya berasal dari build yang dipicu dengan argumen --substitutions. Secara khusus, Anda dapat memberikan nilai secara manual untuk:

$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

Misalnya, perintah berikut menggunakan penggantian TAG_NAME:

gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=TAG_NAME="test"

Contoh berikut menggunakan penggantian default $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER, dan $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"
  ]
}

Contoh berikut menunjukkan permintaan build menggunakan langkah build docker untuk membangun image, lalu mengirim image ke Artifact Registry menggunakan penggantian $PROJECT_ID default:

Dalam contoh ini:

Permintaan build memiliki satu langkah build, yang menggunakan langkah build docker di gcr.io/cloud-builders untuk membangun image Docker.
- Kolom args dalam langkah menentukan argumen yang akan diteruskan ke perintah docker, dalam hal ini build -t gcr.io/my-project/cb-demo-img ., akan dipanggil (setelah $PROJECT_ID diganti dengan project ID Anda).
Kolom images berisi nama gambar. Jika build berhasil, image yang dihasilkan akan dikirim ke Artifact Registry. Jika image tidak berhasil dibuat oleh build, build akan gagal.

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"
  ]
}

Menggunakan penggantian yang ditentukan pengguna

Anda juga dapat menentukan penggantian Anda sendiri. Penggantian yang ditentukan pengguna harus sesuai dengan aturan berikut:

Substitusi harus dimulai dengan garis bawah (_) dan hanya menggunakan huruf besar dan angka (dengan memperhatikan ekspresi reguler _[A-Z0-9_]+). Hal ini mencegah konflik dengan substitusi bawaan. Untuk menggunakan ekspresi yang dimulai dengan $, Anda harus menggunakan $$. For example:
- $FOO is invalid since it is not a built-in substitution.
- $$FOO yang dievaluasi ke string literal $FOO.
Jumlah parameter dibatasi hingga 200 parameter. Panjang kunci parameter dibatasi hingga 100 byte dan panjang nilai parameter dibatasi hingga 4.000 byte.

Anda dapat menentukan variabel dengan salah satu dari dua cara: $_FOO atau ${_FOO}:

$_FOO dan ${_FOO} dievaluasi ke nilai _FOO. Namun, ${} memungkinkan penggantian berfungsi tanpa spasi di sekitarnya, yang memungkinkan penggantian seperti ${_FOO}BAR.

$$ lets you include a literal $ in the template. For example:

$_FOO evaluates to the value of _FOO.
$$_FOO dievaluasi ke string literal $_FOO.
$$$_FOO dievaluasi ke string literal $ yang diikuti dengan nilai _FOO.

Untuk menggunakan penggantian, gunakan argumen --substitutions dalam perintah gcloud atau tentukan di file konfigurasi.

Contoh berikut menunjukkan konfigurasi build dengan dua penggantian yang ditentukan pengguna yang disebut _NODE_VERSION_1 dan _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}"
    ]
}

Untuk mengganti nilai penggantian yang Anda tentukan dalam file konfigurasi build, gunakan tanda --substitutions dalam perintah gcloud builds submit. Perhatikan bahwa penggantian adalah pemetaan variabel ke nilai, bukan array atau urutan. Anda dapat mengganti nilai variabel pengganti default, kecuali $PROJECT_ID dan $BUILD_ID. Perintah berikut menggantikan nilai default untuk _NODE_VERSION_1 yang ditentukan dalam file konfigurasi build sebelumnya:

gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .

Secara default, build akan menampilkan error jika ada variabel penggantian yang tidak ada atau penggantian yang tidak ada. Namun, Anda dapat menyetel opsi ALLOW_LOOSE untuk melewati pemeriksaan ini.

Cuplikan berikut mencetak "hello world" dan menentukan penggantian yang tidak digunakan. Karena opsi penggantian ALLOW_LOOSE ditetapkan, build akan berhasil meskipun penggantian tidak ada.

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"
    }
}

Jika build Anda dipanggil oleh pemicu, opsi ALLOW_LOOSE akan ditetapkan secara default. Dalam hal ini, build Anda tidak akan menampilkan error jika ada variabel penggantian yang tidak ada atau penggantian yang tidak ada. Anda tidak dapat mengganti opsi ALLOW_LOOSE untuk build yang dipanggil oleh pemicu.

Jika opsi ALLOW_LOOSE tidak ditentukan, kunci yang tidak cocok dalam pemetaan substitusi atau permintaan build akan menghasilkan error. Misalnya, jika permintaan build Anda menyertakan $_FOO dan pemetaan penggantian tidak menentukan _FOO, Anda akan menerima error setelah menjalankan build atau memanggil pemicu jika pemicu Anda menyertakan variabel penggantian.

Variabel pengganti berikut selalu berisi nilai string kosong default meskipun Anda tidak menyetel opsi ALLOW_LOOSE:

$REPO_NAME
$REPO_FULL_NAME
$BRANCH_NAME
$TAG_NAME
$COMMIT_SHA
$SHORT_SHA

Saat menentukan variabel penggantian, Anda tidak terbatas pada string statis. Anda juga memiliki akses ke payload acara yang memanggil pemicu. Ini tersedia sebagai binding payload. Anda juga dapat menerapkan ekspansi parameter bash pada variabel substitusi dan menyimpan string yang dihasilkan sebagai variabel substitusi baru. Untuk mempelajari lebih lanjut, lihat Menggunakan binding payload dan ekspansi parameter bash dalam substitusi.

Penggantian dinamis

Anda dapat mereferensikan nilai variabel lain dalam penggantian yang ditentukan pengguna dengan menyetel opsi dynamicSubstitutions ke true dalam file konfigurasi build. Jika build Anda dipanggil oleh pemicu, kolom dynamicSubstitutions akan selalu disetel ke true dan tidak perlu ditentukan dalam file konfigurasi build. Jika build dipanggil secara manual, Anda harus menyetel kolom dynamicSubstitutions ke true agar ekspansi parameter bash dapat ditafsirkan saat menjalankan build.

File konfigurasi build berikut menunjukkan variabel penggantian ${_IMAGE_NAME} yang mereferensikan variabel, ${PROJECT_ID}. Kolom dynamicSubstitutions ditetapkan ke true sehingga referensi diterapkan saat memanggil build secara manual:

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
    }
}

Untuk mengetahui informasi selengkapnya, lihat Menerapkan ekspansi parameter bash.

Memetakan penggantian ke variabel lingkungan

Skrip tidak secara langsung mendukung penggantian, tetapi mendukung variabel lingkungan. Anda dapat memetakan penggantian ke variabel lingkungan, baik secara otomatis sekaligus, atau secara manual dengan menentukan setiap variabel lingkungan sendiri.

Memetakan penggantian secara otomatis

Di tingkat build. Untuk memetakan semua substitusi secara otomatis ke variabel lingkungan, yang akan tersedia di seluruh build, tetapkan automapSubstitutions ke true sebagai opsi di tingkat build. Misalnya, file konfigurasi build berikut menunjukkan substitusi yang ditentukan pengguna $_USER dan substitusi default $PROJECT_ID yang dipetakan ke variabel lingkungan:

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"
  }
}

Di tingkat langkah. Untuk memetakan semua substitusi secara otomatis dan menyediakannya sebagai variabel lingkungan dalam satu langkah, tetapkan kolom automapSubstitutions ke true pada langkah tersebut. Dalam contoh berikut, hanya langkah kedua yang akan menampilkan penggantian dengan benar, karena hanya langkah tersebut yang mengaktifkan pemetaan penggantian otomatis:

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"
  }

Selain itu, Anda dapat membuat penggantian tersedia sebagai variabel lingkungan di seluruh build, lalu mengabaikannya dalam satu langkah. Tetapkan automapSubstitutions ke true di tingkat build, lalu tetapkan kolom yang sama ke false pada langkah saat Anda ingin mengabaikan penggantian. Dalam contoh berikut, meskipun penggantian pemetaan diaktifkan di tingkat build, project ID tidak akan dicetak pada langkah kedua, karena automapSubstitutions ditetapkan ke false pada langkah tersebut:

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"
  }

Memetakan penggantian secara manual

Anda dapat memetakan penggantian ke variabel lingkungan secara manual. Setiap variabel lingkungan ditentukan di tingkat langkah menggunakan kolom env, dan cakupan variabel dibatasi ke langkah tempat variabel tersebut ditentukan. Kolom ini mengambil daftar kunci dan nilai.

Contoh berikut menunjukkan cara memetakan penggantian $PROJECT_ID ke variabel lingkungan BAR:

YAML

steps:
- name: 'ubuntu'
  env:
  - 'BAR=$PROJECT_ID'
  script: 'echo $BAR'

JSON

{
  "steps": [
    {
      "name": "ubuntu",
      "env": [
        "BAR=$PROJECT_ID"
      ],
      "script": "echo $BAR"
    }
  ]
}

Langkah berikutnya

Pelajari cara menggunakan binding payload dan ekspansi parameter bash dalam substitusi.
Pelajari cara membuat file konfigurasi build dasar.
Pelajari cara membuat dan mengelola pemicu build.
Pelajari cara menjalankan build secara manual di Cloud Build.

Mengganti nilai variabel Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Menggunakan penggantian default

YAML

JSON

YAML

JSON

Menggunakan penggantian yang ditentukan pengguna

YAML

JSON

YAML

JSON

Penggantian dinamis

YAML

JSON

Memetakan penggantian ke variabel lingkungan

Memetakan penggantian secara otomatis

YAML

JSON

YAML

JSON

YAML

JSON

Memetakan penggantian secara manual

YAML

JSON

Langkah berikutnya

Mengganti nilai variabel