Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022
運行時間參數可讓您更充分掌控傳遞至管線的值。 使用執行時間參數，您可以：
- 在運行時間為腳本和工作提供不同的值
- 控制參數類型、允許的範圍和預設值
- 使用 範本表示式動態選取作業和階段
您可以在樣本和管線中指定參數。 參數具有數位和字串等數據類型，而且可以限製為值的子集。 YAML 中的 區 parameters 段會定義可用的參數。
參數只能在範本剖析期間使用。 它們會在管線執行之前展開，以參數值取代 所 ${{ }} 包圍的值。 如果您的值需要在整個管線執行中使用，請使用變數。
注意
本指南不適用於傳統管線。 如需傳統管線中的參數，請參閱處理參數（傳統）。
參數必須包含名稱和數據類型。 您無法讓參數成為選擇性參數。 您必須在 YAML 檔案中或執行管線時指派預設值。 如果您未指派預設值或設定 default 為 false，則會使用第一個可用的值。
使用 templateContext 將更多屬性傳遞至範本中做為參數的階段、步驟和作業。
參數和變數之間的差異為何？
下表醒目提示 Azure Pipelines 中參數和變數之間的主要差異。
| 特徵 / 功能 | 參數 | 變數 |
|---|---|---|
| 評估時間 | 樣本剖析 （佇列） | 評估是語法相依的。 以巨集語法 （$(var)） 定義的變數會在運行時間評估工作執行並用於腳本和工作。 以運行時間表示式 （$[variables.var]） 定義的變數會在作業或階段執行之前進行評估，並用於條件或動態變數指派。 |
| 易變性 | 佇列之後不可變 | 使用者定義、環境和輸出變數可以在管線執行期間動態更新 |
| 執行期間UI曝光 | 顯示在執行管線 UI 中，而且可以在執行之前設定 | 如果在管線 UI 中設定為可覆寫，在執行期間公開 |
| 秘密值 | 不支援秘密值 | 可以 設定為秘密 |
在管線中使用參數
在 YAML 檔案的開頭設定運行時間參數。
此範例管線包含具有三個 image 裝載代理程式做為 string 選項的參數。 在 [作業] 區段中， 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 編輯器執行管線，則無法選取集區映射。
搭配參數使用條件式
您也可以使用參數作為條件式邏輯的一部分。 使用條件式時，如果 YAML 符合 if 準則，則會執行部分 YAML。
使用參數來判斷執行哪些步驟
此管線會新增第二個布爾參數， 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"
使用參數來設定所使用的組態
您也可以使用參數來設定要執行的作業。 在此範例中，不同的架構會根據參數的值 config 來建置，這是類型 string 。 根據預設， 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...
選擇性地排除階段
您也可以使用參數來設定階段是否執行。 在此範例中，每個階段都有四個階段和不同作業的管線。 如果 參數 runPerfTests 為 true，效能測試階段就會執行。 的預設值 runPerfTests 為 false，因此除非您更新值，否則四個階段中只有三個執行。
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
檢查空的參數物件
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
參數數據類型
step、stepList、job、 jobListdeploymentdeploymentListstagestringList和 stageList 資料類型全都使用標準 YAML 架構格式。 這個範例包含 string、 number、 boolean、 object、 step和 stepList。
注意
在範本 stringList 中無法使用此數據類型。 請改用模板中的object數據類型。
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', only one default
values: # Allowed values for 'myMultiString'
- default
- ubuntu
- name: myStringlist # Define a parameter named 'myStringlist'
type: stringList # The parameter type is stringList
displayName: Regions
values: # Allowed values for 'myStringlist'
- WUS
- CUS
- EUS
default: # Default values
- WUS
- CUS
- 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
- job: stringList # Define a job named 'stringList'
steps:
- ${{ each region in parameters.myStringlist }}:
- script: echo ${{region}}
參數安全性最佳做法
當您在 Azure Pipelines 中使用運行時間參數時，請勿將秘密或敏感性值當做參數輸入來傳遞。 參數值會在範本剖析時間展開，而且可能會在管線記錄或輸出中公開。
請一律驗證並限制允許的參數值，以防止插入非預期或不安全的輸入。 授與管線資源的存取權時，請遵循最低許可權原則。
針對認證、令牌或其他機密數據，請使用標示為秘密的管線變數，並儲存在 Azure Key Vault、管線 UI 或變數群組中。 如需詳細資訊，請參閱 保護 Azure Pipelines 中的秘密。