Выражения

# Expressions are used to define conditions for a step, job, or stage
steps:
- task: ...
  condition: <expression>

Другое частое использование выражений заключается в определении переменных. Выражения можно оценивать во время компиляции или во время выполнения. Выражения времени компиляции можно использовать в любом месте; Выражения среды выполнения можно использовать в переменных и условиях. Выражения среды выполнения предназначены для вычисления содержимого переменных и состояний (например: condition).

# Two examples of expressions used to define variables
# The first one, a, is evaluated when the YAML file is compiled into a plan.
# The second one, b, is evaluated at runtime.
# Note the syntax ${{}} for compile time and $[] for runtime expressions.
variables:
  a: ${{ <expression> }}
  b: $[ <expression> ]

Разница между синтаксисами выражений времени выполнения и компиляции состоит в первую очередь в том, какой контекст доступен. В выражении времени компиляции (${{ <expression> }}) у вас есть доступ к parameters и статически определенному variables. В выражении среды выполнения ($[ <expression> ]) вы получаете доступ к большему количеству возможностей variables, но не имеете доступа к параметрам.

В этом примере выражение среды выполнения задает значение $(isMain). В выражении компиляции статическая переменная задает значение $(compileVar).

variables:
  staticVar: 'my value' # static variable
  compileVar: ${{ variables.staticVar }} # compile time expression
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')] # runtime expression

steps:
  - script: |
      echo ${{variables.staticVar}} # outputs my value
      echo $(compileVar) # outputs my value
      echo $(isMain) # outputs True

объединяться

• Вычисляет параметры в порядке (слева направо) и возвращает первое значение, которое не равно null или пустой строке.
• Значение не возвращается, если все значения параметров имеют значение NULL или пустые строки.
• Минимальные параметры: 2. Максимальные параметры: N
• Пример: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• Брать сложный объект и формировать его в формате JSON.
• Минимальные параметры: 1. Максимальные параметры: 1.

parameters:
  - name: listOfValues
    type: object
    default:
      this_is:
        a_complex: object
        with:
          - one
          - two

steps:
- script: |
    echo "${MY_JSON}"
  env:
    MY_JSON: ${{ convertToJson(parameters.listOfValues) }}

Выходные данные скрипта:

{
  "this_is": {
    "a_complex": "object",
    "with": [
      "one",
      "two"
    ]
  }
}

счетчик людей

• Эта функция может использоваться только в выражении, определяющем переменную. Его нельзя использовать как часть условия для шага, задания или этапа.
• Вычисляет число, которое увеличивается при каждом запуске конвейера.
• Параметры: 2. prefix и seed.
• Префикс — это строковое выражение. Отдельное значение счетчика отслеживается для каждого уникального значения префикса. Элемент prefix должен использовать символы UTF-16.
• Начальное значение счетчика — это seed.

Вы можете создать счётчик, который будет автоматически увеличиваться на единицу при каждом выполнении вашего конвейера. При определении счетчика необходимо указать prefix и .seed Ниже приведен пример, демонстрирующий это.

variables:
  major: 1
  # define minor as a counter with the prefix as variable major, and seed as 100.
  minor: $[counter(variables['major'], 100)]

steps:
- bash: echo $(minor)

Значение minor в приведенном выше примере в первом запуске конвейера равно 100. Во втором запуске значение равно 101, если значение major по-прежнему равно 1.

Если изменить файл YAML и обновить значение переменной major до 2, то в следующем запуске конвейера значение minor будет равно 100. Последующие запуски увеличивают счетчик до 101, 102, 103, ...

Позже, если вы отредактируете файл YAML и снова установите значение major на 1, то значение счетчика продолжит с того места, где оно остановилось для этого префикса. В этом примере оно возобновляется на отметке 102.

Вот еще один пример установки переменной в качестве счетчика, который начинается со 100, увеличивается на 1 при каждом запуске и сбрасывается до 100 каждый день.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Вот пример счетчика, который поддерживает отдельное значение для PR и CI запусков.

