Menggunakan binding payload dan perluasan parameter bash dalam substitusi

Halaman ini menjelaskan cara menggunakan binding payload dan menerapkan perluasan parameter bash ke variabel substitusi yang terkait dengan pemicu build. Jika Anda belum memahami cara menggunakan variabel substitusi dalam konfigurasi build, lihat Mengganti nilai variabel.

Dengan Cloud Build, Anda dapat menyimpan bagian dari payload peristiwa pemicu sebagai variabel substitusi. 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 ekspansi parameter bash ke nilai variabel pengganti. Perluasan parameter Bash memungkinkan Anda memanipulasi string yang terkait dengan variabel yang ada. Anda dapat memanipulasi string dengan kapitalisasi huruf 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 substitusi. Binding payload tersedia sebagai nilai variabel untuk build yang dipanggil oleh peristiwa push dan pull, serta 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 dari payload. 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 memunculkan peristiwa komentar 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 guna 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 dengan 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 ada di GitHub:

Nama Variabel	Nilai Variabel	Deskripsi Variabel
_PERM_LEVEL	$(perm_level)	Memperoleh tingkat izin pengguna
_IS_COLLABORATOR	$(is_collaborator)	Menghasilkan 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 mengawali nilai variabel ini dengan awalan.

Membuat substitusi menggunakan binding payload

Untuk membuat variabel substitusi yang menggunakan binding payload:

1. Buka halaman Pemicu.

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

3. Di bagian Variabel substitusi, klik Tambahkan variabel.

4. Tambahkan nama untuk Variabel Anda sesuai dengan konvensi yang dijelaskan di bawah ini:

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

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

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

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

   Jika kode sumber berada di GitHub, Anda dapat melihat informasi di payload peristiwa dalam variabel substitusi menggunakan binding payload. Untuk mengakses payload JSON dari peristiwa push, gunakan awalan push atau body. Pada 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)	Memperoleh nama repositori yang terkait dengan peristiwa push
   _COMMITS	$(push.commits)	Memperoleh 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 daftar kolom yang dapat Anda akses menggunakan awalan push, lihat PushEvent.

   Untuk mengakses payload JSON dari peristiwa permintaan pull, gunakan awalan pull_request atau body. Pada 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)	Memperoleh ID permintaan pull
   _PULL_REQUEST_TITLE	$(pull_request.pull_request.title)	Memperoleh 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)	Memperoleh waktu saat permintaan pull digabungkan

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

   Untuk mengakses payload JSON peristiwa commit, gunakan awalan commit. Pada 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)	Memperoleh tanggal yang terkait dengan commit
   _COMMIT_ADDITIONS	$(commit.files['*'].additions)	Memperoleh jumlah penambahan yang terkait dengan file dalam commit

   Untuk 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 yang terkait adalah issue_comment. Pada 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)	Memperoleh ID permintaan pull
   _PULL_REQUEST_TITLE	$(issue_comment.issue.title)	Memperoleh 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 daftar kolom yang dapat Anda akses menggunakan awalan issue_comment, lihat IssueCommentEvent.

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

   Jika kode sumber Anda berada dalam Cloud Source Repositories, Anda dapat merujuk ke informasi dalam payload peristiwa dalam variabel substitusi menggunakan binding payload. Untuk mengakses payload JSON dari peristiwa push, gunakan awalan csr atau body. Pada 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 (mis. "ref/heads/primary-branch")

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

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

Perluasan parameter Bash

Anda dapat menerapkan perluasan parameter bash ke variabel default dan variabel buatan pengguna. Contoh operasi yang didukung meliputi penggantian substring, slicing string, dan kapitalisasi. Misalnya, Anda mungkin ingin mengganti substring dalam variabel default dan menambahkannya sebagai tag gambar.

Perluasan parameter bash yang dapat Anda tentukan untuk variabel substitusi adalah sebagai berikut:

Perluasan bash	Deskripsi
${var}	Memperluas nilai string yang disimpan di var
${var^}	Menggunakan huruf besar pada karakter pertama dalam string
${var^^}	Menggunakan huruf besar untuk semua karakter dalam string
${var,}	Huruf kecil pada karakter pertama dalam string
${var,,}	Huruf kecil semua karakter dalam string
${var:position}	Menghapus position karakter pertama dari string
${var:position:length}	Memotong string yang dimulai pada nilai numerik yang ditentukan dalam position dan mencakup hingga nilai numerik yang ditentukan dalam length
${var/substring/replacement}	Mengganti instance nilai paling kiri yang ditentukan di substring dengan nilai yang ditentukan di replacement
${var//substring/replacement}	Mengganti semua nilai yang ditentukan di substring dengan nilai yang ditentukan di replacement
${var/#substring/replacement}	Mengganti instance pertama dari nilai yang ditentukan di substring dengan nilai yang ditentukan dalam replacement hanya jika substring adalah awalan var
${var/%substring/replacement}	Mengganti instance terakhir dari nilai yang ditentukan di substring dengan nilai yang ditentukan di replacement hanya jika substring adalah akhiran 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:

Perluasan 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 dari 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
*	Cocok dengan nol atau beberapa karakter alfanumerik
?	Cocok dengan satu karakter alfanumerik
[ccc]	Mencocokkan karakter tunggal apa pun di ccc termasuk rentang antara a-z atau 0-9
[^c]	Cocok dengan karakter alfanumerik yang tidak ada dalam c, termasuk rentang karakter dengan lo <= c <= hi
c	Cocok dengan karakter alfanumerik c
\c	Cocok dengan karakter apa pun c termasuk karakter non-alfanumerik seperti *, ?, atau \

Menerapkan perluasan parameter bash

Untuk menerapkan perluasan parameter bash ke variabel substitusi bawaan atau yang ditentukan pengguna:

1. Buka halaman Pemicu.

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

3. Di bagian Variabel substitusi, klik Tambahkan variabel.

4. Tambahkan nama untuk Variabel Anda sesuai dengan konvensi yang dijelaskan di bawah ini:

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

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

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

5. Tambahkan nilai untuk variabel Anda, dengan menerapkan ekspansi parameter bash yang didukung ke variabel substitusi bawaan atau variabel substitusi lain yang ditentukan pengguna.

   Dalam contoh berikut, variabel substitusi 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	Perluasan bash	Nilai Variabel	Deskripsi
   _BRANCH_LOWERCASE	${$BRANCH_NAME,,}	feature_secret_project_#v2	huruf kecil untuk semua karakter dalam string
   _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 sebagai nilai yang ditentukan dalam tabel di atas, my-app-secret-project-prod. Nilai ini sekarang akan mengganti semua definisi _IMAGE_NAME dalam file konfigurasi build Anda. Pada contoh berikut, nilai variabel yang ditentukan untuk _IMAGE_NAME (my-app-secret-project-prod) 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 pada contoh di atas, memungkinkan perluasan parameter bash untuk 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 dapat ditafsirkan saat menjalankan build.

Menggunakan perluasan 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 Anda atau merangkai binding bersama dengan ekspansi parameter bash. Tabel berikut mencantumkan contoh cara menggunakan perluasan parameter bash dengan binding payload:

Nama Variabel	Nilai Variabel	Deskripsi Variabel
_URL	$(push.repository.html_url)	Mendapatkan URL repositori
_URL_CAPITAL	${_URL^^}	Menggunakan perluasan parameter bash untuk menggunakan huruf besar pada semua karakter di URL
_APP_NAME	my-app-${_URL_CAPITAL}	Menambahkan awalan ke URL repositori yang menggunakan 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 menyarangkan binding payload dalam perluasan 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.