Menggunakan binding payload dan ekspansi parameter bash dalam substitusi

Halaman ini menjelaskan cara menggunakan binding payload dan menerapkan ekspansi parameter bash ke variabel penggantian yang terkait dengan pemicu build Anda. Jika Anda tidak terbiasa dengan cara menggunakan variabel penggantian dalam konfigurasi build, lihat Mengganti nilai variabel.

Cloud Build memungkinkan Anda menyimpan bagian payload peristiwa pemicu sebagai variabel penggantian. Payload peristiwa adalah isi peristiwa yang memanggil pemicu. Variabel yang terkait dengan payload disebut sebagai binding dan tersedia untuk build yang dipanggil oleh peristiwa push dan pull. Dengan binding, Anda dapat mengakses data tambahan yang terkait dengan build, seperti bahasa yang terkait dengan kode sumber dan penulis permintaan pull.

Cloud Build juga memungkinkan pengguna menerapkan perluasan parameter bash ke nilai variabel penggantian. Perluasan parameter bash memungkinkan Anda mengakali string yang terkait dengan variabel yang ada. Anda dapat memanipulasi string dengan menggunakan huruf besar atau mengganti substring.

Anda dapat menggunakan binding payload dan menerapkan perluasan parameter bash saat menentukan atau memperbarui pemicu build di konsol Google Cloud dan di file konfigurasi Cloud Build. Selain itu, Anda dapat menerapkan perluasan parameter bash saat menjalankan build manual.

Binding payload

Anda dapat menyimpan bagian payload peristiwa pemicu sebagai nilai variabel penggantian. Binding payload tersedia sebagai nilai variabel untuk build yang dipanggil oleh peristiwa push dan pull, dan dapat digunakan untuk mengakses payload JSON saat kode sumber Anda berada di repositori GitHub atau Cloud Source Repositories. Untuk mempelajari payload peristiwa GitHub lebih lanjut, lihat Payload peristiwa webhook. Untuk mempelajari payload peristiwa untuk Cloud Source Repositories lebih lanjut, lihat Notifikasi untuk Cloud Source Repositories.

Anda dapat mengakses informasi dari payload peristiwa menggunakan awalan yang ditetapkan, yang mewakili root payload peristiwa. Dimulai dengan awalan, Anda dapat menggunakan sintaksis JSONPath untuk mengakses payload dan mengambil data darinya. Awalan payload berikut tersedia bergantung pada jenis peristiwa Anda:

Awalan	Sumber	Deskripsi
push	GitHub	Memungkinkan Anda mengakses kolom dalam payload JSON untuk peristiwa push
pull_request	GitHub	Memungkinkan Anda mengakses kolom dalam payload JSON untuk peristiwa permintaan pull
issue_comment	GitHub	Memungkinkan Anda mengakses kolom dalam payload JSON untuk peristiwa komentar masalah yang terkait dengan permintaan pull
csr	Cloud Source Repositories	Memungkinkan Anda mengakses kolom dalam payload JSON untuk peristiwa push

Catatan: Anda juga dapat mengakses payload menggunakan awalan body, bukan awalan yang tercantum di atas untuk peristiwa apa pun. Misalnya, Anda dapat menggunakan awalan body untuk mengakses isi payload untuk peristiwa pemicu webhook atau peristiwa Pub/Sub.

Untuk peristiwa apa pun yang terkait dengan aplikasi GitHub, nilai variabel bawaan is_collaborator dan perm_level juga tersedia. Status pengguna diperiksa untuk peristiwa push dan pull berdasarkan nilai variabel push.pusher.name, pull_request.pull_request.user.login, dan issue_comment.comment.user.login. Tabel berikut menunjukkan cara menyertakannya sebagai nilai variabel untuk pemicu saat kode sumber Anda berada di GitHub:

Nama Variabel	Nilai Variabel	Deskripsi Variabel
_PERM_LEVEL	$(perm_level)	Mendapatkan tingkat izin pengguna
_IS_COLLABORATOR	$(is_collaborator)	Output true jika pengguna adalah kolaborator

Anda dapat menggunakan nilai variabel is_collaborator dan perm_level untuk peristiwa push, peristiwa permintaan pull, dan peristiwa permintaan pull yang dibatasi oleh komentar. Anda tidak perlu mendahului nilai variabel ini dengan awalan.

Membuat penggantian menggunakan binding payload

Untuk membuat variabel penggantian yang menggunakan binding payload:

1. Buka halaman Pemicu.

2. Jika Anda belum membuat pemicu build, klik Create trigger. Atau, pilih pemicu yang ada.

3. Di bagian Substitution variables, klik Add variable.

