ランタイム パラメーター

ランタイム パラメーターを使用すると、パイプラインに渡す値を詳細に制御できます。 ランタイム パラメーターを使用すると、次の処理を実行できます。

  • 実行時にスクリプトとタスクに異なる値を指定する
  • 制御パラメーターの型、許可される範囲、および既定値
  • テンプレート式を使用してジョブとステージを動的に選択する

パラメーターは 、テンプレートとパイプライン で指定できます。 パラメーターには数値や文字列などのデータ型が含まれており、値のサブセットに制限できます。 parametersYAML の セクションでは、使用できるパラメーターを定義します。

パラメーターは、テンプレートの解析時にのみ使用できます。 パイプラインが実行される直前にパラメーターが展開され、 で囲まれた値がパラメーター値 ${{ }} に置き換えられる。 パイプライン の実行時に 値を広く使用する必要がある場合は、変数 を使用します

注意

このガイダンスは、クラシック パイプラインには適用されません。 クラシック パイプラインのパラメーターについては、「パラメーターの処理 (クラシック)」を参照してください

パラメーターには、名前とデータ型が含まれている必要があります。 パラメーターは省略可能にすることはできません。 YAML ファイルまたはパイプラインを実行するときに、既定値を割り当てる必要があります。 既定値を割り当てない場合、または を に設定しない場合は、 default false 最初に使用できる値が使用されます。

パイプラインでパラメーターを使用する

YAML の先頭にランタイム パラメーターを設定します。 このサンプル パイプラインは の値を受け取り image 、ジョブの値を出力します。 は none に設定されています。そのため、パイプラインを手動でトリガーして実行するときに の trigger image 値を選択できます。

parameters:
- name: image
  displayName: Pool Image
  type: string
  default: ubuntu-latest
  values:
  - windows-latest
  - vs2017-win2016
  - ubuntu-latest
  - ubuntu-16.04
  - macOS-latest
  - macOS-10.14

trigger: none

jobs:
- job: build
  displayName: build
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber) with ${{ parameters.image }}

パイプラインが実行されると、プール イメージを選択します。 選択しない場合は、既定のオプション である が ubuntu-latest 使用されます。

ランタイム パラメーター

パラメーターで条件を使用する

条件付きロジックの一部としてパラメーターを使用することもできます。 条件では、YAML の一部が条件を満たしている場合にのみ実行 if されます。

パラメーターを使用して実行されるステップを決定する

このパイプラインは、ブール型パラメーターが true の場合にのみステップ test を実行します。

parameters:
- name: image
  displayName: Pool Image
  values:
  - windows-latest
  - vs2017-win2016
  - ubuntu-latest
  - ubuntu-16.04
  - macOS-latest
  - macOS-10.14
- name: test
  displayName: Run Tests?
  type: boolean
  default: false

trigger: none

jobs:
- job: build
  displayName: Build and Test
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber)
  - ${{ if eq(parameters.test, true) }}:
    - script: echo "Running all the tests"

パラメーターを使用して使用する構成を設定する

パラメーターを使用して、どのジョブの実行を設定することもできます。 この例では、 の値に応じて異なるジョブが実行されます config

parameters:
- name: configs
  type: string
  default: 'x86,x64'

trigger: none

jobs:
- ${{ if contains(parameters.configs, 'x86') }}:
  - job: x86
    steps:
    - script: echo Building x86...
- ${{ if contains(parameters.configs, 'x64') }}:
  - job: x64
    steps:
    - script: echo Building x64...
- ${{ if contains(parameters.configs, 'arm') }}:
  - job: arm
    steps:
    - script: echo Building arm...

ステージを選択的に除外する

また、パラメーターを使用して、ステージを実行するかどうかを設定することもできます。 この例では、 パラメーターが true の場合、パフォーマンス テスト ステージが runPerfTests 実行されます。

parameters:
- name: runPerfTests
  type: boolean
  default: false

trigger: none

stages:
- stage: Build
  displayName: Build
  jobs:
  - job: Build
    steps:
    - script: echo running Build


- stage: UnitTest
  displayName: Unit Test
  dependsOn: Build
  jobs:
  - job: UnitTest
    steps:
    - script: echo running UnitTest


- ${{ if eq(parameters.runPerfTests, true) }}:
  - stage: PerfTest
    displayName: Performance Test
    dependsOn: Build
    jobs:
    - job: PerfTest
      steps:
      - script: echo running PerfTest


- stage: Deploy
  displayName: Deploy
  dependsOn: UnitTest
  jobs:
  - job: Deploy
    steps:
    - script: echo running UnitTest

パラメーターをループ処理する

文字列、数値、ブール型パラメーターをループ処理することもできます。

この例では、パラメーターをループ処理し、各パラメーターの名前と値を出力します。

# start.yaml
parameters:
- name: myStringName
  type: string
  default: a string value
- 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

steps: 
- ${{ each parameter in parameters }}:
  - script: echo ${{ parameter.Key }} 
  - script: echo ${{ parameter.Value }}
# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

空のパラメーター オブジェクトを確認する

式を使用 length() して、 オブジェクト パラメーターに値がないかどうかを確認できます。

parameters:
- name: foo
  type: object
  default: []

steps:
- checkout: none
- ${{ if eq(length(parameters.foo), 0) }}:
  - script: echo Foo is empty
    displayName: Foo is empty

パラメーターのデータ型

データ型 メモ
string string
number はに制限される場合があります。それ以外の場合は values: 、任意の数字に似た文字列が許容されます
boolean true または false
object 任意の YAML 構造体
step 1つの手順
stepList 一連の 手順
job 1つのジョブ
jobList ジョブのシーケンス
deployment 単一の展開ジョブ
deploymentList 配置ジョブのシーケンス
stage 1つのステージ
stageList 一連の ステージ

ステップ、stepList、job、jobList、deployment、deploymentList、stage、および stageList の各データ型はすべて、標準の YAML スキーマ形式を使用します。 この例には、文字列、数値、ブール値、オブジェクト、ステップ、および 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 }}

よく寄せられる質問

テンプレート内で変数を使用する方法

変数に基づいてパラメーターを値に設定すると便利な場合があります。 パラメーターはパイプラインの実行の処理の早い段階で拡張 されます 。そのため、すべての変数が使用できるではありません。 テンプレートで使用できる定義済みの変数を確認するには、「定義済みの変数を使用 する」を参照してください

この例では、定義済みの変数 Build.SourceBranch と が Build.Reason template.yml の条件で使用されます。

# File: azure-pipelines.yml
trigger:
- main

extends:
  template: template.yml
# File: template.yml
steps:
- script: echo Build.SourceBranch = $(Build.SourceBranch) # outputs refs/heads/main
- script: echo Build.Reason = $(Build.Reason) # outputs IndividualCI
- ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}: 
  - script: echo I run only if Build.SourceBranch = refs/heads/main 
- ${{ if eq(variables['Build.Reason'], 'IndividualCI') }}: 
  - script: echo I run only if Build.Reason = IndividualCI 
- script: echo I run after the conditions