variables:
  patch: $[counter(variables['build.reason'], 0)]

Счетчики используются в контексте конвейера. Другими словами, его значение увеличивается для каждого запуска этого конвейера. Отсутствуют счетчики, привязанные к проекту.

формат

• Оценивает последующие параметры и вставляет их в строку параметров начального уровня.
• Минимальные параметры: 1. Максимальные параметры: N
• Пример: format('Hello {0} {1}', 'John', 'Doe')
• Использует настраиваемые описатели формата даты и времени .NET для форматирования дат (yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff, K)
• Пример: format('{0:yyyyMMdd}', pipeline.startTime). В этом случае pipeline.startTime это специальная переменная объекта времени даты.
• Побег, удвоив фигурные скобки. Например: format('literal left brace {{ and literal right brace }}')

ИИФ

• Возвращает второй параметр, если первый параметр вычисляется как True, а в противном случае третий параметр.
• Минимальные параметры: 1. Максимальные параметры: 3
• Первый параметр должен быть условием
• Пример: iif(eq(variables['Build.Reason'], 'PullRequest'), 'ManagedDevOpsPool', 'Azure Pipelines') возвращает "ManagedDevOpsPool" при выполнении пиплайна в ответ на PR.

присоединиться

• Объединяет все элементы в массиве правого параметра, используя строку левого параметра в качестве разделителя.
• Минимальные параметры: 2. Максимальные параметры: 2
• Каждый элемент в массиве преобразуется в строку. Сложные объекты преобразуются в пустую строку.
• Если правильный параметр не является массивом, результатом является правильный параметр, преобразованный в строку.

В этом примере точка с запятой добавляется между каждым элементом в массиве. Тип параметра — это объект.

parameters:
- name: myArray
  type: object
  default:
    - FOO
    - BAR
    - ZOO

variables:
   A: ${{ join(';',parameters.myArray) }}

steps:
  - script: echo $A # outputs FOO;BAR;ZOO

ниже

• Преобразует строковое или переменное значение во все строчные символы
• Минимальные параметры: 1. Максимальные параметры 1
• Возвращает строчные буквы, эквивалентные строке
• Пример: lower('FOO') возвращается foo

заменить

• Возвращает новую строку, в которой все экземпляры строки в текущем экземпляре заменяются другой строкой.
• Минимальные параметры: 3. Максимальные параметры: 3
• replace(a, b, c): возвращает a, при этом все вхождения b заменены на c
• Пример: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (возвращается http://server/saml/consume)

разделить

• Разбивает строку на подстроки на основе указанных символов разделителя
• Минимальные параметры: 2. Максимальные параметры: 2
• Первый параметр — это строка для разделения
• Второй параметр — символы разделителя
• Возвращает массив подстроок. Массив включает пустые строки, когда символы разделителя отображаются последовательно или в конце строки
• Пример:

  variables:
  - name: environments
    value: prod1,prod2
  steps:
    - ${{ each env in split(variables.environments, ',')}}:
      - script: ./deploy.sh --environment ${{ env }}
  

• Пример использования split() с replace():

  parameters:
  - name: resourceIds
    type: object
    default:
    - /subscriptions/mysubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/loadBalancers/kubernetes-internal
    - /subscriptions/mysubscription02/resourceGroups/myResourceGroup02/providers/Microsoft.Network/loadBalancers/kubernetes
  - name: environments
    type: object
    default:
    - prod1
    - prod2
  
  trigger:
  - main
  
  steps:
  - ${{ each env in parameters.environments }}:
    - ${{ each resourceId in parameters.resourceIds }}:
        - script: echo ${{ replace(split(resourceId, '/')[8], '-', '_') }}_${{ env }}
  

подстригать

• Возвращает значение параметра без начальных и конечных пробелов
• Минимальные параметры: 1. Максимальные параметры: 1
• Пример: trim(' variable ') возвращает значение "переменная"

верхний

• Преобразует строковое или переменное значение во все символы верхнего регистра
• Минимальные параметры: 1. Максимальные параметры 1
• Возвращает эквивалент строки в верхнем регистре.
• Пример: upper('bah') возвращается BAH

Можно использовать if, elseif, и else условные выражения для условного назначения значений переменных или задания входных данных для задач. При выполнении условия можно также выполнить шаг условно.

Можно использовать if для условного назначения значений переменных или задания входных данных для задач. При выполнении условия можно также выполнить шаг условно.

elseif и else условия доступны начиная с версии Azure DevOps 2022 и недоступны для Azure DevOps Server 2020 и более ранних версий.

Условно задать входные данные задачи

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Pipeline.Workspace)'
    ${{ if eq(variables['Build.SourceBranchName'], 'main') }}:
      artifact: 'prod'
    ${{ else }}:
      artifact: 'dev'
    publishLocation: 'pipeline'

