Parametry środowiska uruchomieniowego

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

Parametry środowiska uruchomieniowego zapewniają większą kontrolę nad wartościami przekazywanymi do potoku. Za pomocą parametrów środowiska uruchomieniowego można wykonywać następujące czynności:

• Podaj różne wartości skryptów i zadań w czasie wykonywania
• Kontrolowanie typów parametrów, dozwolonych zakresów i wartości domyślnych
• Dynamiczne wybieranie zadań i etapów za pomocą wyrażeń szablonu

Parametry można określić w szablonach i w pipeline. Parametry mają typy danych, takie jak liczba i ciąg, i mogą być ograniczone do podzestawu wartości. Sekcja parameters w języku YAML definiuje, jakie parametry są dostępne.

Parametry są dostępne tylko podczas analizowania szablonów. Rozwijają się przed uruchomieniem potoku, zastępując wartości otoczone znacznikami ${{ }} wartościami parametrów. Użyj zmiennych , jeśli wartości muszą być dostępne w całym przebiegu potoku.

Parametry muszą zawierać nazwę i typ danych. Nie można ustawić parametrów opcjonalnych. Musisz przypisać wartość domyślną w pliku YAML lub przy uruchamianiu potoku. Jeśli nie przypiszesz wartości domyślnej lub ustawisz default wartość falsena , zostanie użyta pierwsza dostępna wartość.

Użyj templateContext, aby przekazać więcej właściwości do etapów, kroków i zadań używanych jako parametry w szablonie.

Jaka jest różnica między parametrami i zmiennymi?

W poniższej tabeli przedstawiono kluczowe różnice między parametrami i zmiennymi w usłudze Azure Pipelines.

Używanie parametrów w potokach

Ustaw parametry środowiska uruchomieniowego na początku pliku YAML.

Ten przykładowy image pipeline zawiera parametr z trzema hostowanymi agentami jako opcje string. W sekcji pool zadań wartość określa agenta z parametru używanego do uruchamiania zadania. Parametr trigger jest ustawiony na brak, aby móc wybrać wartość image podczas ręcznego wyzwalania uruchomienia potoku.

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

Na stronie Przebiegi potoku wybierz pozycję Uruchom potok , aby uruchomić potok. Zostanie wyświetlona opcja wybrania obrazu puli. Jeśli nie wybierzesz opcji, zostanie użyta opcja ubuntu-latest domyślna. Nie można wybrać obrazu puli, jeśli uruchomisz potok w edytorze YAML.

Używanie warunkowych z parametrami

Można również użyć parametrów w ramach logiki warunkowej. Przy użyciu warunków, część pliku YAML jest uruchamiana, jeśli spełnia if kryteria.

Użyj parametrów, aby określić, jakie kroki są uruchamiane

Ten pipeline dodaje drugi parametr logiczny test, który kontroluje, czy uruchamiać testy w tym pipeline. Gdy test jest równe true, wykonywany jest krok, który obejmuje uruchamianie wszystkich testów.

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"

Ustawianie używanej konfiguracji przy użyciu parametrów

Możesz również użyć parametrów, aby ustawić, które zadanie jest uruchamiane. W tym przykładzie różne architektury są kompilowane w zależności od wartości parametru config, który jest typem string. Domyślnie zarówno x86, jak i x64 są budowane.

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

Selektywne wykluczanie etapu

Możesz również użyć parametrów, aby ustawić, czy etap jest uruchamiany. W tym przykładzie istnieje ciąg technologiczny z czterema etapami i różnymi zadaniami dla każdego etapu. Etap testu wydajnościowego jest uruchamiany, jeśli parametr runPerfTests ma wartość true. Wartość domyślna runPerfTests to false, więc tylko trzy z czterech etapów są uruchamiane, chyba że wartość zostanie zaktualizowana.

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

Sprawdzanie pustego obiektu parametru

length() Użyj wyrażenia , aby sprawdzić, czy parametr obiektu nie ma wartości.

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

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

Typy danych parametrów

Typy danych step, stepList, job, jobList, deployment, deploymentList, stage, stringList i stageList wszystkie używają standardowego formatu schematu YAML. Ten przykład obejmuje string, number, boolean, object, step i 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', 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}}

Najlepsze rozwiązania dotyczące zabezpieczeń parametrów

Jeśli używasz parametrów środowiska uruchomieniowego w usłudze Azure Pipelines, nie przekazuj tajnych danych ani wartości poufnych jako danych wejściowych parametrów. Wartości parametrów są rozszerzane w czasie analizowania szablonów i mogą być uwidocznione w dziennikach potoku lub danych wyjściowych.

Zawsze weryfikuj i ograniczaj dozwolone wartości parametrów, aby zapobiec wstrzyknięciu nieoczekiwanych lub niebezpiecznych danych wejściowych. Przestrzegaj zasady najniższych uprawnień podczas udzielania dostępu do zasobów potoku.

W przypadku poświadczeń, tokenów lub innych poufnych danych użyj zmiennych potoku przechowywanych w usłudze Azure Key Vault, w interfejsie użytkownika potoku lub w grupach zmiennych, oznaczonych jako tajne. Aby uzyskać więcej informacji, zobacz Chronienie tajemnic w Azure Pipelines.