式

[アーティクル]
10/10/2023

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

重要

Select a version from Azure DevOps Content Version selector.

お使いのプラットフォームとバージョンに対応するこの記事のバージョンを選択します。バージョンセレクターは目次の上にあります。 Azure DevOps のプラットフォームとバージョンを検索します。

式は、パイプラインを作成するときに文字列、ブール値、または数値を指定する必要がある多くの場所で使用できます。式から配列が返されると、通常のインデックス作成ルールが適用され、インデックスは 0 で開始します

式の最も一般的な用途は、ジョブまたはステップを実行するかどうかを決定する条件です。

# 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

式は、リテラル、変数への参照、依存関係への参照、関数、または有効な形式で入れ子にしたこれらの組み合わせのいずれかを使用できます。

リテラル

式の一部として、ブール値、null、数値、文字列、バージョンリテラルを使用できます。

# 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 と False はブール値リテラル式です。

[Null]

null は、(variables['noSuch']) のように、ディクショナリのミスから返される特殊なリテラル式です。 null は、式の出力になることはありますが、式の中で直接呼び出すことはできません。

数値

'-'、'.'、または '0' から '9' で始まります。

String

単一引用符で囲む必要があります。 (例: 'this is a string')。

リテラルの一重引用符を表現するには、一重引用符でエスケープします。 (例: 'It''s OK if they''re using contractions.')。

複数行の文字列には、パイプ文字 (|) を使用できます。

myKey: |
  one
  two
  three

バージョン

最大 4 つのセグメントからなるバージョン番号。数字で始まり、ピリオド (.) 文字を 2 つまたは 3 つ含める必要があります。 (例: 1.2.3.4)。

変数

式の一部として、2 つの構文のいずれかを使って変数にアクセスできます。

インデックス構文: variables['MyVar']
プロパティ逆参照構文: variables.MyVar

プロパティ参照外しの構文を使用するには、プロパティ名に次の条件が必要です。

a-Z または _ で始める
その後に a-Z0-9 または _ を続ける

実行コンテキストに応じて、さまざまな変数を使用できます。

YAML を使ってパイプラインを作成する場合、pipeline 変数を使用できます。
クラシックエディターを使ってビルドパイプラインを作成する場合、build 変数を使用できます。
クラシックエディターを使ってリリースパイプラインを作成する場合、release 変数を使用できます。

変数は常に文字列です。型指定された値を使う場合は、パラメーターを代わりに使う必要があります。

注意

変数タブの UI を使ってこのような変数を設定する場合、クラシックパイプラインと YAML パイプラインの両方について、式に変数を使うことに制限があります。式として定義した変数は、値に式が含まれる別の変数に依存しないでください。なぜなら、両方の式が正しく評価されることが保証されないからです。たとえば、変数 a があり、その値 $[ <expression> ] は変数 b の一部として使われています。変数の処理順序は保証されないので、評価後、変数 b の変数 a の値は正しくなくなる可能性があります。

ここで説明した構造は、YAML パイプラインの variables キーワードを使って変数を設定する場合にのみ使用できます。処理後に正しい値を取得するには、処理する順序で変数を配置する必要があります。

関数

式には次の組み込み関数を使用できます。

および

すべてのパラメーターが True の場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: N
評価のためにパラメーターをブール値にキャストします
最初の False 後の短絡
例: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

coalesce

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

contains

左辺のパラメーター文字列に右辺のパラメーターが含まれる場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
評価のためにパラメーターを文字列にキャストします
大文字と小文字を区別しない序数の比較を実行します
例: contains('ABCDE', 'BCD') (True を返します)

containsValue

左辺のパラメーターが配列であり、いずれかの項目が右辺のパラメーターと等しい場合は、True と評価されます。また、左辺のパラメーターがオブジェクトであり、いずれかのプロパティの値が右辺のパラメーターと等しい場合は、True と評価されます。
最小パラメーター: 2。最大パラメーター: 2
左辺のパラメーターが配列の場合、各項目を右辺のパラメーターの型と一致するように変換します。左辺のパラメーターがオブジェクトの場合、各プロパティの値を右辺のパラメーターの型と一致するように変換します。変換に失敗した場合は、個々の項目の等値比較は False と評価されます。
文字列の大文字と小文字を区別しない序数の比較
最初の一致後の短絡

注意

