ランタイムパラメーター

[アーティクル]
08/08/2024

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

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

次の方法で共有

ランタイムパラメーター

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

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

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

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

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

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

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

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

パラメーターのデータ型

フィードバック

その他のリソース

次の方法で共有

ランタイム パラメーター

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

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

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

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

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

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

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

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

パラメーターのデータ型

フィードバック

その他のリソース

ランタイムパラメーター

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