テンプレート パラメーター

テンプレートでパラメーターとそのデータ型を指定し、パイプラインでそれらのパラメーターを参照できます。 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