Ekspresi

Layanan Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Penting

Pilih versi artikel ini yang sesuai dengan platform dan versi Anda. Pemilih versi berada di atas daftar isi. Cari platform dan versi Azure DevOps Anda.

Gunakan ekspresi saat Anda perlu menentukan string, boolean, atau nilai angka saat menulis alur. Saat ekspresi mengembalikan array, aturan pengindeksan normal berlaku dan indeks dimulai dengan 0.

Penggunaan ekspresi yang paling umum adalah dalam kondisi untuk menentukan apakah pekerjaan atau langkah harus dijalankan.

# Expressions are used to define conditions for a step, job, or stage
steps:
- task: ...
  condition: <expression>

Penggunaan umum ekspresi lainnya adalah dalam menentukan variabel. Anda dapat mengevaluasi ekspresi pada waktu kompilasi atau pada waktu proses. Gunakan ekspresi waktu kompilasi di mana saja; gunakan ekspresi runtime dalam variabel dan kondisi. Gunakan ekspresi runtime untuk menghitung konten variabel dan status (misalnya: condition).

# Two examples of expressions used to define variables
# The first one, a, is evaluated when the YAML file is compiled into a plan.
# The second one, b, is evaluated at runtime.
# Note the syntax ${{}} for compile time and $[] for runtime expressions.
variables:
  a: ${{ <expression> }}
  b: $[ <expression> ]

Perbedaan antara sintaks ekspresi waktu proses dan waktu kompilasi terutama pada konteks apa yang tersedia. Dalam ekspresi waktu kompilasi (${{ <expression> }}), Anda memiliki akses ke parameters dan variables yang ditentukan secara statis. Dalam ekspresi runtime ($[ <expression> ]), Anda memiliki akses ke elemen tambahan variables tetapi tidak ada parameter.

Dalam contoh ini, ekspresi runtime mengatur nilai $(isMain). Variabel statis dalam ekspresi kompilasi mengatur nilai $(compileVar).

variables:
  staticVar: 'my value' # static variable
  compileVar: ${{ variables.staticVar }} # compile time expression
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')] # runtime expression

steps:
  - script: |
      echo ${{variables.staticVar}} # outputs my value
      echo $(compileVar) # outputs my value
      echo $(isMain) # outputs True

Ekspresi dapat berupa literal, referensi ke variabel, referensi ke dependensi, fungsi, atau kombinasi berlapis yang valid dari jenis ini.

Harfiah

Sebagai bagian dari ekspresi, Anda dapat menggunakan boolean, null, angka, string, atau literal versi.

# Examples
variables:
  someBoolean: ${{ true }} # case insensitive, so True or TRUE also works
  someNumber: ${{ -1.2 }}
  someString: ${{ 'a b c' }}
  someVersion: ${{ 1.2.3 }}

Boolean

True dan False adalah ekspresi harfiah boolean.

Nol

Null adalah ekspresi harfiah khusus yang dikembalikan dari kesalahan kamus, misalnya (variables['noSuch']). Null bisa menjadi output ekspresi tetapi tidak dapat dipanggil langsung dalam ekspresi.

Nomor

Dimulai dengan '-', '.', atau '0' hingga '9'.

string

Harus menggunakan tanda kutip tunggal. Misalnya: 'this is a string'.

Untuk mengekspresikan kutipan tunggal harfiah, lepaskan dengan satu kutipan. Misalnya: 'It''s OK if they''re using contractions.'.

Anda dapat menggunakan karakter pipa (|) untuk string multibaris.

myKey: |
  one
  two
  three

Versi

Nomor versi yang terdiri dari hingga empat segmen. Harus dimulai dengan angka dan berisi dua atau tiga karakter titik (.). Misalnya: 1.2.3.4.

Variabel

Sebagai bagian dari ekspresi, Anda dapat mengakses variabel dengan menggunakan salah satu dari dua sintaks:

• Sintaks indeks: variables['MyVar']
• Sintaksis dereferensi properti: variables.MyVar

Untuk menggunakan sintaks dereferensi properti, nama properti harus:

• Mulai dengan a-Z atau _
• Diikuti oleh a-Z, , 0-9atau _

Variabel yang berbeda tersedia tergantung pada konteks eksekusi.

• Jika Anda membuat alur menggunakan YAML, variabel alur tersedia.
• Jika Anda membuat alur build menggunakan editor klasik, maka variabel build tersedia.
• Jika Anda membuat alur rilis menggunakan editor klasik, variabel rilis tersedia.

Variabel selalu string. Jika Anda ingin menggunakan nilai yang ditik, gunakan parameter.

Catatan

Ada batasan untuk menggunakan variabel dengan ekspresi dalam alur kerja Klasik dan YAML saat menyetel variabel tersebut melalui antarmuka pengguna tab variabel. Variabel yang didefinisikan sebagai ekspresi tidak boleh bergantung pada variabel lain dengan ekspresi dalam nilai karena tidak dijamin bahwa kedua ekspresi akan dievaluasi dengan benar. Misalnya kita memiliki variabel a yang nilainya $[ <expression> ] digunakan sebagai bagian untuk nilai variabel b. Karena urutan pemrosesan variabel tidak dijamin variabel b dapat memiliki nilai variabel a yang salah setelah evaluasi.

