テンプレート パラメーター
テンプレートでパラメーターとそのデータ型を指定し、パイプラインでそれらのパラメーターを参照できます。 templateContext を使用すると、テンプレートのパラメーターとして使用されるステージ、ステップ、ジョブにプロパティを渡すこともできます。
テンプレートの外部でパラメーターを使用することもできます。 パラメーターの既定値にはリテラルのみを使用できます。 YAML スキーマのパラメーターについて説明します。
パラメーターを渡す
パラメーターには、名前とデータ型が含まれている必要があります。 azure-pipelines.yml
では、パラメーター yesNo
がブール値に設定されている場合、ビルドは成功します。 yesNo
が apples
などの文字列に設定されている場合、ビルドは失敗します。
# File: simple-param.yml
parameters:
- name: yesNo # name of the parameter; required
type: boolean # data type of the parameter; required
default: false
steps:
- script: echo ${{ parameters.yesNo }}
# File: azure-pipelines.yml
trigger:
- main
extends:
template: simple-param.yml
parameters:
yesNo: false # set to a non-boolean value to have the build fail
templateContext を使用してテンプレートにプロパティを渡す
templateContext
を使用して、テンプレートのパラメータとして使用されるプロパティをさらにステージ、ステップ、ジョブに渡すことができます。 具体的には、jobList
、deploymentList
、stageList
パラメーターのデータ型内で templateContext
を指定できます。
templateContext
を使用すると、各ジョブを処理するときに環境設定を簡単に行えます。 templateContext
でジョブとその環境プロパティ オブジェクトをバンドルすることで、YAML の保守と理解が容易になります。
この例では、testing-template.yml
のパラメーター testSet
のデータ型は jobList
です。 テンプレート testing-template.yml
では 各キーワードを使用して新しい変数 testJob
を作成します。 その後、テンプレートでは testJob.templateContext.expectedHTTPResponseCode
を参照し、これが azure-pipeline.yml
に設定され、テンプレートに渡されます。
応答コードが 200 の場合、テンプレートでは REST 要求を行います。 応答コードが 500 の場合、テンプレートではデバッグ用にすべての環境変数を出力します。
templateContext
にはプロパティを含めることができます。
#testing-template.yml
parameters:
- name: testSet
type: jobList
jobs:
- ${{ each testJob in parameters.testSet }}:
- ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 200) }}:
- job:
steps:
- powershell: 'Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ | Format-Table -Property Title, pubDate'
- ${{ testJob.steps }}
- ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 500) }}:
- job:
steps:
- powershell: 'Get-ChildItem -Path Env:\'
- ${{ testJob.steps }}
#azure-pipeline.yml
trigger: none
pool:
vmImage: ubuntu-latest
extends:
template: testing-template.yml
parameters:
testSet:
- job: positive_test
templateContext:
expectedHTTPResponseCode: 200
steps:
- script: echo "Run positive test"
- job: negative_test
templateContext:
expectedHTTPResponseCode: 500
steps:
- script: echo "Run negative test"
実行時にテンプレートを選ぶためのパラメーター
条件に応じて、パイプライン YAML から異なるテンプレートを呼び出すことができます。 この例では、experimentalTemplate
パラメータが true の場合に experimental.yml
YAML が実行されます。
#azure-pipeline.yml
parameters:
- name: experimentalTemplate
displayName: 'Use experimental build process?'
type: boolean
default: false
steps:
- ${{ if eq(parameters.experimentalTemplate, true) }}:
- template: experimental.yml
- ${{ if not(eq(parameters.experimentalTemplate, true)) }}:
- template: stable.yml
パラメーターのデータ型
データ型 | Notes |
---|---|
string |
string |
number |
values: に制限される場合があります。それ以外の場合は、任意の数値のような文字列が受け入れられます |
boolean |
true または false |
object |
任意の YAML 構造体 |
step |
1 つのステップ |
stepList |
ステップのシーケンス |
job |
1 つのジョブ |
jobList |
ジョブのシーケンス |
deployment |
1 つの配置ジョブ |
deploymentList |
配置ジョブのシーケンス |
stage |
1 つのステージ |
stageList |
ステージのシーケンス |
step、stepList、job、jobList、deployment、deploymentList、stage、stageList のデータ型ではすべて、標準の YAML スキーマ形式を使用します。 この例には、string、number、boolean、object、step、stepList が含まれています。
parameters:
- name: myString
type: string
default: a string
- name: myMultiString
type: string
default: default
values:
- default
- ubuntu
- name: myNumber
type: number
default: 2
values:
- 1
- 2
- 4
- 8
- 16
- name: myBoolean
type: boolean
default: true
- name: myObject
type: object
default:
foo: FOO
bar: BAR
things:
- one
- two
- three
nested:
one: apple
two: pear
count: 3
- name: myStep
type: step
default:
script: echo my step
- name: mySteplist
type: stepList
default:
- script: echo step one
- script: echo step two
trigger: none
jobs:
- job: stepList
steps: ${{ parameters.mySteplist }}
- job: myStep
steps:
- ${{ parameters.myStep }}
オブジェクトを反復処理し、オブジェクト内の各文字列を出力できます。
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 }}
必須のパラメーター
テンプレートの冒頭に検証ステップを追加して、必要なパラメーターをチェックできます。
Bash を使用して solution
パラメーターをチェックする例を次に示します (これにより、あらゆるプラットフォームで動作できるようになります)。
# File: steps/msbuild.yml
parameters:
- name: 'solution'
default: ''
type: string
steps:
- bash: |
if [ -z "$SOLUTION" ]; then
echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
echo "##vso[task.complete result=Failed;]"
fi
env:
SOLUTION: ${{ parameters.solution }}
displayName: Check for required parameters
- task: msbuild@1
inputs:
solution: ${{ parameters.solution }}
- task: vstest@2
inputs:
solution: ${{ parameters.solution }}
必要なパラメーターがない場合、テンプレートが失敗することを示すには、次のようにします。
# File: azure-pipelines.yml
# This will fail since it doesn't set the "solution" parameter to anything,
# so the template will use its default of an empty string
steps:
- template: steps/msbuild.yml
テンプレートにパラメーターを渡すことができます。
parameters
セクションでは、テンプレートで使用できるパラメーターとその既定値を定義します。
テンプレートはパイプラインが実行される直前に展開され、${{ }}
で囲まれた値が、外側のパイプラインから受け取るパラメーターに置き換えられます。 その結果、定義済みの変数のみをパラメーターで使用できます。
複数のパイプラインでパラメーターを使用するには、変数グループを作成する方法を参照してください。
パラメーターを含むジョブ、ステージ、ステップのテンプレート
# File: templates/npm-with-params.yml
parameters:
name: '' # defaults for any parameters that aren't specified
vmImage: ''
jobs:
- job: ${{ parameters.name }}
pool:
vmImage: ${{ parameters.vmImage }}
steps:
- script: npm install
- script: npm test
パイプラインでテンプレートを使用する場合は、テンプレート パラメーターの値を指定します。
# File: azure-pipelines.yml
jobs:
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Linux
vmImage: 'ubuntu-latest'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: macOS
vmImage: 'macOS-10.13'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Windows
vmImage: 'windows-latest'
ステップ テンプレートまたはステージ テンプレートでパラメーターを使用することもできます。 たとえば、パラメーターを含むステップは次のようになります。
# File: templates/steps-with-params.yml
parameters:
runExtendedTests: 'false' # defaults for any parameters that aren't specified
steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, 'true') }}:
- script: npm test --extended
パイプラインでテンプレートを使用する場合は、テンプレート パラメーターの値を指定します。
# File: azure-pipelines.yml
steps:
- script: npm install
- template: templates/steps-with-params.yml # Template reference
parameters:
runExtendedTests: 'true'
注意
スカラー パラメーターは、常に文字列として扱われます。
たとえば、eq(parameters['myparam'], true)
では、myparam
パラメーターが false
という単語であっても、ほぼ必ず true
を返します。
空でない文字列は、ブール型のコンテキストで true
にキャストされます。
その式を書き直して、文字列を明示的に比較できます: eq(parameters['myparam'], 'true')
。
パラメーターはスカラー文字列に限定されません。 パラメーターが展開される場所でマッピングが想定されている限り、パラメーターをマッピングにすることができます。 同様に、シーケンスが必要な場所ではシーケンスを渡すことができます。 次に例を示します。
# azure-pipelines.yml
jobs:
- template: process.yml
parameters:
pool: # this parameter is called `pool`
vmImage: ubuntu-latest # and it's a mapping rather than a string
# process.yml
parameters:
pool: {}
jobs:
- job: build
pool: ${{ parameters.pool }}