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

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:

Buka halaman Pemicu.
Jika Anda belum membuat pemicu build, klik Create trigger. Jika tidak, pilih pemicu yang ada.
Di bagian Variabel substitusi, klik Tambahkan variabel.
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.

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.

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.

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

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:

Buka halaman Pemicu.
Jika Anda belum membuat pemicu build, klik Create trigger. Jika tidak, pilih pemicu yang ada.
Di bagian Variabel substitusi, klik Tambahkan variabel.
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.

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

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.