Expressions

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

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.

Ekspresi dapat digunakan di banyak tempat di mana Anda perlu menentukan nilai string, boolean, atau 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. Ekspresi dapat dievaluasi pada waktu kompilasi atau pada waktu proses. Ekspresi waktu kompilasi dapat digunakan di mana saja; Ekspresi runtime dapat digunakan dalam variabel dan kondisi. Ekspresi runtime dimaksudkan sebagai cara 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 kompilasi terutama konteks apa yang tersedia. Dalam ekspresi waktu kompilasi (${{ <expression> }}), Anda memiliki akses ke parameters dan ditentukan variablessecara statis . Dalam ekspresi runtime ($[ <expression> ]), Anda memiliki akses ke lebih 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 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.

Null

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.

Number

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

String

Harus dikutip 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 dengan 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 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-9 atau _

Tergantung pada konteks eksekusi, variabel yang berbeda tersedia.

• 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, maka Anda harus menggunakan parameter sebagai gantinya.

Catatan

Ada batasan untuk menggunakan variabel dengan ekspresi untuk alur Klasik dan YAML saat menyiapkan variabel tersebut melalui UI 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.

Konstruksi yang dijelaskan hanya diizinkan saat mengatur variabel melalui kata kunci variabel dalam alur YAML. Diperlukan untuk menempatkan variabel dalam urutan yang harus diproses untuk mendapatkan nilai yang benar setelah diproses.

Fungsi

Fungsi bawaan berikut dapat digunakan dalam ekspresi.

dan

• Mengevaluasi ke True jika semua parameter adalah True
• Parameter min: 2. Parameter maks: 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 tidak sama dengan null atau string kosong.
• Tidak ada nilai yang dikembalikan jika nilai parameter semuanya adalah string null atau kosong.
• Parameter min: 2. Parameter maks: N
• Contoh: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

mengandung

• Mengevaluasi True apakah String parameter kiri berisi parameter kanan
• Parameter min: 2. Parameter maks: 2
• Mentransmisikan parameter ke String untuk evaluasi
• Melakukan perbandingan kasus abaikan ordinal
• Contoh: contains('ABCDE', 'BCD') (mengembalikan True)

containsValue

• Mengevaluasi True apakah parameter kiri adalah array, dan item apa pun sama dengan parameter yang tepat. Juga mengevaluasi True apakah parameter kiri adalah objek, dan nilai properti apa pun sama dengan parameter yang tepat.
• Parameter min: 2. Parameter maks: 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 mengevaluasi False apakah konversi gagal.
• Perbandingan kasus abaikan ordinal untuk String
• Sirkuit pendek setelah pertandingan pertama

Catatan

Tidak ada sintaksis harfiah dalam alur YAML untuk menentukan array. Fungsi ini terbatas dalam alur umum. Ini ditujukan untuk digunakan dalam konteks dekorator alur dengan array yang disediakan sistem seperti daftar langkah-langkah.

Anda dapat menggunakan containsValue ekspresi untuk menemukan nilai yang cocok dalam objek. Berikut adalah contoh yang menunjukkan mencari dalam daftar cabang sumber untuk kecocokan untuk 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"

convertToJson

• Ambil objek yang kompleks dan keluarkan sebagai JSON.
• Parameter min: 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) }}

Output skrip:

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

penghitung

• Fungsi ini hanya dapat digunakan dalam ekspresi yang menentukan variabel. Ini tidak dapat digunakan sebagai bagian dari kondisi untuk langkah, pekerjaan, atau tahapan.
• Mengevaluasi angka yang bertahap dengan setiap eksekusi alur.
• Parameter: 2. prefix dan seed.
• Awalan adalah ekspresi string. Nilai penghitung terpisah dilacak untuk setiap nilai awalan yang unik. prefix harus menggunakan karakter UTF-16.
• Benih adalah nilai awal penghitung