YAML パイプラインには、配列を指定するためのリテラル構文がありません。一般的なパイプラインでは、この関数の使用は制限があります。これは、ステップの一覧などのシステム提供の配列と共に、パイプラインデコレーターのコンテキストで使うことを目的としています。

containsValue 式を使うと、オブジェクトの中から一致する値を見つけることができます。ソースブランチの一覧から 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

複合オブジェクトを取得し、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 になります。 major の値がまだ 1 である場合、2 回目の実行では 101 になります。

YAML ファイルを編集して、変数 major の値を 2 に更新すると、パイプラインの次の実行で minor の値は 100 になります。後続の実行で、カウンターは 101、102、103、... とインクリメントされます。

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

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

注意

pipeline.startTime は式の外では使用できません。 pipeline.startTime は、system.pipelineStartTime を日付と時刻のオブジェクトに書式を設定し、式を操作できるようにします。 pipeline.startTime の既定のタイムゾーンは UTC です。自分の組織のタイムゾーンを変更できます。

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

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

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

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

endsWith

左辺のパラメーター文字列が右辺のパラメーターで終わる場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
評価のためにパラメーターを文字列にキャストします
大文字と小文字を区別しない序数の比較を実行します
例: endsWith('ABCDE', 'DE') (True を返します)

eq

パラメーターが等しい場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
右辺のパラメーターを左辺のパラメーターの型と一致するように変換します。変換に失敗した場合は False を返します。
文字列の大文字と小文字を区別しない序数の比較
例: eq(variables.letters, 'ABC')

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

ge

左辺のパラメーターが右辺のパラメーター以上の場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
右辺のパラメーターを左辺のパラメーターの型と一致するように変換します。変換に失敗した場合はエラー。
文字列の大文字と小文字を区別しない序数の比較
例: ge(5, 5) (True を返します)

gt

左辺のパラメーターが右辺のパラメーターより大きい場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
右辺のパラメーターを左辺のパラメーターの型と一致するように変換します。変換に失敗した場合はエラー。
文字列の大文字と小文字を区別しない序数の比較
例: gt(5, 2) (True を返します)

in

左辺のパラメーターが右辺のいずれかのパラメーターと等しい場合は、True と評価されます
最小パラメーター: 1。最大パラメーター: N
右辺のパラメーターを左辺のパラメーターの型と一致するように変換します。変換に失敗した場合は、等値比較は False と評価されます。
文字列の大文字と小文字を区別しない序数の比較
最初の一致後の短絡
例: in('B', 'A', 'B', 'C') (True を返します)

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

le

左辺のパラメーターが右辺のパラメーター以下の場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
右辺のパラメーターを左辺のパラメーターの型と一致するように変換します。変換に失敗した場合はエラー。
文字列の大文字と小文字を区別しない序数の比較
例: le(2, 2) (True を返します)

length

文字列または配列の長さ (システムから取得したもの、またはパラメーターから取得したもの) を返します
最小パラメーター: 1。最大パラメーター: 1
例: length('fabrikam') は 8 を返します

lower

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

lt

左辺のパラメーターが右辺のパラメーター未満の場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
右辺のパラメーターを左辺のパラメーターの型と一致するように変換します。変換に失敗した場合はエラー。
文字列の大文字と小文字を区別しない序数の比較
例: lt(2, 5) (True を返します)

ne

パラメーターが等しくない場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
右辺のパラメーターを左辺のパラメーターの型と一致するように変換します。変換に失敗した場合は True を返します。
文字列の大文字と小文字を区別しない序数の比較
例: ne(1, 2) (True を返します)

not

パラメーターが False の場合は、True と評価されます
最小パラメーター: 1。最大パラメーター: 1
評価のために値をブール値に変換します
例: not(eq(1, 2)) (True を返します)

notIn

左辺のパラメーターが右辺のいずれかのパラメーターと等しくない場合は、True と評価されます
最小パラメーター: 1。最大パラメーター: N
右辺のパラメーターを左辺のパラメーターの型と一致するように変換します。変換に失敗した場合は、等値比較は False と評価されます。
文字列の大文字と小文字を区別しない序数の比較
最初の一致後の短絡
例: notIn('D', 'A', 'B', 'C') (True を返します)

または