Условное выполнение шага

Если переменная не задана или значение foo не соответствует if условиям, else инструкция выполняется. Здесь значение foo возвращает true в условии elseif.

variables:
  - name: foo
    value: contoso # triggers elseif condition

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start"
- ${{ if eq(variables.foo, 'adaptum') }}:
  - script: echo "this is adaptum"
- ${{ elseif eq(variables.foo, 'contoso') }}: # true
  - script: echo "this is contoso"
- ${{ else }}:
  - script: echo "the value is not adaptum or contoso"

Каждое ключевое слово

Ключевое слово each можно использовать для перебора параметров с типом объекта.

parameters:
- name: listOfStrings
  type: object
  default:
  - one
  - two

steps:
- ${{ each value in parameters.listOfStrings }}:
  - script: echo ${{ value }}

Кроме того, можно итерировать вложенные элементы в объекте.

parameters:
- name: listOfFruits
  type: object
  default:
  - fruitName: 'apple'
    colors: ['red','green']
  - fruitName: 'lemon'
    colors: ['yellow']
steps:
- ${{ each fruit in parameters.listOfFruits }} :
  - ${{ each fruitColor in fruit.colors}} :
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }}

Зависимости

Выражения могут использовать контекст зависимостей для ссылки на предыдущие задания или этапы. Для этого можно использовать зависимости:

• Обратите внимание на статус предыдущей работы
• Ссылка на статус предыдущего этапа
• Ссылка на выходные переменные в предыдущем задании в том же этапе
• Ссылайтесь на выходные переменные с предыдущего этапа в текущем этапе.
• Используйте выходные переменные задания из предыдущего этапа на следующем этапе.

Контекст называется dependencies для заданий и этапов и функционирует так же, как переменные. Если вы ссылаетесь на выходную переменную из задания на другой стадии, этот контекст называется stageDependencies.

Если возникают проблемы с выходными переменными с символами кавычки (' или ") в них, ознакомьтесь с этим руководством по устранению неполадок.

Общие сведения о синтаксисе зависимостей

Синтаксис ссылки на выходные переменные с зависимостями зависит от обстоятельств. Ниже приведен обзор наиболее распространенных сценариев. Иногда также работает альтернативный синтаксис.

Существуют также различные синтаксисы выходных переменных в заданиях развертывания в зависимости от стратегии развертывания. Дополнительные сведения см. в разделе "Задания развертывания".

Этап к этапу зависимостей

Структурно, объект dependencies представляет собой отображение имен заданий и этапов к results и outputs. Выражение в формате JSON будет выглядеть следующим образом:

"dependencies": {
  "<STAGE_NAME>" : {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
        "jobName.stepName.variableName": "value"
    }
  },
  "...": {
    // another stage
  }
}

Используйте эту форму dependencies для сопоставления переменных или проверки условий на уровне этапа.

В этом примере есть два этапа, A и B. Этап A имеет условие false и никогда не будет выполняться в итоге. Этап B выполняется, если результат этапа A имеет Succeededзначение , SucceededWithIssuesили Skipped. Этап B выполняется, так как этап A пропущен.

stages:
- stage: A
  condition: false
  jobs:
  - job: A1
    steps:
    - script: echo Job A1