Anda hanya dapat menggunakan konstruksi ini saat menyiapkan variabel melalui kata kunci variabel dalam alur YAML. Anda perlu menempatkan variabel dalam urutan yang harus diproses untuk mendapatkan nilai yang benar setelah pemrosesan.

Functions

Anda dapat menggunakan fungsi bawaan berikut dalam ekspresi.

dan

• Mengevaluasi ke True jika semua parameter adalah True.
• Parameter minimal: 2. Parameter maksimum: N.
• Mentransmisikan parameter ke Boolean untuk evaluasi.
• Sirkuit pendek setelah pertama False.
• Contoh: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

gabungkan

• Mengevaluasi parameter secara berurutan (kiri ke kanan), dan mengembalikan nilai pertama yang bukan null atau string kosong.
• Tidak mengembalikan nilai jika semua nilai parameter adalah string null atau kosong.
• Parameter minimal: 2. Parameter maksimum: N.
• Contoh: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

mengandung

• Mengevaluasi ke True jika string parameter kiri berisi parameter yang tepat.
• Parameter minimum: 2. Parameter maksimum: 2.
• Mentransmisikan parameter ke string untuk evaluasi.
• Melakukan perbandingan ordinal ignore-case.
• Contoh: contains('ABCDE', 'BCD') (mengembalikan True).

mengandungNilai

• Mengevaluasi True apakah parameter kiri adalah array, dan apakah ada item yang sama dengan parameter di sebelah kanan. Juga mengevaluasi True apakah parameter kiri adalah objek, dan nilai properti apa pun sama dengan parameter yang tepat.
• Parameter minimum adalah: 2. Parameter maksimum: 2.
• Jika parameter kiri adalah array, konversikan setiap item agar sesuai dengan jenis parameter kanan. Jika parameter kiri adalah objek, konversikan nilai setiap properti agar sesuai dengan jenis parameter kanan. Perbandingan kesetaraan untuk setiap item tertentu akan mengevaluasi False jika konversi gagal.
• Perbandingan abaikan kasus ordinal untuk string.
• Sirkuit pendek setelah pertandingan pertama

Catatan

Tidak ada sintaksis harfiah dalam alur YAML untuk menentukan array. Fungsi ini memiliki kegunaan terbatas dalam alur kerja umumnya. Ini ditujukan untuk digunakan dalam konteks dekorator pipeline dengan array yang disediakan sistem seperti daftar langkah.

Anda dapat menggunakan containsValue ekspresi untuk menemukan nilai yang cocok dalam objek. Berikut adalah contoh yang menunjukkan cara mencari di daftar cabang asal untuk menemukan kecocokan dengan Build.SourceBranch.

parameters:
- name: branchOptions
  displayName: Source branch options
  type: object
  default:
    - refs/heads/main
    - refs/heads/test

jobs:
  - job: A1 
    steps:
    - ${{ each value in parameters.branchOptions }}:
      - script: echo ${{ value }}

  - job: B1 
    condition: ${{ containsValue(parameters.branchOptions, variables['Build.SourceBranch']) }}
    steps:
      - script: echo "Matching branch found"

konversiToJson

• Ambil objek yang kompleks dan keluarkan sebagai JSON.
• Parameter minimum: 1. Parameter maks: 1.

parameters:
  - name: listOfValues
    type: object
    default:
      this_is:
        a_complex: object
        with:
          - one
          - two

steps:
- script: |
    echo "${MY_JSON}"
  env:
    MY_JSON: ${{ convertToJson(parameters.listOfValues) }}

Keluaran skrip

{
  "this_is": {
    "a_complex": "object",
    "with": [
      "one",
      "two"
    ]
  }
}

penghitung

• Gunakan fungsi ini hanya dalam ekspresi yang menentukan variabel. Jangan gunakan sebagai bagian dari kondisi untuk langkah, tugas, atau tahapan.
• Mengevaluasi angka yang meningkat dengan setiap kali jalankan pipeline.
• Mengambil dua parameter: prefix dan seed.
• prefix adalah ekspresi string. Fungsi ini melacak nilai penghitung terpisah untuk setiap nilai unik prefix. Gunakan karakter UTF-16 di prefix.
• seed adalah nilai awal penghitung.

Anda dapat membuat penghitung yang secara otomatis bertambah satu per satu setiap kali pipeline Anda dijalankan. Saat Anda menentukan penghitung, berikan prefix dan seed. Contoh berikut menunjukkan konsep ini.

variables:
  major: 1
  # define minor as a counter with the prefix as variable major, and seed as 100.
  minor: $[counter(variables['major'], 100)]

steps:
- bash: echo $(minor)

Nilai minor dalam contoh sebelumnya adalah 100 selama eksekusi pertama alur. Dalam eksekusi kedua, nilainya adalah 101, selama nilai major tetap 1.

