Runtime parameters (Parâmetros de runtime)

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

Os parâmetros de tempo de execução oferecem mais controle sobre os valores que você passa para um pipeline. Com parâmetros de tempo de execução, você pode:

• Fornecer valores diferentes para scripts e tarefas em tempo de execução
• Tipos de parâmetros de controle, intervalos permitidos e valores padrão
• Selecione dinamicamente trabalhos e estágios com expressões de modelo

Você pode especificar parâmetros em modelos e no pipeline. Os parâmetros têm tipos de dados, como número e cadeia de caracteres, e podem ser restritos a um subconjunto de valores. A parameters seção em um YAML define quais parâmetros estão disponíveis.

Os parâmetros estão disponíveis apenas durante a análise do modelo. Eles se expandem antes que o pipeline seja executado, substituindo valores cercados por valores de ${{ }} parâmetro. Use variáveis se seus valores precisarem estar disponíveis durante toda a execução do pipeline.

Os parâmetros devem conter um nome e um tipo de dados. Não é possível tornar os parâmetros opcionais. Você precisa atribuir um valor padrão em seu arquivo YAML ou quando você executa seu pipeline. Se você não atribuir um valor padrão ou definir default como false, o primeiro valor disponível será usado.

Use templateContext para passar mais propriedades para estágios, etapas e trabalhos usados como parâmetros em um modelo.

Qual é a diferença entre parâmetros e variáveis?

A tabela a seguir destaca as principais diferenças entre parâmetros e variáveis no Azure Pipelines.

Usar parâmetros em pipelines

Defina parâmetros de tempo de execução no início de um arquivo YAML.

Este pipeline de exemplo inclui um image parâmetro com três agentes hospedados como string opções. Na seção jobs, o pool valor especifica o agente a partir do parâmetro usado para executar o trabalho. O trigger é definido como none para que você possa selecionar o valor de image quando você acionar manualmente o pipeline para ser executado.

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 página de execuções do pipeline, selecione Executar pipeline para executar o pipeline. Você verá a opção para selecionar a Imagem do pool. Se você não fizer uma seleção, a opção ubuntu-latest padrão será usada. Não é possível selecionar uma Imagem de Pool se executar o pipeline a partir do editor YAML.

Use condicionais com parâmetros

Você também pode usar parâmetros como parte da lógica condicional. Com condicionais, uma parte de um YAML é executada se atender aos if critérios.

Usar parâmetros para determinar quais etapas são executadas

Esse pipeline adiciona um segundo parâmetro booleano, test, que controla se os testes devem ser executados no pipeline. Quando o valor de test é true, a etapa que gera Executando todos os testes é executada.

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"

Usar parâmetros para definir qual configuração é usada

Você também pode usar parâmetros para definir qual trabalho é executado. Neste exemplo, diferentes arquiteturas são construídas dependendo do valor do config parâmetro, que é um string tipo. Por omissão, tanto a arquitetura x86 como a x64 são construídas.

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

Excluir seletivamente um estágio

Você também pode usar parâmetros para definir se um estágio é executado. Neste exemplo, há um pipeline com quatro fases e tarefas diferentes para cada fase. O estágio de teste de desempenho é executado se o parâmetro runPerfTests for verdadeiro. O valor padrão de runPerfTests é false, portanto, apenas três dos quatro estágios são executados, a menos que você atualize o valor.

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

Verificar se há um objeto de parâmetro vazio

Use a length()expressão para verificar se um parâmetro object não tem valor.

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

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

Tipos de dados de parâmetros

Os steptipos de dados , stepList, job, jobList, deploymentdeploymentList, stage, stringList, e stageList usam o formato de esquema YAML padrão. Este exemplo inclui string, number, boolean, object, stepe 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}}

Práticas recomendadas de segurança de parâmetros

Ao usar parâmetros de tempo de execução no Azure Pipelines, não passe segredos ou valores confidenciais como entradas de parâmetros. Os valores dos parâmetros são expandidos no momento da análise do modelo e podem ser expostos em logs ou saídas de pipeline.

Sempre valide e restrinja os valores de parâmetros permitidos para evitar a injeção de entradas inesperadas ou inseguras. Siga o princípio do menor privilégio ao conceder acesso aos recursos do pipeline.

Para credenciais, tokens ou outros dados confidenciais, use variáveis de pipeline marcadas como segredos e armazenadas no Cofre de Chaves do Azure, na interface do usuário do Pipeline ou em grupos de variáveis. Para obter mais informações, consulte Proteger segredos no Azure Pipelines.