ランタイム パラメーター

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

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

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

スクリプト

この例では、パラメーターをループ処理し、各パラメーターの名前と値を出力します。 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

PowerShell

この例では、パラメーターをループ処理し、各パラメーターの名前と値を出力します。 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

stepList パラメーターを使用してステップのリストを動的に含める

この例では、ビルド プロセスにステップのリストを動的に含めるために、stepList パラメーター型を使用します。

• メイン パイプライン (azure-pipelines.yml) では、build と deploy という 2 つのジョブを定義します。
• build ジョブではテンプレート (build.yml) を使用し、stepList パラメーターを使用してビルド タスクのリストを渡します。
• build.yml テンプレートには、build_tasks パラメーターで定義されているステップが動的に含められます。

#azure-pipelines.yml

trigger:
- main

jobs:
  - job: build
    displayName: 'Build .NET Core Application'
    pool:
      vmImage: 'ubuntu-latest'

    steps:
      - checkout: self

      - template: build.yml
        parameters:
          build_tasks:
            - task: DotNetCoreCLI@2
              displayName: 'Restore'
              inputs:
                command: 'restore'
                projects: '**/*.csproj'  

            - task: DotNetCoreCLI@2
              displayName: 'Build'
              inputs:
                command: 'build'
                arguments: '--no-restore'
                projects: '**/*.csproj' 

  - job: deploy
    displayName: 'Pack for Azure App Service deployment'
    dependsOn: build
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - download: current
        artifact: drop

build.yml テンプレート:

• stepList 型と既定の空のリストを使用して、パラメーター build_tasks を定義します。
• .NET Core SDK を 6.x に設定します。
• build_tasks パラメーター内の各ステップを反復処理します。
• build_tasks リストで定義されている各ステップを実行します。

#build.yml

parameters:
  - name: build_tasks
    type: stepList
    default: []

steps:
  - task: UseDotNet@2
    displayName: 'Use .NET Core SDK'
    inputs:
      packageType: 'sdk'
      version: '6.x'

  - ${{ each step in parameters.build_tasks }}:
      - ${{ step }}

  - task: DotNetCoreCLI@2
    displayName: 'Publish'
    inputs:
      command: 'publish'
      arguments: '--configuration Release --output $(Build.ArtifactStagingDirectory)'
      projects: '**/*.csproj'

  - task: PublishBuildArtifacts@1
    displayName: 'Publish Artifact'
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)'
      ArtifactName: 'drop'

パラメーターのデータ型

データ型	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  # Define a parameter named 'myString'
  type: string  # The parameter type is string
  default: a string  # Default value is 'a string'

- name: myMultiString  # Define a parameter named 'myMultiString'
  type: string  # The parameter type is string
  default: default  # Default value is 'default'
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- name: myNumber  # Define a parameter named 'myNumber'
  type: number  # The parameter type is number
  default: 2  # Default value is 2
  values:  # Allowed values for 'myNumber'
  - 1  
  - 2  
  - 4  
  - 8  
  - 16  

- name: myBoolean  # Define a parameter named 'myBoolean'
  type: boolean  # The parameter type is boolean
  default: true  # Default value is true

- name: myObject  # Define a parameter named 'myObject'
  type: object  # The parameter type is object
  default:  # Default value is an object with nested properties
    foo: FOO  # Property 'foo' with value 'FOO'
    bar: BAR  # Property 'bar' with value 'BAR'
    things:  # Property 'things' is a list
    - one  
    - two  
    - three  
    nested:  # Property 'nested' is an object
      one: apple  # Property 'one' with value 'apple'
      two: pear  # Property 'two' with value 'pear'
      count: 3  # Property 'count' with value 3

- name: myStep  # Define a parameter named 'myStep'
  type: step  # The parameter type is step
  default:  # Default value is a step
    script: echo my step 

- name: mySteplist  # Define a parameter named 'mySteplist'
  type: stepList  # The parameter type is stepList
  default:  # Default value is a list of steps
    - script: echo step one  
    - script: echo step two  

trigger: none  

jobs: 
- job: stepList  # Define a job named 'stepList'
  steps: ${{ parameters.mySteplist }}  # Use the steps from the 'mySteplist' parameter

- job: myStep  # Define a job named 'myStep'
  steps:
    - ${{ parameters.myStep }}  # Use the step from the 'myStep' parameter