式

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

式のもう 1 つの一般的な用途は、変数の定義です。 式は、コンパイル時または実行時に評価できます。 コンパイル時の式はどこでも使用できます。ランタイム式は変数や条件で使用できます。 ランタイム式は、変数の内容と状態 (例: condition) を計算する方法の 1 つとして使われます。

# 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> ]

ランタイム式とコンパイル時式の構文の違いは、主に使用できるコンテキストです。 コンパイル時式 (${{ <expression> }}) の場合、parameters と静的に定義された variables にアクセスできます。 ランタイム式 ($[ <expression> ]) の場合、より多くの variables にアクセスできますが、パラメーターにはアクセスできません。

この例では、ランタイム式を使って $(isMain) の値を設定しています。 コンパイル式の静的変数を使って $(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

coalesce

• パラメーターを順番 (左から右) に評価し、null または空の文字列と等しくない最初の値を返します。
• パラメーター値がすべて null または空の文字列の場合、値は返されません。
• 最小パラメーター: 2。 最大パラメーター: N
• 例: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• 複合オブジェクトを取得し、JSON として出力します。
• 最小パラメーター: 1。 最大パラメーター: 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) }}

スクリプトの出力:

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

counter

• この関数は、変数を定義する式の中でのみ使用できます。 ステップ、ジョブ、またはステージの条件の一部として使用することはできません。
• パイプラインを実行するたびにインクリメントされる数値を評価します。
• パラメーター: 2。 prefix および seed。
• プレフィックスは文字列式です。 カウンターの個別の値は、プレフィックスの一意の値ごとに追跡されます。 prefix は UTF-16 文字を使う必要があります。
• シードはカウンターの開始値です

パイプラインの各実行で自動的に 1 ずつインクリメントされるカウンターを作成できます。 カウンターを定義するときは、prefix と seed を指定します。 これを示す例はこちらです。

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)

パイプラインの最初の実行に関する上記の例で minor の値は、100 です。 2 回目の実行では、major の値が 1 のままであれば、101 になります。

YAML ファイルを編集して、変数 major の値を 2 に更新すると、パイプラインの次の実行で minor の値は 100 になります。 以降の実行では、カウンターが 101、102、103、... と増えます。

その後、YAML ファイルを編集して major の値を 1 に戻すと、カウンターの値はそのプレフィックスで中断されたところから再開されます。 この例では、102 から再開されます。

100 から始まり、実行ごとに 1 ずつ増分され、毎日 100 にリセットされるカウンターとして機能するように変数を設定する別の例を次に示します。

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

PR と CI 実行に対して個別の値を保持するカウンターを持つ例を次に示します。

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

カウンターのスコープはパイプラインです。 つまり、値は、そのパイプラインの実行ごとにインクリメントされます。 プロジェクトスコープのカウンターはありません。

format

• 末尾のパラメーターを評価し、先頭のパラメーター文字列に挿入します
• 最小パラメーター: 1。 最大パラメーター: N
• 例: format('Hello {0} {1}', 'John', 'Doe')
• 日付形式 (yyyy、yy、MM、M、dd、d、HH、H、m、mm、ss、s、f、ff、ffff、K) に対して、.NET カスタム日付および時間の書式指定子を使います
• 例: format('{0:yyyyMMdd}', pipeline.startTime). この場合、pipeline.startTime は特殊な日時オブジェクト変数です。
• 中かっこを二重にしてエスケープします。 例: format('literal left brace {{ and literal right brace }}')

join

• 右辺のパラメーター配列のすべての要素を、左辺のパラメーター文字列で区切って連結します。
• 最小パラメーター: 2。 最大パラメーター: 2
• 配列の各要素は文字列に変換されます。 複雑なオブジェクトは空の文字列に変換されます。
• 右パラメータが配列でない場合、結果は文字列に変換された右パラメータになります。

この例では、配列の各項目の間にセミコロンが追加されます。 パラメーターの型はオブジェクトです。

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

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

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

lower

• 文字列または変数値をすべて小文字に変換します
• 最小パラメーター: 1。 最大パラメーター: 1
• 文字列を小文字に変換して返します
• 例: lower('FOO') は foo を返します

replace

• 現在のインスタンスに含まれる文字列のすべてのインスタンスを別の文字列で置き換えた新しい文字列を返します。
• 最小パラメーター: 3。 最大パラメーター: 3
• replace(a, b, c): b のすべてのインスタンスを c に置き換えた a を返します
• 例: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (http://server/saml/consume を返します)

split

• 指定された区切り文字に基づいて文字列を部分文字列に分割します
• 最小パラメーター: 2。 最大パラメーター: 2
• 最初のパラメーターは分割する文字列です
• 2 番目のパラメーターは区切り文字です
• 部分文字列の配列を返します。 区切り文字が連続して出現する場合、または文字列の末尾に出現する場合は、この配列には空の文字列が含まれます。
• 例:

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

• split() を 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 }}
  