4. Tambahkan nama untuk Variabel Anda dengan mengikuti konvensi yang diuraikan di bawah ini:

   • Substitusi harus dimulai dengan garis bawah (_) dan hanya menggunakan huruf besar dan angka (mengikuti ekspresi reguler [A-Z0-9_]+). Hal ini mencegah konflik dengan penggantian bawaan.

   • Jumlah parameter dibatasi hingga 100 parameter. Panjang kunci parameter dibatasi hingga 100 byte dan panjang nilai parameter dibatasi hingga 4.000 byte.

   Untuk mempelajari lebih lanjut cara menentukan dan menggunakan penggantian yang ditentukan pengguna, lihat Menggunakan penggantian yang ditentukan pengguna.

5. Tambahkan nilai untuk variabel Anda, menggunakan awalan yang didukung.

   Jika kode sumber Anda ada di GitHub, Anda dapat merujuk ke informasi dalam payload peristiwa dalam variabel penggantian menggunakan binding payload. Untuk mengakses payload JSON peristiwa push, gunakan awalan push atau body. Dalam contoh berikut, awalan push dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda:

   Nama Variabel	Nilai Variabel	Deskripsi Variabel
   _PUSH_NAME	$(push.repository.name)	Mendapatkan nama repositori yang terkait dengan peristiwa push
   _COMMITS	$(push.commits)	Mendapatkan array objek commit yang menjelaskan setiap commit yang didorong
   _OWNER	$(push.repository.owner.name)	Mendapatkan nama pemilik repositori
   _URL	$(push.repository.html_url)	Mendapatkan URL untuk repositori GitHub Anda
   _LANGUAGE	$(push.repository.language)	Mendapatkan bahasa kode sumber Anda yang disertakan dalam push

   Untuk mengetahui daftar kolom yang dapat Anda akses menggunakan awalan push, lihat PushEvent.

   Untuk mengakses payload JSON peristiwa permintaan pull, gunakan awalan pull_request atau body. Dalam contoh berikut, awalan pull_request dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda:

   Nama Variabel	Nilai Variabel	Deskripsi Variabel
   _PULL_REQUEST_ID	$(pull_request.pull_request.id)	Mendapatkan ID permintaan pull
   _PULL_REQUEST_TITLE	$(pull_request.pull_request.title)	Mendapatkan judul permintaan pull
   _PULL_REQUEST_BODY	$(pull_request.pull_request.body)	Mendapatkan isi permintaan pull
   _USERNAME	$(pull_request.pull_request.user.login)	Mendapatkan nama pengguna pengirim permintaan pull
   _MERGE_TIME	$(pull_request.pull_request.merged_at)	Mendapatkan waktu permintaan pull digabungkan

   Untuk mengetahui daftar kolom yang dapat Anda akses menggunakan awalan pull_request, lihat PullRequestEvent.

   Untuk mengakses payload JSON peristiwa commit, gunakan awalan commit. Dalam contoh berikut, awalan commit dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda:

   Nama Variabel	Nilai Variabel	Deskripsi Variabel
   _COMMIT_URL	$(commit.url)	Mendapatkan URL yang terkait dengan commit
   _COMMIT_USER	$(commit.author.login)	Mendapatkan nama pengguna penulis commit
   _COMMIT_MESSAGE	$(commit.commit.message)	Mendapatkan pesan commit yang terkait dengan commit
   _COMMIT_DATE	$(commit.commit.committer.date)	Mendapatkan tanggal yang terkait dengan commit
   _COMMIT_ADDITIONS	$(commit.files['*'].additions)	Mendapatkan jumlah penambahan yang terkait dengan file dalam commit

   Untuk mengetahui daftar kolom yang dapat Anda akses menggunakan awalan commit, lihat Mendapatkan commit.

   Jika Anda mengaktifkan Kontrol komentar untuk pemicu yang dipanggil oleh permintaan pull, peristiwa yang memanggil pemicu adalah IssueCommentEvent dan awalan terkaitnya adalah issue_comment. Dalam contoh berikut, awalan issue_comment dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda:

   Nama Variabel	Nilai Variabel	Deskripsi Variabel
   _PULL_REQUEST_ID	$(issue_comment.issue.id)	Mendapatkan ID permintaan pull
   _PULL_REQUEST_TITLE	$(issue_comment.issue.title)	Mendapatkan judul permintaan pull
   _STATE	$(issue_comment.state)	Mendapatkan status permintaan pull (yaitu terbuka, tertutup, dll.)
   _LABELS	$(issue_comment.issue.labels)	Mendapatkan daftar label yang terkait dengan permintaan pull
   _LABELS_URL	$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)	Mendapatkan URL yang terkait dengan label yang cocok dengan deskripsi

   Untuk mengetahui daftar kolom yang dapat Anda akses menggunakan awalan issue_comment, lihat IssueCommentEvent.

   Catatan: Jika Anda menggunakan body sebagai awalan, awalan ini akan merujuk ke issue_comment, bukan peristiwa satu permintaan pull. Untuk mengakses kolom yang terkait dengan satu permintaan pull, gunakan awalan pull_request.

   Jika kode sumber Anda berada di Cloud Source Repositories, Anda dapat merujuk ke informasi dalam payload peristiwa dalam variabel penggantian menggunakan binding payload. Untuk mengakses payload JSON dari peristiwa push, gunakan awalan csr atau body. Dalam contoh berikut, awalan csr dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda.

   Nama Variabel	Nilai Variabel	Deskripsi Variabel
   _REPO_NAME	$(csr.name)	Mendapatkan nama repositori Anda
   _REPO_URL	$(csr.url)	Mendapatkan URL repositori Anda
   _CREATED_REPO	$(csr.createRepoEvent)	Menunjukkan apakah pengguna membuat repositori
   _REF_EVENT_NAME	$(csr.refUpdateEvent.refUpdates['*'].refName)	Nama ref (misalnya, "refs/heads/primary-branch")

   Untuk melihat kolom tambahan yang dapat Anda akses di Cloud Source Repositories, lihat Data notifikasi.