Jika Anda mengedit file YAML dan memperbarui nilai variabel major menjadi 2, nilainya minor adalah 100 dalam eksekusi alur berikutnya. Eksekusi berikutnya akan menaikkan penghitung ke 101, 102, 103, dan sebagainya.

Jika nanti Anda mengedit file YAML dan mengatur nilai major kembali ke 1, nilai penghitung dimulai dari tempat yang terakhir untuk awalan tersebut. Dalam contoh ini, dilanjutkan pada 102.

Contoh berikut menunjukkan cara mengatur variabel untuk bertindak sebagai penghitung yang dimulai dari 100, berinkrement 1 setiap kali dijalankan, dan kembali ke 100 setiap hari.

Catatan

pipeline.startTime tidak tersedia di luar ekspresi. pipeline.startTime memformat system.pipelineStartTime ke dalam objek tanggal dan waktu untuk dapat digunakan oleh ekspresi. Zona waktu default untuk pipeline.startTime adalah UTC. Anda dapat mengubah zona waktu untuk organisasi Anda.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Contoh berikut menunjukkan penghitung yang mempertahankan nilai terpisah untuk eksekusi PR dan CI.

variables:
  patch: $[counter(variables['build.reason'], 0)]

Penghitung dilingkup ke alur. Dengan kata lain, alur menaikkan nilai penghitung untuk setiap eksekusi. Tidak ada penghitung yang khusus untuk proyek.

berakhir dengan

• Mengevaluasi True apakah parameter string di sebelah kiri berakhir dengan parameter di sebelah kanan.
• Parameter minimal: 2. Parameter maksimum: 2.
• Mentransmisikan parameter ke string untuk evaluasi.
• Melakukan perbandingan ordinal ignore-case.
• Contoh: endsWith('ABCDE', 'DE') (mengembalikan True)

Eq

• Mengevaluasi True apakah parameter sama
• Parameter minimum: 2. Parameter maksimum: 2.
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Mengembalikan False jika konversi gagal.
• Perbandingan abaikan kasus ordinal untuk string.
• Contoh: eq(variables.letters, 'ABC')

bentuk

• Mengevaluasi parameter berikutnya dan menyisipkannya ke dalam string parameter terkemuka
• Parameter minimum: 1. Parameter maks: N
• Contoh: format('Hello {0} {1}', 'John', 'Doe')
• Menggunakan spesifikasi format tanggal dan waktu kustom .NET untuk pemformatan tanggal (, yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff, K)
• Contoh: format('{0:yyyyMMdd}', pipeline.startTime). Dalam hal pipeline.startTime ini adalah variabel objek waktu tanggal khusus.
• Lolos dengan menggandakan kurung kurawal. Misalnya: format('literal left brace {{ and literal right brace }}')

Ge

• Mengevaluasi True apakah parameter kiri lebih besar dari atau sama dengan parameter kanan
• Parameter minimum: 2. Parameter maksimum: 2.
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Kesalahan jika konversi gagal.
• Perbandingan ordinal tanpa memperhatikan huruf besar-kecil untuk string.
• Contoh: ge(5, 5) (mengembalikan True)

GT

• Mengevaluasi True apakah parameter kiri lebih besar dari parameter kanan
• Parameter minimumnya: 2. Parameter maksimum: 2.
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Kesalahan jika konversi gagal.
• Perbandingan abaikan kasus ordinal untuk string.
• Contoh: gt(5, 2) (mengembalikan True)

di

• Mengevaluasi True apakah parameter kiri sama dengan parameter kanan apa pun
• Parameter minimum: 1. Parameter maks: N
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Perbandingan kesetaraan mengevaluasi False apakah konversi gagal.
• Perbandingan ordinal tanpa memperhatikan huruf besar/kecil untuk string.
• Sirkuit pendek setelah pertandingan pertama
• Contoh: in('B', 'A', 'B', 'C') (mengembalikan True)

iif

• Mengembalikan parameter kedua jika parameter pertama mengevaluasi ke True, dan parameter ketiga sebaliknya
• Parameter minimum: 1. Parameter maks: 3
• Parameter pertama harus berupa kondisi
• Contoh: iif(eq(variables['Build.Reason'], 'PullRequest'), 'ManagedDevOpsPool', 'Azure Pipelines') mengembalikan 'ManagedDevOpsPool' saat alur berjalan sebagai respons terhadap PR.

gabung

• Menghubungkan semua elemen dalam array parameter di sebelah kanan, dipisahkan oleh string parameter di sebelah kiri.
• Parameter minimumnya: 2. Parameter maksimum: 2.
• Setiap elemen dalam array dikonversi menjadi string. Objek kompleks dikonversi menjadi string kosong.
• Jika parameter yang tepat bukan array, hasilnya adalah parameter yang tepat yang dikonversi menjadi string.

Dalam contoh ini, titik koma ditambahkan di antara setiap item dalam array. Jenis parameter adalah objek.