Anda dapat membuat penghitung yang secara otomatis bertambah satu di setiap eksekusi alur Anda. Saat Anda menentukan penghitung, Anda menyediakan prefix dan seed. Berikut adalah contoh yang menunjukkan hal 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 di atas dalam eksekusi pertama alur adalah 100. Dalam eksekusi kedua adalah 101, asalkan nilainya major masih 1.

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

Kemudian, jika Anda mengedit file YAML, dan mengatur nilai major kembali ke 1, maka nilai penghitung dilanjutkan ke tempat yang ditinggalkannya untuk awalan tersebut. Dalam contoh ini, dilanjutkan pada 102.

Berikut adalah contoh lain dari pengaturan variabel untuk bertindak sebagai penghitung yang dimulai dari 100, bertambah 1 untuk setiap eksekusi, dan direset ke 100 setiap hari.

Catatan

pipeline.startTime tidak tersedia di luar ekspresi. pipeline.startTimesystem.pipelineStartTime format ke dalam objek tanggal dan waktu sehingga tersedia untuk bekerja dengan 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)

Berikut adalah contoh memiliki penghitung yang mempertahankan nilai terpisah untuk eksekusi PR dan CI.

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

Penghitung dilingkup ke alur. Dengan kata lain, nilainya bertahap untuk setiap eksekusi alur tersebut. Tidak ada penghitung cakupan proyek.

endsWith

• Mengevaluasi True apakah String parameter kiri berakhir dengan parameter kanan
• Parameter min: 2. Parameter maks: 2
• Mentransmisikan parameter ke String untuk evaluasi
• Melakukan perbandingan kasus abaikan ordinal
• Contoh: endsWith('ABCDE', 'DE') (mengembalikan True)

eq

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

format