いずれかのパラメーターが True の場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: N
評価のためにパラメーターをブール値にキャストします
最初の True 後の短絡
例: or(eq(1, 1), eq(2, 3)) (True を返します、短絡)

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

startsWith

左辺のパラメーター文字列が右辺のパラメーターから始まる場合は、True と評価されます
最小パラメーター: 2。最大パラメーター: 2
評価のためにパラメーターを文字列にキャストします
大文字と小文字を区別しない序数の比較を実行します
例: startsWith('ABCDE', 'AB') (True を返します)

upper

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

xor

1 つのパラメーターのみが True の場合は True と評価されます
最小パラメーター: 2。最大パラメーター: 2
評価のためにパラメーターをブール値にキャストします
例: xor(True, False) (True を返します)

ジョブ状態チェック関数

次の状態チェック関数は、条件で式として使用できますが、変数定義では使用できません。

常時

常に (取り消された場合でも) True と評価されます。注: 重大な障害が発生した場合でも、タスクの実行が妨げられることがあります。たとえば、ソースの取得に失敗した場合などがそれにあたります。

canceled

パイプラインが取り消された場合は、True と評価されます。

失敗

ステップの場合は eq(variables['Agent.JobStatus'], 'Failed') と同じです
ジョブの場合:
- 引数がない場合、依存関係グラフの前のジョブが失敗した場合にのみ、True と評価されます。
- 引数としてジョブ名を指定した場合、それらのジョブのいずれかが失敗した場合にのみ、True と評価されます。

succeeded

ステップの場合は in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues') と同じです
ジョブを操作するときに、前のジョブが成功したかどうかを評価する場合は、dependsOn と共に使います。ジョブは並列で実行され、ステージは順番に実行されるように設計されています。
ジョブの場合:
- 引数がない場合、依存関係グラフの前のジョブがすべて成功したか、部分的に成功した場合にのみ、True と評価されます。
- 引数としてジョブ名を指定した場合、それらのジョブがすべて成功したか、部分的に成功した場合は、True と評価されます。
- パイプラインが取り消された場合は、False と評価されます。

succeededOrFailed

ステップの場合は in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed') と同じです
ジョブの場合:
- 引数がない場合、依存関係グラフ内のジョブが成功したか失敗したかに関係なく、True と評価されます。
- 引数としてジョブ名を指定した場合、それらのジョブのいずれかが成功したか失敗した場合に True と評価されます。
- 依存関係グラフに前のスキップされたジョブがある場合は、代わりに not(canceled()) を使用できます。
これは always() と似ていますが、パイプラインが取り消されたときに False と評価される点が異なります。

条件付きの挿入

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

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

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

条件は、テンプレート構文を使う場合にのみ機能します。詳細については、変数の構文に関する記事を参照してください。

テンプレートの場合、シーケンスまたはマッピングを追加するときに条件付き挿入を使用できます。詳細については、テンプレートでの条件の挿入に関する記事を参照してください。

条件付きで変数を割り当てる

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

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

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 と呼ばれます。

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

依存関係構文の概要

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

Type

説明

ステージ間の依存関係 (異なるステージ)

stages の条件内の別のステージにあるジョブの前のステージからの出力変数を参照します。

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

ジョブ間の依存関係 (同じステージ)

stages 内の同じステージにある別のジョブの出力変数を参照します。

構文: and(succeeded(), eq(dependencies.<stage-name>.outputs['<step-name>.<variable-name>'], 'true'))
例: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))

ジョブとステージ間の依存関係 (異なるステージ)

job 内の別のステージにある出力変数を参照します。

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

ステージ間の依存関係 (デプロイジョブ)

stages 内の別のステージにあるデプロイジョブの出力変数を参照します。

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

ステージ間の依存関係 (リソースを使用したデプロイジョブ)

stages 内の別のステージにあるリソースを含むデプロイジョブの出力変数を参照します。

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

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

ステージ間の依存関係

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

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

Note

次の例では、標準パイプライン構文を使います。配置パイプラインを使っている場合、変数と条件変数の構文は両方とも異なります。使用する特定の構文の詳細については、「デプロイジョブ」を参照してください。

この形式の 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

Note

既定では、パイプライン内の各ステージは、YAML ファイル内の直前のステージによって異なります。現在のステージの直前ではないステージを参照する必要がある場合は、ステージに dependsOn セクションを追加することで、この自動既定値をオーバーライドできます。

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