parameters:
- name: myArray
  type: object
  default:
    - FOO
    - BAR
    - ZOO

variables:
   A: ${{ join(';',parameters.myArray) }}

steps:
  - script: echo $A # outputs FOO;BAR;ZOO

Le

• Mengevaluasi True apakah parameter kiri kurang dari atau sama dengan parameter kanan
• Parameter minimum: 2. Parameter maksimum: 2.
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Kesalahan jika konversi gagal.
• Melakukan perbandingan ordinal yang mengabaikan kasus untuk string.
• Contoh: le(2, 2) (mengembalikan True)

panjang

• Mengembalikan panjang string atau array, baik yang berasal dari sistem atau yang berasal dari parameter
• Parameter yang minimum: 1. Parameter maksimum: 1.
• Contoh: length('fabrikam') mengembalikan 8.

rendah

• Mengonversi string atau nilai variabel ke semua karakter huruf kecil.
• Parameter minimum: 1. Parameter maksimum: 1.
• Mengembalikan versi huruf kecil dari sebuah string.
• Contoh: lower('FOO') mengembalikan foo.

liter

• Mengevaluasi True apakah parameter kiri kurang dari parameter kanan.
• Parameter minimum: 2. Parameter maksimum: 2.
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Kesalahan jika konversi gagal.
• Perbandingan abaikan kasus ordinal untuk string.
• Contoh: lt(2, 5) (mengembalikan True)

Ne

• Mengevaluasi True apakah parameter tidak sama
• Parameter minimum: 2. Parameter maksimum: 2.
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Mengembalikan True jika konversi gagal.
• Perbandingan abaikan kasus ordinal untuk string.
• Contoh: ne(1, 2) mengembalikan True.

tidak

• Mengevaluasi True jika parameter adalah False
• Parameter minimum: 1. Parameter maks: 1
• Mengonversi nilai ke Boolean untuk evaluasi
• Contoh: not(eq(1, 2)) (mengembalikan True)

tidakDiDalam

• Mengevaluasi True apakah parameter kiri tidak sama dengan parameter kanan apa pun
• Parameter minimum: 1. Parameter maks: N
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Perbandingan kesetaraan mengevaluasi False apakah konversi gagal.
• Perbandingan ordinal tanpa memperhatikan huruf besar-kecil pada string.
• Sirkuit pendek setelah pertandingan pertama
• Contoh: notIn('D', 'A', 'B', 'C') (mengembalikan True)

atau

• Mengevaluasi True jika ada parameter True
• Parameter minimum: 2. Parameter maksimum: N.
• Mentransmisikan parameter ke Boolean untuk evaluasi.
• Hubungan arus pendek setelah yang pertama True
• Contoh: or(eq(1, 1), eq(2, 3)) (mengembalikan True, penghentian lebih awal)

ganti