• Mengevaluasi parameter berikutnya dan menyisipkannya ke dalam string parameter terkemuka
• Parameter min: 1. Parameter maks: N
• Contoh: format('Hello {0} {1}', 'John', 'Doe')
• Menggunakan penentu tanggal dan waktu kustom .NET untuk pemformatan tanggal (yyyy, , yy, MM, M, ddd, HH, mH, , 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 min: 2. Parameter maks: 2
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Kesalahan jika konversi gagal.
• Perbandingan kasus abaikan ordinal untuk String
• Contoh: ge(5, 5) (mengembalikan True)

gt

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

in

• Mengevaluasi True apakah parameter kiri sama dengan parameter kanan apa pun
• Parameter min: 1. Parameter maks: N
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Perbandingan kesetaraan mengevaluasi False apakah konversi gagal.
• Perbandingan kasus abaikan ordinal untuk String
• Sirkuit pendek setelah pertandingan pertama
• Contoh: in('B', 'A', 'B', 'C') (mengembalikan True)

join

• Menggabungkan semua elemen dalam array parameter kanan, dipisahkan oleh string parameter kiri.
• Parameter min: 2. Parameter maks: 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 min: 2. Parameter maks: 2
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Kesalahan jika konversi gagal.
• Perbandingan kasus abaikan ordinal untuk String
• Contoh: le(2, 2) (mengembalikan True)

length

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

lower

• Mengonversi string atau nilai variabel ke semua karakter huruf kecil
• Parameter min: 1. Parameter maks 1
• Mengembalikan huruf kecil yang setara dengan untai (karakter)
• Contoh: lower('FOO') mengembalikan foo

lt

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

ne

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

not

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

notIn

• Mengevaluasi True apakah parameter kiri tidak sama dengan parameter kanan apa pun
• Parameter min: 1. Parameter maks: N
• Mengonversi parameter kanan untuk mencocokkan jenis parameter kiri. Perbandingan kesetaraan mengevaluasi False apakah konversi gagal.
• Perbandingan kasus abaikan ordinal untuk String
• Sirkuit pendek setelah pertandingan pertama
• Contoh: notIn('D', 'A', 'B', 'C') (mengembalikan True)

or

• Mengevaluasi True apakah ada parameter True
• Parameter min: 2. Parameter maks: N
• Mentransmisikan parameter ke Boolean untuk evaluasi
• Sirkuit pendek setelah pertama True
• Contoh: or(eq(1, 1), eq(2, 3)) (mengembalikan True, short-circuits)

mengganti

• Mengembalikan string baru di mana semua instans string dalam instans saat ini diganti dengan string lain
• Parameter min: 3. Parameter maks: 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 min: 2. Parameter maks: 2
• Parameter pertama adalah string yang akan dipisahkan
• Parameter kedua adalah karakter pembatas
• Mengembalikan array 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

• Mengevaluasi True apakah string parameter kiri dimulai dengan parameter kanan
• Parameter min: 2. Parameter maks: 2
• Mentransmisikan parameter ke String untuk evaluasi
• Melakukan perbandingan kasus abaikan ordinal
• Contoh: startsWith('ABCDE', 'AB') (mengembalikan True)

upper

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

xor

• Mengevaluasi True apakah tepat satu parameter adalah True
• Parameter min: 2. Parameter maks: 2
• Mentransmisikan parameter ke Boolean untuk evaluasi
• Contoh: xor(True, False) (mengembalikan True)

Fungsi pemeriksaan status pekerjaan

Anda dapat menggunakan fungsi pemeriksaan status berikut sebagai ekspresi dalam kondisi, tetapi tidak dalam definisi variabel.

always

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

dibatalkan

• Mengevaluasi ke True jika alur dibatalkan.

gagal

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

berhasil

• Untuk langkah, setara dengan in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
• Gunakan dengan dependsOn saat bekerja dengan pekerjaan dan Anda ingin mengevaluasi apakah pekerjaan sebelumnya berhasil. Pekerjaan dirancang untuk berjalan secara paralel sementara tahapan berjalan secara berurutan.
• Untuk pekerjaan:
  • Tanpa argumen, dievaluasi hanya untuk True jika semua pekerjaan sebelumnya dalam grafik dependensi berhasil atau sebagian berhasil.
  • Dengan nama pekerjaan sebagai argumen, mengevaluasi apakah True semua pekerjaan tersebut berhasil atau sebagian berhasil.
  • Mengevaluasi ke False jika alur dibatalkan.

berhasilOrFailed

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

• Untuk pekerjaan:

  • Tanpa argumen, mengevaluasi terlepas True 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 ada pekerjaan yang dilewati sebelumnya dalam grafik dependensi.

  Ini seperti always(), kecuali akan mengevaluasi False ketika alur dibatalkan.

Penyisipan bersyarah

Anda dapat menggunakan 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 menggunakan sintaks templat. Pelajari selengkapnya tentang sintaks variabel.

Untuk templat, Anda dapat menggunakan penyisipan kondisi saat menambahkan urutan atau pemetaan. Pelajari selengkapnya tentang penyisipan bersyarah 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. Di sini nilai foo mengembalikan true dalam elseif kondisi .

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

Anda dapat menggunakan each kata kunci untuk mengulang parameter dengan jenis objek.

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

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

Selain itu, Anda 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. Anda dapat menggunakan dependensi untuk:

• Mereferensikan status pekerjaan dari pekerjaan sebelumnya
• Mereferensikan status tahap dari tahap sebelumnya
• Variabel output referensi dalam pekerjaan sebelumnya dalam tahap yang sama
• Variabel output referensi pada tahap sebelumnya dalam 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 sintaks 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

tahap ke dependensi tahap (tahap yang berbeda)

Referensikan variabel output dari tahap sebelumnya dalam pekerjaan dalam tahap yang berbeda dalam kondisi di stages.

• Sitnaksis: 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'))

ke dependensi pekerjaan (tahap yang sama)

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

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

Pekerjaan untuk menahapkan dependensi (tahap yang berbeda)

Referensikan variabel output dalam tahap yang berbeda dalam job.

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

Tahap ke dependensi tahap (pekerjaan penyebaran)

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

• Sitnaksis: 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')

Tahap ke dependensi tahap (pekerjaan penyebaran dengan sumber daya)

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

• Sitnaksis: 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')

Ada juga sintaks yang berbeda untuk variabel output dalam pekerjaan penyebaran tergantung pada strategi penyebaran. Untuk informasi selengkapnya, lihat Pekerjaan penyebaran.

Tahap untuk mentahapkan dependensi

Secara struktural, dependencies objek adalah peta nama pekerjaan dan tahap ke results dan outputs. Dinyatakan sebagai JSON, akan 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 akan berbeda. Untuk informasi tentang sintaksis tertentu yang akan digunakan, lihat Pekerjaan penyebaran.

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

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

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 juga 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 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
  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 segera sebelum tahap saat ini, Anda dapat mengambil alih default otomatis ini dengan menambahkan dependsOn bagian ke tahap.

Tugas untuk dependensi pekerjaan dalam satu tahap

Pada tingkat pekerjaan dalam satu tahap, dependencies data tidak berisi informasi 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 akan selalu dilewati karena condition: false. Pekerjaan b berjalan karena tidak ada 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

Pekerjaan untuk dependensi pekerjaan di seluruh 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 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 build_job pekerjaan penyebaran 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 tergantung pada pengaturan shouldTest penyebaran build_job ke true. Perhatikan bahwa di condition test panggung, 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 beroperasi pada kumpulan item, Anda dapat menggunakan * sintaks untuk menerapkan array yang difilter. Array yang difilter mengembalikan semua objek/elemen terlepas dari namanya.

Sebagai contoh, pertimbangkan array objek bernama foo. Kami ingin mendapatkan array nilai id properti di setiap objek dalam array kami.

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

Kita bisa melakukan hal berikut:

foo.*.id

Ini memberi tahu sistem untuk beroperasi sebagai array yang difilter foo lalu memilih id properti .

Ini akan mengembalikan:

[ 1, 2, 3 ]

Pengecoran jenis

Nilai dalam ekspresi dapat dikonversi dari satu jenis ke jenis lainnya saat ekspresi dievaluasi. Saat ekspresi dievaluasi, parameter digabungkan ke jenis data yang relevan lalu diubah kembali menjadi string.

Misalnya, dalam YAML ini, nilai True dan False dikonversi ke 1 dan 0 ketika 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)

