ランタイムパラメーター

[アーティクル]
07/03/2023

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

ランタイムパラメーターを使用すると、パイプラインに渡すことができる値をより細かく制御できます。ランタイムパラメーターを使用すると、次のことができます。

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

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

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

注意

このガイダンスは、クラシックパイプラインには適用されません。クラシックパイプラインのパラメーターについては、プロセスパラメーター (クラシック)に関する記事を参照してください。

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

templateContext を使用して、テンプレートのパラメーターとして使用されるステージ、ステップ、ジョブにプロパティを渡します。

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

YAML の先頭にランタイムパラメーターを設定します。

このパイプラインの例には、string オプションとして 3 つのホステッドエージェントを含む image パラメーターが含まれています。ジョブセクションの pool 値では、ジョブの実行に使用されるパラメーターのエージェントを指定します。 trigger は none に設定されているため、パイプラインの実行を手動でトリガーするときに image の値を選択できます。

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

trigger: none

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

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

ランタイムパラメーター

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

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

パラメーターを使用して実行する手順を決定する

このパイプラインでは、パイプラインでテストを実行するかどうかを制御するために使用できる 2 番目のブール型パラメーター test を追加します。 test の値が true の場合、すべてのテストの実行 を出力するステップが実行されます。

parameters:
- name: image
  displayName: Pool Image
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest
- 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"

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

パラメーターを使用して、実行するジョブを設定することもできます。この例では、string 型の config パラメーターの値に応じて、アーキテクチャが異なります。既定では、x86 と x64 の両方のアーキテクチャがビルドされます。

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

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

パラメーターを使用して、ステージを実行するかどうかを設定することもできます。この例では、ステージごとに 4 つのステージと異なるジョブを含むパイプラインがあります。パラメーター runPerfTests が true の場合、パフォーマンステストステージが実行されます。 runPerfTests の既定値は false であるため、更新されずに、4 つのステージのうち 3 つだけが実行されます。

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

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

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

スクリプト
PowerShell

この例では、パラメーターをループ処理し、各パラメーターの名前と値を出力します。 4 つの異なるパラメーターがあり、それぞれが異なる型を表します。 myStringName は 1 行の文字列です。 myMultiString は複数行の文字列です。 myNumber is a number。 myBoolean はブール値です。ステップセクションでは、スクリプトタスクによって各パラメーターのキーと値が出力されます。

# 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

この例では、パラメーターをループ処理し、各パラメーターの名前と値を出力します。 4 つの異なるパラメーターがあり、それぞれが異なる型を表します。 myStringName は 1 行の文字列です。 myMultiString は複数行の文字列です。 myNumber is a number。 myBoolean はブール値です。ステップセクションでは、PowerShell タスクのパラメーターをループ処理し、各パラメーターを環境変数として設定します。

# 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: 
  - task: PowerShell@2
    env:
      ${{ each parameter in parameters }}:
        ${{ parameter.Key }}: ${{ parameter.Value }}
    inputs:
      filePath: test_script.ps1
      pwsh: true

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

# test_script.ps1

Write-Host "Hello, World!"
Write-Host $env:myStringName

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

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

パラメーターのデータ型

データ型	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 }}

ランタイムパラメーター

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

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

パラメーターを使用して実行する手順を決定する

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

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

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

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

パラメーターのデータ型

フィードバック

フィードバック

その他のリソース

ランタイム パラメーター

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

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

パラメーターを使用して実行する手順を決定する

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

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

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

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

パラメーターのデータ型

フィードバック

フィードバック

その他のリソース

ランタイムパラメーター

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