• Mengembalikan string baru di mana semua instans string dalam instans saat ini diganti dengan string lain.
• Parameter minimum: 3. Parameter maksimum: 3.
• replace(a, b, c): mengembalikan a, dengan semua instans b digantikan oleh c.
• Contoh: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (mengembalikan http://server/saml/consume).

belah

• Memisahkan string menjadi substring berdasarkan karakter pembatas yang ditentukan.
• Parameter minimum adalah: 2. Parameter maksimum: 2.
• Parameter pertama adalah string yang akan dipisahkan.
• Parameter kedua adalah karakter pembatas.
• Mengembalikan serangkaian substring. Array menyertakan string kosong saat karakter pembatas muncul secara berturut-turut atau di akhir string.
• Contoh:

  variables:
  - name: environments
    value: prod1,prod2
  steps:
    - ${{ each env in split(variables.environments, ',')}}:
      - script: ./deploy.sh --environment ${{ env }}
  

• Contoh penggunaan split() dengan replace():

  parameters:
  - name: resourceIds
    type: object
    default:
    - /subscriptions/mysubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/loadBalancers/kubernetes-internal
    - /subscriptions/mysubscription02/resourceGroups/myResourceGroup02/providers/Microsoft.Network/loadBalancers/kubernetes
  - name: environments
    type: object
    default:
    - prod1
    - prod2
  
  trigger:
  - main
  
  steps:
  - ${{ each env in parameters.environments }}:
    - ${{ each resourceId in parameters.resourceIds }}:
        - script: echo ${{ replace(split(resourceId, '/')[8], '-', '_') }}_${{ env }}
  

startsWith (dimulaiDengan)

• Mengevaluasi True apakah string parameter kiri dimulai dengan parameter kanan
• Parameter yang minimum: 2. Parameter maksimum: 2.
• Mentransmisikan parameter ke string untuk evaluasi.
• Melakukan perbandingan ordinal ignore-case.
• Contoh: startsWith('ABCDE', 'AB') (mengembalikan True).

pangkas

• Mengembalikan parameter tanpa spasi putih di awal dan akhir
• Parameter minimum: 1. Parameter maks: 1
• Contoh: trim(' variable ') mengembalikan 'variabel'

atas

• Mengonversi string atau nilai variabel ke semua karakter huruf besar
• Parameter minimum: 1. Parameter maksimum: 1.
• Mengembalikan huruf besar yang setara dengan string
• Contoh: upper('bah') mengembalikan BAH

xor

• Mengevaluasi True jika hanya ada satu parameter yang True
• Parameter yang minimum: 2. Parameter maksimum: 2.
• Mentransmisikan parameter ke Boolean untuk evaluasi.
• Contoh: xor(True, False) (mengembalikan True)

Fungsi pemeriksaan status pekerjaan

Gunakan fungsi pemeriksaan status berikut sebagai ekspresi dalam kondisi, tetapi tidak dalam definisi variabel.

selalu

• Selalu menghasilkan True (meskipun ketika dibatalkan). Catatan: Kegagalan kritis mungkin masih mencegah tugas berjalan. Misalnya, jika gagal mendapatkan sumber.

dibatalkan

• Akan menjadi True jika alur dibatalkan.

gagal

• Untuk satu langkah, setara dengan eq(variables['Agent.JobStatus'], 'Failed').
• Untuk pekerjaan:
  • Tanpa adanya argumen, akan bernilai True jika ada pekerjaan sebelumnya dalam grafik dependensi yang gagal.
  • Dengan nama pekerjaan sebagai argumen, mengevaluasi ke True jika salah satu pekerjaan tersebut gagal.

berhasil

• Untuk satu langkah, setara dengan in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues').
• Gunakan dengan dependsOn saat mengerjakan tugas dan Anda ingin memeriksa apakah tugas sebelumnya berhasil. Pekerjaan berjalan secara paralel, sementara tahapan berjalan secara berurutan.
• Untuk pekerjaan:
  • Tanpa argumen, akan dievaluasi ke True jika semua pekerjaan sebelumnya pada graf dependensi berhasil atau sebagian berhasil.
  • Dengan nama pekerjaan sebagai argumen, mengevaluasi apakah True semua pekerjaan tersebut berhasil atau sebagian berhasil.
  • Akan menjadi False jika alur dibatalkan.

berhasilAtauGagal

• Untuk satu langkah, setara dengan in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed').

• Untuk pekerjaan:

  • Tanpa argumen, akan menghasilkan True terlepas dari apakah ada pekerjaan dalam grafik dependensi yang berhasil atau gagal.
  • Dengan nama pekerjaan sebagai argumen, mengevaluasi True apakah salah satu pekerjaan tersebut berhasil atau gagal.
  • Anda mungkin ingin menggunakan not(canceled()) sebagai gantinya ketika pekerjaan sebelumnya dalam grafik dependensi dilewati.

  Fungsi ini seperti always(), kecuali akan bernilai False ketika alur dibatalkan.

Penyisipan bersyarat

Gunakan ifklausa , elseif, dan else untuk menetapkan nilai variabel secara kondisional atau mengatur input untuk tugas. Anda juga dapat menjalankan langkah secara kondisional saat kondisi terpenuhi.

Kondisi hanya berfungsi saat Anda menggunakan sintaks template. Untuk informasi selengkapnya, lihat sintaks variabel.

Untuk templat, Anda dapat menggunakan penyisipan kondisi saat menambahkan urutan atau pemetaan. Untuk informasi selengkapnya, lihat penyisipan bersyarat dalam templat.

Menetapkan variabel secara kondisional

variables:
  ${{ if eq(variables['Build.SourceBranchName'], 'main') }}: # only works if you have a main branch
    stageName: prod

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo ${{variables.stageName}}

Mengatur input tugas secara kondisional

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Pipeline.Workspace)'
    ${{ if eq(variables['Build.SourceBranchName'], 'main') }}:
      artifact: 'prod'
    ${{ else }}:
      artifact: 'dev'
    publishLocation: 'pipeline'

Menjalankan langkah secara kondisional

Jika tidak ada set variabel, atau nilai foo tidak cocok dengan if kondisi, else pernyataan akan berjalan. Dalam contoh ini, nilai foo memberikan hasil true dalam kondisi elseif.

variables:
  - name: foo
    value: contoso # triggers elseif condition

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start"
- ${{ if eq(variables.foo, 'adaptum') }}:
  - script: echo "this is adaptum"
- ${{ elseif eq(variables.foo, 'contoso') }}: # true
  - script: echo "this is contoso"
- ${{ else }}:
  - script: echo "the value is not adaptum or contoso"

Setiap kata kunci

Gunakan kata kunci each untuk mengulang melalui parameter dengan jenis objek.

parameters:
- name: listOfStrings
  type: object
  default:
  - one
  - two

steps:
- ${{ each value in parameters.listOfStrings }}:
  - script: echo ${{ value }}

Anda juga dapat melakukan iterasi melalui elemen berlapis dalam objek.

parameters:
- name: listOfFruits
  type: object
  default:
  - fruitName: 'apple'
    colors: ['red','green']
  - fruitName: 'lemon'
    colors: ['yellow']