フィルター処理された配列

項目のコレクションを操作する場合、* 構文を使ってフィルター処理された配列を適用できます。フィルター処理された配列は、名前に関係なくすべてのオブジェクトと要素を返します。

たとえば、foo というオブジェクトの配列を考えてみましょう。この配列の各オブジェクトに含まれる id プロパティの値の配列を取得する必要があります。

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

次のように実行できます。

foo.*.id

このようにして、foo をフィルター処理された配列として操作してから、id プロパティを選ぶようにシステムに指示します。

これにより、次の結果が返されます。

[ 1, 2, 3 ]

型キャスト

式の値は、式が評価されるときに、ある型から別の型に変換されることがあります。式が評価されるとき、パラメーターは関連するデータ型に結合されてから文字列に戻されます。

たとえば、この YAML では、式が評価されるときに True と False の値は 1 と 0 に変換されます。左辺のパラメーターが右辺のパラメーターより小さい場合、関数 lt() は True を返します。

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

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

この例では、値 variables.emptyString と空の文字列はどちらも空の文字列として評価されます。関数 coalesce() はパラメーターを順番に評価し、null または空の文字列に等しくない最初の値を返します。

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

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

詳細な変換規則を次の一覧にまとめました。

変換元/変換先	Boolean	[Null]	Number	String	バージョン
Boolean	-	-	はい	はい	-
Null	有効	-	イエス	はい	-
Number	はい	-	-	はい	部分的
String	はい	部分的	Partial	-	Partial
Version	はい	-	-	はい	-

Boolean

数値へ:

False → 0
True → 1

文字列へ:

False → 'False'
True → 'True'

[Null]

ブール値へ: False
数値へ: 0
文字列へ: '' (空の文字列)

数値

ブール値へ: 0 → False、その他の数値 → True
バージョンへ: ゼロより大きく、ゼロでない小数が含まれている必要があります。 Int32.MaxValue 未満である必要があります (10 進数コンポーネントも)。
文字列へ: 千単位の区切り記号と小数点の区切り記号がない文字列に数値を変換します。

String

ブール値へ: '' (空の文字列) → False、それ以外の文字列 → True
null へ: '' (空の文字列) → Null、その他の変換できない文字列
数値へ: '' (空の文字列) → 0、それ以外の場合は InvariantCulture と次の規則を使って C# の Int32.TryParse を実行します AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite。 TryParse が失敗した場合、変換できません。
バージョンへ: C# の Version.TryParse を実行します。少なくとも Major コンポーネントと Minor コンポーネントを含める必要があります。 TryParse が失敗した場合、変換できません。

バージョン

ブール値へ: True
文字列へ: Major.Minor または Major.Minor.Build または Major.Minor.Build.Revision。

よく寄せられる質問

式でサポートされていないことをしたいと考えています。 Pipelines の機能を拡張するには、どのようなオプションがありますか?

式を含むスクリプトを使って、Pipeline をカスタマイズできます。たとえば、このスニペットは BUILD_BUILDNUMBER 変数を受け取り、Bash を使って分割しています。このスクリプトは、メジャーとマイナーの実行番号用に $MAJOR_RUN と $MINOR_RUN という 2 つの新しい変数を出力します。この 2 つの変数は、task.setvariable で $major と $minor という 2 つのパイプライン変数を作成するために使われます。これらの変数は、ダウンストリームのステップで使用できます。パイプライン間で変数を共有するには、変数グループに関する記事を参照してください。

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)"

式

リテラル

Boolean

[Null]

数値

String

バージョン

変数

関数

および

coalesce

contains

containsValue

convertToJson

counter

endsWith

eq

format

ge

gt

in

join

le

length

lower

lt

ne

not

notIn

または

replace

split

startsWith

upper

xor

ジョブ状態チェック関数

常時

canceled

失敗

succeeded

succeededOrFailed

条件付きの挿入

条件付きで変数を割り当てる

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

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

Each キーワード

依存関係

依存関係構文の概要

ステージ間の依存関係

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

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

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

フィルター処理された配列

型キャスト

Boolean

[Null]

数値

String

バージョン

よく寄せられる質問

式でサポートされていないことをしたいと考えています。 Pipelines の機能を拡張するには、どのようなオプションがありますか?

フィードバック

フィードバック

その他のリソース

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