upper

• 文字列または変数値をすべて大文字に変換します
• 最小パラメーター: 1。 最大パラメーター: 1
• 文字列を大文字に変換して返します
• 例: upper('bah') は BAH を返します

if、elseif、else 句を使って、条件付きで変数値を割り当てたり、タスクの入力を設定したりすることができます。 また、条件を満たした場合に、条件付きでステップを実行することもできます。

if を使って、条件付きで変数値を割り当てたり、タスクの入力を設定したりすることができます。 また、条件を満たした場合に、条件付きでステップを実行することもできます。

elseif 句と else 句は、Azure DevOps 2022 以降で使用できます。Azure DevOps Server 2020 以前のバージョンの Azure DevOps では使用できません。

条件付きでタスク入力を設定する

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'

条件付きでステップを実行する

変数が設定されていない場合、または foo の値が if 条件と一致しない場合は、else ステートメントが実行されます。 ここでは、foo の値が elseif の条件で true を返します。

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"

Each キーワード

each キーワードを使うと、オブジェクト型のパラメーターをループ処理することができます。

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

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

さらに、オブジェクト内の入れ子になった要素を反復処理することもできます。

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

依存関係

式に依存関係コンテキストを使って、前のジョブやステージを参照することができます。 依存関係を使うと、次のことができます。

• 前のジョブのジョブ状態を参照する
• 前のステージのステージ状態を参照する
• 同じステージの前のジョブの出力変数を参照する
• ステージ内で、前のステージの出力変数を参照する
• 次のステージで、前のステージのジョブの出力変数を参照する

このコンテキストは、ジョブとステージでは dependencies と呼ばれ、変数とよく似た機能です。 他のステージのジョブの出力変数を参照する場合、そのコンテキストは stageDependencies と呼ばれます。

出力変数に引用符文字 (' または ") がある場合に問題が発生する場合は、このトラブルシューティング ガイドを参照してください。

依存関係構文の概要

依存関係がある出力変数の参照の構文は、状況によって異なります。 最も一般的なシナリオの概要を次に示します。 別の構文でも機能する場合があります。

デプロイ ジョブの出力変数には、デプロイ戦略に応じて異なる構文もあります。 詳細については、デプロイ ジョブを参照してくだい。

ステージ間の依存関係

構造的に、dependencies オブジェクトは、results と outputs に対するジョブとステージの名前のマップです。 JSON 形式で表現すると、次のようになります。

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

この形式の dependencies を使って、ステージ レベルで変数にマップしたり、条件を確認したりします。

この例では、A と B の 2 つのステージがあります。ステージ A には条件 false があり、結果として実行されることはありません。 ステージ B は、ステージ A の結果が Succeeded、SucceededWithIssues、または Skipped の場合に実行されます。 ステージ A がスキップされたため、ステージ B が実行されます。

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

ステージは、別のステージからの出力変数を使うこともできます。 この例では、2 つのステージもあります。 ステージ A には、出力変数 shouldrun から true を設定するジョブ A1 が含まれています。 ステージ B は、shouldrun が true である場合に実行されます。 shouldrun が true であるため、ステージ B が 実行されます。

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

1 つのステージ内のジョブ間の依存関係

1 つのステージ内のジョブ レベルでは、dependencies データにはステージレベルの情報は含まれません。

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

この例では、3 つのジョブ (a、b、c) があります。 condition: false のため、ジョブ a は常にスキップされます。 関連付けられた条件がないため、ジョブ b が実行されます。 すべての依存関係が成功 (ジョブ b) した、またはスキップ (ジョブ a) されたため、ジョブ c が実行されます。

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

この例では、ジョブ B はジョブ 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

ステージをまたぐジョブ間の依存関係

ジョブ レベルでは、前のステージのジョブからの出力を参照することもできます。 これには、stageDependencies コンテキストを使う必要があります。

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

この例では、ジョブ A1 がスキップされると、ジョブ B1 が実行されます。 ジョブ B2 は、ジョブ A1 からの出力変数の値をチェックして、実行する必要があるかどうかを判断します。

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

ジョブが、別のステージの配置ジョブによって定義された変数に依存する場合、構文は異なります。 次の例では、build_job 配置ジョブによって runTests が true に設定された場合にジョブ run_tests が実行されます。 outputs ディクショナリに使われるキーは 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:
        ...

デプロイ ジョブの出力変数

ステージが、別のステージの配置ジョブによって定義された変数に依存する場合、構文は異なります。 次の例で、ステージ test は、配置の build_job 設定 shouldTest を true に設定することに依存しています。 test ステージの condition では、build_job が 2 回出現することに注目してください。

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

上記の例では、条件は環境リソースではなく環境を参照しています。 環境リソースを参照するには、依存関係の条件に環境リソース名を追加する必要があります。 次の例で、条件は 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