steps:
- ${{ each fruit in parameters.listOfFruits }} :
  - ${{ each fruitColor in fruit.colors}} :
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }}

Dependensi

Ekspresi dapat menggunakan konteks dependensi untuk mereferensikan pekerjaan atau tahap sebelumnya. Gunakan ketergantungan untuk:

• Mereferensikan status pekerjaan dari pekerjaan sebelumnya
• Mereferensikan status tahap dari tahap sebelumnya
• Variabel output referensi dalam pekerjaan sebelumnya dalam tahap yang sama
• Referensi variabel output pada tahap sebelumnya dalam sebuah tahap.
• Variabel output referensi dalam pekerjaan di tahap sebelumnya pada tahap berikut

Konteks dipanggil dependencies untuk pekerjaan dan tahapan dan berfungsi seperti variabel. Jika Anda merujuk ke variabel output dari pekerjaan di tahap lain, konteksnya disebut stageDependencies.

Jika Anda mengalami masalah dengan variabel output yang memiliki karakter kutipan (' atau ") di dalamnya, lihat panduan pemecahan masalah ini.

Gambaran Umum Sintaksis Dependensi

Sintaks mereferensikan variabel output dengan dependensi bervariasi tergantung pada keadaannya. Berikut adalah gambaran umum skenario yang paling umum. Mungkin ada kalanya sintaks alternatif juga berfungsi.

Jenis

Keterangan

dependensi antara tahap (tahap yang berbeda)

Gunakan variabel output dari tahap sebelumnya di sebuah pekerjaan pada tahap yang berbeda dalam kondisi di stages.

• Sintaks: and(succeeded(), eq(stageDependencies.<stage-name>.outputs['<job-name>.<step-name>.<variable-name>'], 'true'))
• Contoh: and(succeeded(), eq(stageDependencies.A.outputs['A1.printvar.shouldrun'], 'true'))

dependensi pekerjaan ke pekerjaan (pada tahapan yang sama)

Referensikan variabel output dalam pekerjaan yang berbeda dalam tahap yang sama di stages.

• Sintaks: and(succeeded(), eq(dependencies.<job-name>.outputs['<step-name>.<variable-name>'], 'true'))
• Contoh: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))

Pekerjaan untuk mengatur tahapan dependensi (tahapan yang berbeda)

Referensikan variabel output dalam tahap yang berbeda dalam job.

• Sintaks: eq(stageDependencies.<stage-name>.<job-name>.outputs['<step-name>.<variable-name>'], 'true')
• Contoh: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')

Keterkaitan antar tahap (tugas penyebaran)

Variabel output referensi dalam tugas penyebaran dalam tahap yang berbeda di stages.

• Sintaks: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<deployment-job-name>.<step-name>.<variable-name>'], 'true')
• Contoh: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')

Ketergantungan tahap ke tahap (pekerjaan penyebaran dengan sumber daya)

Referensikan variabel output dalam pekerjaan penyebaran yang menyertakan sumber daya dalam tahap yang berbeda di stages.

• Sintaks: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<Deploy_resource-name>.<step-name>.<variable-name>'], 'true')
• Contoh: eq(dependencies.build.outputs['build_job.Deploy_winVM.setRunTests.runTests'], 'true')

Sintaks untuk variabel output dalam tugas penyebaran berbeda-beda tergantung pada strategi penyebaran. Untuk informasi selengkapnya, lihat Tugas penyebaran.

Keterhubungan tahapan ke tahapan ketergantungan

Secara struktural, objek dependencies adalah struktur yang menggambarkan nama pekerjaan dan tahapan ke results dan outputs. Dinyatakan sebagai JSON, terlihat seperti:

"dependencies": {
  "<STAGE_NAME>" : {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
        "jobName.stepName.variableName": "value"
    }
  },
  "...": {
    // another stage
  }
}

Catatan

Contoh berikut menggunakan sintaks alur standar. Jika Anda menggunakan alur penyebaran, sintaks variabel dan variabel bersyarat berbeda. Untuk informasi tentang sintaksis tertentu yang akan digunakan, lihat Pekerjaan penyebaran.

Gunakan bentuk dependencies ini untuk memetakan variabel atau memeriksa kondisi pada tahap.

Dalam contoh ini, ada dua tahap, A dan B. Tahap A memiliki kondisi false dan tidak berjalan. Tahap B berjalan jika hasil Tahap A adalah Succeeded, , SucceededWithIssuesatau Skipped. Tahap B berjalan karena Tahap A diabaikan.

stages:
- stage: A
  condition: false
  jobs:
  - job: A1
    steps:
    - script: echo Job A1