Catatan: Anda juga dapat menggunakan binding payload dalam file konfigurasi build, tetapi binding tersebut hanya akan ditafsirkan saat build Anda dipanggil oleh pemicu.

Ekspansi parameter bash

Anda dapat menerapkan ekspansi parameter bash ke variabel default dan variabel yang ditentukan pengguna. Contoh operasi yang didukung meliputi penggantian substring, pemotongan string, dan kapitalisasi. Misalnya, Anda mungkin ingin mengganti substring dalam variabel default dan menggunakan variabel tersebut sebagai tag gambar.

Ekspansi parameter bash yang dapat Anda tentukan untuk variabel penggantian adalah sebagai berikut:

Ekspansi bash	Deskripsi
${var}	Memperluas nilai string yang disimpan di var
${var^}	Mengubah huruf pertama dalam string menjadi huruf kapital
${var^^}	Mengapitalisasi semua karakter dalam string
${var,}	Mengubah karakter pertama dalam string menjadi huruf kecil
${var,,}	Mengubah semua karakter dalam string menjadi huruf kecil
${var:position}	Menghapus karakter position pertama dari string
${var:position:length}	Memotong string mulai dari nilai numerik yang ditentukan di position dan menyertakan hingga nilai numerik yang ditentukan di length
${var/substring/replacement}	Mengganti instance paling kiri dari nilai yang ditentukan di substring dengan nilai yang ditentukan di replacement
${var//substring/replacement}	Mengganti semua instance nilai yang ditentukan di substring dengan nilai yang ditentukan di replacement
${var/#substring/replacement}	Mengganti instance pertama nilai yang ditentukan dalam substring dengan nilai yang ditentukan dalam replacement hanya jika substring adalah awalan var
${var/%substring/replacement}	Mengganti instance terakhir nilai yang ditentukan di substring dengan nilai yang ditentukan di replacement hanya jika substring adalah akhiran dari var
${#var}	Mengambil panjang string
${var:-default}	Mengevaluasi var ke default kecuali jika var sudah ditentukan

Catatan: ${var:=default} dan ${var=default} berperilaku mirip dengan ${var:-default} dan tidak menetapkan nilai ke var jika belum ditentukan.

Anda juga dapat menentukan pola yang akan dicocokkan untuk perluasan parameter bash berikut:

Ekspansi bash	Deskripsi
${var#pattern}	Menghapus karakter dari sisi kiri string hingga dan termasuk instance paling kiri dari pattern yang ditentukan
${var##pattern}	Menghapus karakter dari sisi kiri string hingga dan termasuk instance paling kanan dari pattern yang ditentukan
${var%pattern}	Menghapus karakter dari sisi kanan string hingga dan termasuk instance pertama pattern yang ditentukan
${var%%pattern}	Menghapus karakter dari sisi kanan string hingga dan termasuk instance paling kiri dari pattern yang ditentukan

Pola yang dapat Anda tentukan meliputi:

Pola	Deskripsi
*	Mencocokkan nol karakter atau lebih alfanumerik
?	Mencocokkan satu karakter alfanumerik
[ccc]	Mencocokkan satu karakter apa pun di ccc termasuk rentang antara a-z atau 0-9
[^c]	Mencocokkan karakter alfanumerik apa pun yang tidak ada di c, termasuk rentang karakter dengan lo <= c <= hi
c	Mencocokkan karakter alfanumerik apa pun c
\c	Mencocokkan karakter c apa pun, termasuk karakter non-alfanumerik seperti *, ?, atau \

Menerapkan ekspansi parameter bash

Untuk menerapkan ekspansi parameter bash ke variabel penggantian bawaan atau buatan pengguna:

1. Buka halaman Pemicu.

2. Jika Anda belum membuat pemicu build, klik Create trigger. Atau, pilih pemicu yang ada.

3. Di bagian Substitution variables, klik Add variable.

4. Tambahkan nama untuk Variabel Anda dengan mengikuti konvensi yang diuraikan di bawah ini:

   • Substitusi harus dimulai dengan garis bawah (_) dan hanya menggunakan huruf besar dan angka (mengikuti ekspresi reguler [A-Z0-9_]+). Hal ini mencegah konflik dengan penggantian bawaan.

   • Jumlah parameter dibatasi hingga 100 parameter. Panjang kunci parameter dibatasi hingga 100 byte dan panjang nilai parameter dibatasi hingga 4.000 byte.

   Untuk mempelajari lebih lanjut cara menentukan dan menggunakan penggantian yang ditentukan pengguna, lihat Menggunakan penggantian yang ditentukan pengguna.

5. Tambahkan nilai untuk variabel Anda, dengan menerapkan ekspansi parameter bash yang didukung ke variabel penggantian bawaan atau variabel penggantian buatan pengguna lainnya.

   Dalam contoh berikut, variabel penggantian bawaan $BRANCH_NAME memiliki nilai default Feature_Secret_Project_#v2. Tabel berikut menunjukkan contoh perluasan parameter bash yang dapat Anda terapkan ke $BRANCH_NAME:

   Nama Variabel	Ekspansi bash	Nilai Variabel	Deskripsi
   _BRANCH_LOWERCASE	${$BRANCH_NAME,,}	feature_secret_project_#v2	mengubah semua karakter dalam string menjadi huruf kecil
   _BRANCH_NO_SUFFIX	${_BRANCH_LOWERCASE%_\#v2}	feature_secret_project	menghapus semua karakter dari sisi kanan string yang cocok dengan pola yang ditentukan
   _BRANCH_NO_PREFIX	${_BRANCH_NO_SUFFIX#*_}	secret_project	menghapus semua karakter hingga garis bawah pertama
   _BRANCH_FOR_IMAGE_NAME	${_BRANCH_NO_PREFIX//_/-}	secret-project	mengganti semua garis bawah dengan tanda hubung
   _IMAGE_NAME	my-app-${_BRANCH_FOR_IMAGE_NAME}-prod	my-app-secret-project-prod	membuat nama untuk gambar menggunakan variabel _BRANCH_FOR_IMAGE_NAME yang ditentukan di atas

   Misalnya, _IMAGE_NAME ditentukan dalam pemicu Anda sebagai nilai yang ditentukan dalam tabel di atas, my-app-secret-project-prod. Nilai ini sekarang akan menggantikan definisi _IMAGE_NAME apa pun dalam file konfigurasi build Anda. Dalam contoh berikut, nilai variabel yang ditentukan untuk _IMAGE_NAME (my-app-secret-project-prod) akan menggantikan nilai default _IMAGE_NAME (test-image) saat pemicu build dipanggil.

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

Kolom dynamicSubstitutions, yang ditetapkan ke true dalam contoh di atas, memungkinkan ekspansi parameter bash ditafsirkan. Jika build Anda dipanggil oleh pemicu, kolom dynamicSubstitutions selalu ditetapkan ke true dan tidak perlu ditentukan dalam file konfigurasi build Anda. Jika build dipanggil secara manual, Anda harus menetapkan kolom dynamicSubstitutions ke true agar ekspansi parameter bash ditafsirkan saat menjalankan build.

Menggunakan ekspansi parameter bash dengan binding payload

Anda dapat menerapkan ekspansi parameter bash ke variabel yang terkait dengan binding payload dengan membuat variabel baru untuk mereferensikan variabel yang berisi binding atau menggabungkan binding dengan ekspansi parameter bash. Tabel berikut mencantumkan contoh cara Anda dapat menggunakan ekspansi parameter bash dengan binding payload:

Nama Variabel	Nilai Variabel	Deskripsi Variabel
_URL	$(push.repository.html_url)	Mendapatkan URL repositori
_URL_CAPITAL	${_URL^^}	Menggunakan ekspansi parameter bash untuk menulis semua karakter dalam URL dalam huruf besar
_APP_NAME	my-app-${_URL_CAPITAL}	Menambahkan awalan ke URL repositori yang diawali dengan huruf besar
APP_NAME_ID	my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7}	Membuat nama aplikasi yang menyertakan URL repositori dan tujuh karakter pertama ID payload

Catatan: Operasi bertingkat tidak diizinkan. Misalnya, Anda tidak dapat menyusun bertingkat binding payload dalam ekspansi parameter bash: ${$(push.repository.html_url)^^}.

Langkah selanjutnya

• Pelajari cara mengganti nilai variabel.
• Pelajari cara membuat file konfigurasi build dasar.
• Pelajari cara membuat dan mengelola pemicu build.
• Pelajari cara menjalankan build secara manual.