Parámetros en tiempo de ejecución

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

Los parámetros en tiempo de ejecución proporcionan más control sobre los valores que se pasan a una canalización. Con los parámetros en tiempo de ejecución, puede hacer lo siguiente:

• Proporcionar valores diferentes en scripts y tareas en tiempo de ejecución
• Tipos de parámetros de control, intervalos permitidos y valores predeterminados
• Seleccionar de forma dinámica trabajos y fases con expresiones de plantilla

Puede especificar parámetros en plantillas y en la canalización. Los parámetros tienen tipos de datos, como number y string, y se pueden restringir a un subconjunto de valores. La sección parameters de un YAML define qué parámetros están disponibles.

Los parámetros solo están disponibles durante el análisis de plantillas. Se expanden antes de que se ejecute la canalización, reemplazando los valores rodeados por ${{ }} por valores de parámetros. Usa variables si tus valores necesitan estar disponibles durante toda la ejecución de la canalización.

Los parámetros deben contener un nombre y un tipo de datos. No puede hacer que los parámetros sean opcionales. Debe asignar un valor predeterminado en el archivo YAML o al ejecutar la canalización. Si no asigna ningún valor predeterminado o establece default en false, se usará el primer valor disponible.

Use templateContext para pasar más propiedades a fases, pasos y trabajos usados como parámetros en una plantilla.

¿Cuál es la diferencia entre los parámetros y las variables?

En la tabla siguiente se resaltan las diferencias clave entre los parámetros y las variables de Azure Pipelines.

Uso de parámetros en las canalizaciones

Defina los parámetros de tiempo de ejecución al inicio de un archivo YAML.

Esta canalización de ejemplo incluye un parámetro image con tres agentes hospedados como opciones string. En la sección Trabajos, el valor pool especifica el agente del parámetro usado para ejecutar el trabajo. trigger se establece en Ninguno para poder seleccionar el valor de image cuando desencadene manualmente la canalización para ejecutarla.

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

En la página ejecuciones de canalización, seleccione Ejecutar canalización para ejecutar la canalización. Verá la opción para seleccionar la imagen del Pool. Si no realiza una selección, se usa la opción ubuntu-latest predeterminada. No puedes seleccionar una Imagen de Pool si ejecutas la canalización desde el editor de YAML.

Uso de condicionales con parámetros

También puede usar parámetros como parte de la lógica condicional. Con los condicionales, parte de un YAML se ejecuta si cumple los criterios if.

Uso de parámetros para determinar qué pasos se ejecutan

Esta canalización agrega un segundo parámetro booleano, , testque controla si se deben ejecutar pruebas en la canalización. Cuando el valor de test es true, se ejecuta el paso que genera Ejecutando todas las pruebas.

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"

Uso de parámetros para establecer qué configuración se va a usar

También puede usar parámetros para establecer qué trabajo se va a ejecutar. En este ejemplo, las distintas arquitecturas se basan en el valor del parámetro config, que es un tipo string. De forma predeterminada, las arquitecturas x86 y x64 se compilan.

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 una fase selectivamente

También puede usar parámetros para establecer si se ejecuta una fase. En este ejemplo, hay una canalización con cuatro fases y trabajos diferentes para cada fase. La fase Prueba de rendimiento se ejecuta si el parámetro runPerfTests es true. El valor predeterminado de runPerfTests es false, por lo que solo se ejecutan tres de las cuatro fases a menos que actualice el 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

Buscar un objeto de parámetro vacío

Use la length()expresión para comprobar si un parámetro de objeto no tiene ningún 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 datos de parámetro

Los steptipos de datos , stepList, jobjobList, deploymentdeploymentListstage, stringList, y stageList usan el formato de esquema YAML estándar. En este ejemplo se incluyen string, number, boolean, object, step y 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}}

Procedimientos recomendados de seguridad de parámetros

Al usar parámetros en tiempo de ejecución en Azure Pipelines, no pase secretos ni valores confidenciales como entradas de parámetro. Los valores de parámetro se expanden en el momento de análisis de la plantilla y pueden exponerse en los registros o en las salidas de la canalización.

Valide y restrinja siempre los valores de parámetro permitidos para evitar la inserción de entradas inesperadas o no seguras. Siga el principio de privilegios mínimos al conceder acceso a los recursos de canalización.

Para credenciales, tokens u otros datos confidenciales, use variables de canalización marcadas como secretos y almacenadas en Azure Key Vault, la interfaz de usuario de canalización o grupos de variables. Para más información, consulte Protección de secretos en Azure Pipelines.