- stage: B
  condition: in(dependencies.A.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
  jobs:
  - job: B1
    steps:
    - script: echo Job B1

Tahapan juga dapat menggunakan variabel output dari tahap lain. Dalam contoh ini, ada dua tahap. Tahap A mencakup pekerjaan, A1, yang mengatur variabel shouldrun output ke true. Tahap B berjalan ketika shouldrun adalah true. Karena shouldrun adalah true, Tahap B dijalankan.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  condition: and(succeeded(), eq(dependencies.A.outputs['A1.printvar.shouldrun'], 'true'))
  dependsOn: A
  jobs:
  - job: B1
    steps:
    - script: echo hello from Stage B

Catatan

Secara default, setiap tahapan dalam alur bergantung pada satu tahapan tepat sebelum tahapan tersebut di file YAML. Jika Anda perlu merujuk ke tahap yang tidak langsung sebelum tahap saat ini, Anda dapat mengubah pengaturan default otomatis ini dengan menambahkan bagian dependsOn ke tahap tersebut.

Dependensi antar pekerjaan dalam satu tahap

Pada tingkat pekerjaan dalam satu tahap, data dependencies tidak berisi informasi pada tingkat tahap.

"dependencies": {
  "<JOB_NAME>": {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
      "stepName.variableName": "value1"
    }
  },
  "...": {
    // another job
  }
}

Dalam contoh ini, ada tiga pekerjaan (a, b, dan c). Pekerjaan a selalu dilewati karena condition: false. Pekerjaan b berjalan karena tidak memiliki kondisi terkait. Pekerjaan c berjalan karena semua dependensinya berhasil (pekerjaan b) atau dilewati (pekerjaan a).

jobs:
- job: a
  condition: false
  steps:
  - script: echo Job a
- job: b
  steps:
  - script: echo Job b