Dalam contoh ini, nilai variables.emptyString dan string kosong mengevaluasi sebagai string kosong. Fungsi coalesce() mengevaluasi parameter secara berurutan, dan mengembalikan nilai pertama yang tidak sama dengan null atau empty-string.

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	Null	Number	String	Versi
Boolean	-	-	Ya	Ya	-
Null	Ya	-	Ya	Ya	-
Number	Ya	-	-	Ya	Sebagian
String	Ya	Sebagian	Sebagian	-	Sebagian
Versi	Ya	-	-	Ya	-

Boolean

Ke angka:

• False → 0
• True → 1

Untuk string:

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

Null

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

Number

• Ke Boolean: 0 → False, angka lain → True
• Ke versi: Harus lebih besar dari nol dan harus berisi desimal bukan nol. Harus kurang dari Int32.MaxValue (komponen desimal juga).
• Ke string: Mengonversi angka menjadi string tanpa pemisah ribuan dan tanpa pemisah desimal.

String

• Untuk Boolean: '' (string kosong) → False, string lainnya → True
• Untuk null: '' (string kosong) → Null, string lain yang tidak dapat dikonversi
• Ke angka: '' (string kosong) → 0, jika tidak, menjalankan C#'s Int32.TryParse menggunakan InvariantCulture dan aturan berikut: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Jika TryParse gagal, maka tidak dapat dikonversi.
• Ke versi: menjalankan C#'s Version.TryParse. Harus berisi komponen Mayor dan Minor minimal. 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 tidak didukung oleh ekspresi. Opsi apa yang saya miliki untuk memperluas fungsionalitas Alur?

Anda dapat menyesuaikan Alur Anda dengan skrip yang menyertakan ekspresi. Misalnya, cuplikan BUILD_BUILDNUMBER ini mengambil variabel dan membaginya dengan 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 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)"