- stage: B
  condition: in(dependencies.A.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
  jobs:
  - job: B1
    steps:
    - script: echo Job B1

Этапы также могут использовать выходные переменные из другого этапа. В этом примере также существует два этапа. Этап A включает задание A1, которое задает значение выходной переменной shouldrun равным true. Этап B выполняется, когда shouldrun находится в состоянии true. Поскольку shouldrun является true, выполняется этап B.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  condition: and(succeeded(), eq(dependencies.A.outputs['A1.printvar.shouldrun'], 'true'))
  dependsOn: A
  jobs:
  - job: B1
    steps:
    - script: echo hello from Stage B

Зависимости между заданиями в одном этапе

На уровне задачи в пределах одного этапа данные dependencies не содержат информации на уровне стадии.

"dependencies": {
  "<JOB_NAME>": {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
      "stepName.variableName": "value1"
    }
  },
  "...": {
    // another job
  }
}

В этом примере есть три задания (a, b и c). Задание всегда пропускается из-за condition: false. Задание b выполняется из-за отсутствия связанных условий. Задание c выполняется, если все его зависимости либо успешно выполнены (задание b), либо пропущены (задание a).

jobs:
- job: a
  condition: false
  steps:
  - script: echo Job a
- job: b
  steps:
  - script: echo Job b
- job: c
  dependsOn:
  - a
  - b
  condition: |
    and
    (
      in(dependencies.a.result, 'Succeeded', 'SucceededWithIssues', 'Skipped'),
      in(dependencies.b.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
    )
  steps:
  - script: echo Job c

В этом примере задание B зависит от выходной переменной задания A.

jobs:
- job: A
  steps:
  - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
  # or on Windows:
  # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
    name: printvar

- job: B
  condition: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

Зависимости между задачами на различных этапах

На уровне задания вы можете также ссылаться на выходные данные задания на предыдущем этапе. Для этого требуется использование контекста stageDependencies .

"stageDependencies": {
  "<STAGE_NAME>" : {
    "<JOB_NAME>": {
      "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
      "outputs": {
          "stepName.variableName": "value"
      }
    },
    "...": {
      // another job
    }
  },
  "...": {
    // another stage
  }
}

В этом примере задание B1 выполняется, если задание A1 пропущено. Задание B2 проверяет значение выходной переменной из задания A1, чтобы определить, следует ли выполнять ее.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  dependsOn: A
  jobs:
  - job: B1
    condition: in(stageDependencies.A.A1.result, 'Skipped') # change condition to `Succeeded and stage will be skipped`
    steps:
    - script: echo hello from Job B1
  - job: B2
    condition: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')
    steps:
     - script: echo hello from Job B2

Если задание зависит от переменной, определенной заданием развертывания на другом этапе, синтаксис отличается. В следующем примере задание run_tests выполняется, если установлено значение build_job для задания на развертывание runTests, равное true. Обратите внимание, что ключ, используемый для словаря outputs, это build_job.setRunTests.runTests.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  jobs:
    - job: run_tests
      condition: eq(stageDependencies.build.build_job.outputs['build_job.setRunTests.runTests'], 'true')
      steps:
        ...

Выходные переменные задания развертывания

Если этап зависит от переменной, определенной заданием развертывания на другом этапе, синтаксис отличается. В следующем примере этап test зависит от параметра настройки build_job для развертывания shouldTest на true. Обратите внимание, что на conditiontest этапе build_job отображается дважды.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')
  jobs:
    - job: A
      steps:
        - script: echo Hello from job A

В приведенном выше примере условие ссылается на среду, а не ресурс среды. Чтобы ссылаться на ресурс среды, необходимо добавить имя ресурса среды в условие зависимостей. В следующем примере условие ссылается на ресурс виртуальной машины среды с именем vmtest.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: vmtest
      resourceName: winVM2
      resourceType: VirtualMachine
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.Deploy_winVM2.setRunTests.runTests'], 'true')
  jobs:
  - job: A
    steps:
     - script: echo Hello from job A