- job: c
  dependsOn:
  - a
  - b
  condition: |
    and
    (
      in(dependencies.a.result, 'Succeeded', 'SucceededWithIssues', 'Skipped'),
      in(dependencies.b.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
    )
  steps:
  - script: echo Job c

Dalam contoh ini, Job B bergantung pada variabel output dari Pekerjaan A.

jobs:
- job: A
  steps:
  - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
  # or on Windows:
  # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
    name: printvar

- job: B
  condition: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

Dependensi antar pekerjaan di berbagai tahap

Pada tingkat pekerjaan, Anda juga dapat mereferensikan output dari pekerjaan di tahap sebelumnya. Ini memerlukan penggunaan stageDependencies konteks.

"stageDependencies": {
  "<STAGE_NAME>" : {
    "<JOB_NAME>": {
      "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
      "outputs": {
          "stepName.variableName": "value"
      }
    },
    "...": {
      // another job
    }
  },
  "...": {
    // another stage
  }
}

Dalam contoh ini, pekerjaan B1 akan berjalan jika pekerjaan A1 dilewati. Job B2 memeriksa nilai variabel output dari pekerjaan A1 untuk menentukan apakah variabel tersebut harus berjalan.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  dependsOn: A
  jobs:
  - job: B1
    condition: in(stageDependencies.A.A1.result, 'Skipped') # change condition to `Succeeded and stage will be skipped`
    steps:
    - script: echo hello from Job B1
  - job: B2
    condition: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')
    steps:
     - script: echo hello from Job B2

Jika pekerjaan bergantung pada variabel yang ditentukan oleh pekerjaan penyebaran dalam tahap yang berbeda, maka sintaksnya berbeda. Dalam contoh berikut, pekerjaan run_tests berjalan jika pekerjaan penerapan build_job diatur runTests ke true. Perhatikan bahwa kunci yang digunakan untuk outputs kamus adalah build_job.setRunTests.runTests.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  jobs:
    - job: run_tests
      condition: eq(stageDependencies.build.build_job.outputs['build_job.setRunTests.runTests'], 'true')
      steps:
        ...

Variabel output pekerjaan penyebaran

Jika tahap tergantung pada variabel yang ditentukan oleh pekerjaan penyebaran dalam tahap yang berbeda, maka sintaksnya berbeda. Dalam contoh berikut, tahap test bergantung pada pengaturan penyebaran build_job untuk shouldTest hingga true. Perhatikan bahwa di condition dari tahap test, build_job muncul dua kali.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')
  jobs:
    - job: A
      steps:
        - script: echo Hello from job A

Dalam contoh di atas, kondisi mereferensikan lingkungan dan bukan sumber daya lingkungan. Untuk mereferensikan sumber daya lingkungan, Anda harus menambahkan nama sumber daya lingkungan ke kondisi dependensi. Dalam contoh berikut, kondisi mereferensikan sumber daya komputer virtual lingkungan bernama vmtest.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: vmtest
      resourceName: winVM2
      resourceType: VirtualMachine
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.Deploy_winVM2.setRunTests.runTests'], 'true')
  jobs:
  - job: A
    steps:
     - script: echo Hello from job A

Array yang difilter

Saat Anda bekerja dengan kumpulan item, gunakan * sintaks untuk menerapkan array yang difilter. Array yang difilter mengembalikan semua objek atau elemen terlepas dari namanya.

Misalnya, pertimbangkan array objek bernama foo. Anda ingin mendapatkan array dari nilai properti id pada setiap objek di dalam array Anda.

[
    { "id": 1, "a": "avalue1"},
    { "id": 2, "a": "avalue2"},
    { "id": 3, "a": "avalue3"}
]

Gunakan ekspresi berikut:

foo.*.id

Ekspresi ini memberi tahu sistem untuk memperlakukan foo sebagai array yang difilter lalu memilih id properti dari setiap objek.

Ekspresi ini mengembalikan:

[ 1, 2, 3 ]

Pengubahan tipe

Nilai dalam ekspresi mungkin dikonversi dari satu jenis ke jenis lainnya saat ekspresi dievaluasi. Saat Anda mengevaluasi ekspresi, proses mengonversi parameter ke jenis data yang relevan lalu mengubahnya kembali menjadi string.

Misalnya, dalam YAML ini, nilai True dan False konversi ke 1 dan 0 saat ekspresi dievaluasi. Fungsi lt() mengembalikan True ketika parameter kiri kurang dari parameter kanan.

variables:
  firstEval: $[lt(False, True)] # 0 vs. 1, True
  secondEval: $[lt(True, False)] # 1 vs. 0, False

steps:
- script: echo $(firstEval)
- script: echo $(secondEval)

Saat Anda menggunakan eq() ekspresi untuk mengevaluasi kesetaraan, nilai secara implisit dikonversi menjadi angka (false ke 0 dan true ke 1).

variables:
  trueAsNumber: $[eq('true', true)] # 1 vs. 1, True
  falseAsNumber: $[eq('false', true)] # 0 vs. 1, False

steps:
- script: echo $(trueAsNumber)
- script: echo $(falseAsNumber)

Dalam contoh berikutnya ini, nilai variables.emptyString dan string kosong dievaluasi sebagai string kosong. Fungsi coalesce() mengevaluasi parameter secara berurutan, dan mengembalikan nilai pertama yang bukan null atau string kosong.

variables:
  coalesceLiteral: $[coalesce(variables.emptyString, '', 'literal value')]

steps:
- script: echo $(coalesceLiteral) # outputs literal value

Aturan konversi terperinci tercantum lebih lanjut di bawah ini.

Dari / Ke	Boolean	Nol	Nomor	string	Versi
Boolean	-	-	Ya	Ya	-
Nol	Ya	-	Ya	Ya	-
Angka	Ya	-	-	Ya	Sebagian
Tali	Ya	Sebagian	Sebagian	-	Sebagian
Versi	Ya	-	-	Ya	-

Boolean

Ke angka:

• False → 0
• True → 1

Untuk string:

• False → 'False'
• True → 'True'

Nol

• Untuk Boolean: False
• Menuju nomor: 0
• Ke string: '' (string kosong)

Nomor

• Ke Boolean: 0 → False, bilangan lainnya → True
• Ke versi: Harus lebih besar dari nol dan harus mengandung angka desimal yang tidak nol. Harus kurang dari Int32.MaxValue (komponen desimal juga).
• Ke string: Mengonversi angka menjadi string tanpa pemisah ribuan atau desimal.

string

• Untuk Boolean: '' (string kosong) → False, string lainnya → True
• Untuk null: '' (string kosong) → Null, string lain yang tidak dapat dikonversi
• Menerjemahkan ke angka: '' (string kosong) menjadi 0, sebaliknya, menjalankan fungsi Int32.TryParse dari bahasa C# menggunakan InvariantCulture dengan aturan berikut: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Jika TryParse gagal, maka tidak dapat dikonversi.
• Ke versi: menjalankan versi C# Version.TryParse. Harus minimal berisi komponen Major dan Minor. Jika TryParse gagal, maka tidak dapat dikonversi.

Versi

• Untuk Boolean: True
• Untuk string: Major.Minor atau Major.Minor.Build atau Major.Minor.Build.Revisi.

FAQ

Saya ingin melakukan sesuatu yang ekspresi tidak mendukung. Opsi apa yang saya miliki untuk memperluas fungsionalitas Alur?

Anda dapat mengkustomisasi alur dengan menggunakan skrip yang menyertakan ekspresi. Misalnya, cuplikan BUILD_BUILDNUMBER ini mengambil variabel dan membaginya dengan menggunakan Bash. Skrip ini menghasilkan dua variabel baru, $MAJOR_RUN dan $MINOR_RUN, untuk nomor eksekusi utama dan minor. Kedua variabel kemudian digunakan untuk membuat dua variabel alur, $major dan $minor dengan menggunakan task.setvariable. Variabel ini tersedia untuk langkah-langkah hilir. Untuk berbagi variabel di seluruh alur, lihat Grup variabel.

steps:
- bash: |
    MAJOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f1)
    echo "This is the major run number: $MAJOR_RUN"
    echo "##vso[task.setvariable variable=major]$MAJOR_RUN"

    MINOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f2)
    echo "This is the minor run number: $MINOR_RUN"
    echo "##vso[task.setvariable variable=minor]$MINOR_RUN"

- bash: echo "My pipeline variable for major run is $(major)"
- bash: echo "My pipeline variable for minor run is $(minor)"