Expressões

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

Outro uso comum de expressões é na definição de variáveis. Você pode avaliar expressões em tempo de compilação ou em tempo de execução. Use expressões de tempo de compilação em qualquer lugar; use expressões de runtime em variáveis e condições. Use expressões de runtime para calcular o conteúdo de variáveis e estado (exemplo: 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> ]

A diferença entre as sintaxes de expressão de tempo de compilação e de runtime é principalmente o contexto disponível. Em uma expressão de tempo de compilação (${{ <expression> }}), você tem acesso a parameters e definiu variables estaticamente. Em uma expressão de runtime ($[ <expression> ]), você tem acesso a mais variables, mas sem parâmetros.

Neste exemplo, uma expressão de runtime define o valor de $(isMain). Uma variável estática em uma expressão de compilação define o valor de $(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

unir

• Avalia os parâmetros em ordem (da esquerda para a direita) e retorna o primeiro valor que não é nulo ou uma cadeia de caracteres vazia.
• Não retornará nenhum valor se todos os valores de parâmetro forem cadeias de caracteres nulas ou vazias.
• Parâmetros mínimos: 2. Parâmetros máximos: N.
• Exemplo: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• Pega um objeto complexo e o gera como JSON.
• Parâmetros mínimos: 1. Parâmetros máximos: 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) }}

Saída de script:

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

contador

• Use essa função apenas em uma expressão que defina uma variável. Não o use como parte de uma condição para uma etapa, trabalho ou estágio.
• Avalia um número que é incrementado a cada execução de uma pipeline.
• Usa dois parâmetros: prefix e seed.
• prefix é uma expressão de cadeia de caracteres. A função rastreia um valor de contador separado para cada prefix único. Use caracteres UTF-16 no prefix.
• seed é o valor inicial do contador.

Você pode criar um contador que incrementa automaticamente por um cada vez que o pipeline é executado. Ao definir um contador, forneça um prefix e um seed. O exemplo a seguir demonstra esse conceito.

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)

O valor de minor no exemplo anterior é 100 durante a primeira execução do pipeline. Na segunda execução, o valor é 101, desde que o valor permaneça major 1.

Se você editar o arquivo YAML e atualizar o valor da variável major para 2, o valor será minor 100 na próxima execução do pipeline. As execuções subsequentes incrementam o contador para 101, 102, 103 e assim por diante.

Se você editar posteriormente o arquivo YAML e definir o valor de major de volta para 1, o valor do contador retoma de onde parou para aquele prefixo. Neste exemplo, ele é retomado em 102.

O exemplo a seguir mostra como definir uma variável para atuar como um contador que começa em 100, incrementa em 1 para cada execução e redefine para 100 todos os dias.

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

O exemplo a seguir mostra um contador que mantém um valor separado para PRs e execuções de CI.

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

O escopo dos contadores é um pipeline. Em outras palavras, o pipeline incrementa o valor do contador para cada execução. Nenhum contador tem escopo de projeto.

formato

• Avalia os parâmetros à direita e os insere na cadeia de caracteres de parâmetro à esquerda
• Parâmetros mínimos: 1. Parâmetros máximos: N
• Exemplo: format('Hello {0} {1}', 'John', 'Doe')
• Usa especificadores de formato de data e hora personalizados do .NET para formatação de data (yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff, K)
• Exemplo: format('{0:yyyyMMdd}', pipeline.startTime). Nesse caso, pipeline.startTime é uma variável de objeto de data e hora especial.
• Escape dobrando as chaves. Por exemplo: format('literal left brace {{ and literal right brace }}')

iif

• Retorna o segundo parâmetro se o primeiro parâmetro for avaliado como True, e o terceiro parâmetro caso contrário
• Parâmetros mínimos: 1. Parâmetros máximos: 3
• O primeiro parâmetro deve ser uma condição
• Exemplo: iif(eq(variables['Build.Reason'], 'PullRequest'), 'ManagedDevOpsPool', 'Azure Pipelines') retorna "ManagedDevOpsPool" quando o pipeline é executado em resposta a uma PR.

ingressar

• Concatena todos os elementos na matriz de parâmetros à direita, separados pela cadeia de caracteres de parâmetro à esquerda.
• Parâmetros mínimos: 2. Parâmetros máximos: 2.
• Cada elemento na matriz é convertido em uma cadeia de caracteres. Os objetos complexos são convertidos em uma cadeia de caracteres vazia.
• Se o parâmetro correto não for uma matriz, o resultado será o parâmetro correto convertido em uma cadeia de caracteres.

Neste exemplo, um ponto e vírgula é adicionado entre cada item na matriz. O tipo de parâmetro é um objeto.

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

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

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

abaixar

• Converte um valor de cadeia de caracteres ou variável em todos os caracteres minúsculos.
• Parâmetros mínimos: 1. Parâmetros máximos: 1.
• Retorna o equivalente minúsculo de uma cadeia de caracteres.
• Exemplo: lower('FOO') retorna foo.

substituir

• Retorna uma nova cadeia de caracteres na qual todas as instâncias de uma cadeia de caracteres na instância atual são substituídas por outra cadeia de caracteres.
• Parâmetros mínimos: 3. Parâmetros máximos: 3.
• replace(a, b, c): retorna a, com todas as instâncias de b substituídas por c.
• Exemplo: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (retorna http://server/saml/consume).

dividir

• Divide uma cadeia de caracteres em subcadeias de caracteres com base nos caracteres delimitadores especificados.
• Parâmetros mínimos: 2. Parâmetros máximos: 2.
• O primeiro parâmetro é a cadeia de caracteres a ser dividida.
• O segundo parâmetro é os caracteres delimitadores.
• Retorna uma matriz de substrings. A matriz inclui cadeias de caracteres vazias quando os caracteres delimitadores aparecem consecutivamente ou no final da cadeia de caracteres.
• Exemplo:

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

• Exemplo de uso de split() com 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 }}
  

cortar

• Retorna o parâmetro sem espaços em branco à esquerda e à direita
• Parâmetros mínimos: 1. Parâmetros máximos: 1
• Exemplo: trim(' variable ') retorna 'variável'

superior

• Converte um valor de cadeia de caracteres ou variável em todos os caracteres maiúsculos
• Parâmetros mínimos: 1. Parâmetros máximos: 1.
• Retorna o equivalente em maiúsculas de uma cadeia de caracteres
• Exemplo: upper('bah') retorna BAH

Use if, elseife else cláusulas para atribuir condicionalmente valores variáveis ou definir entradas para tarefas. Você também pode executar condicionalmente uma etapa, quando uma condição for atendida.

Definir uma entrada de tarefa condicionalmente

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'

Executar uma etapa condicionalmente

Se não houver nenhuma variável definida ou o valor de foo não corresponder às condições if, a else instrução será executada. Neste exemplo, o valor de foo retorna true na elseif condição.

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"

palavra-chave Each

Utilize a palavra-chave each para percorrer parâmetros com o tipo de objeto.

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

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

Você também pode iterar por meio de elementos aninhados dentro de um objeto.

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

Dependências

As expressões podem usar o contexto de dependências para referenciar trabalhos ou fases anteriores. Use dependências para:

• Referenciar o status de trabalho de um trabalho anterior
• Referenciar o status de fase de uma fase anterior
• Referenciar variáveis de saída no trabalho anterior na mesma fase
• Referenciar variáveis de saída na fase anterior em um fase
• Referenciar variáveis de saída em um trabalho em uma fase anterior na fase seguinte

O contexto é chamado de dependencies para trabalhos e fases e funciona como variáveis. Se você fizer referência a uma variável de saída de um trabalho em outra fase, o contexto será chamado de stageDependencies.

Se você tiver problemas com variáveis de saída com caracteres de aspas (' ou ") neles, consulte este guia de solução de problemas.

Visão geral da sintaxe de dependências

A sintaxe de referência de variáveis de saída com dependências é diferente dependendo das circunstâncias. Aqui está uma visão geral dos cenários mais comuns. Pode haver momentos em que a sintaxe alternativa também funciona.

A sintaxe para variáveis de saída em trabalhos de implantação varia dependendo da estratégia de implantação. Para obter mais informações, consulte Trabalhos de implantação.

Fase para preparar dependências

Estruturalmente, o objeto dependencies é um mapa de nomes de trabalho e fase para results e outputs. Expresso na forma de JSON, fica:

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

Use essa forma de dependencies para mapear em variáveis ou verificar condições em um nível de fase.

Neste exemplo, existem dois estágios, A e B. O Estágio A tem a condição false e não é executado. O estágio B será executado se o resultado do Estágio A for Succeeded, SucceededWithIssues ou Skipped. O estágio B é executado porque o estágio A foi ignorado.

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

As fases também podem usar variáveis de saída de outra fase. Neste exemplo, existem dois estágios. O estágio A inclui um trabalho, A1, que define uma variável de saída shouldrun como true. O estágio B é executado quando shouldrun é true. Como shouldrun é true, o estágio B é executado.

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

Dependências de tarefas dentro de uma fase

No nível do trabalho em uma fase única, os dados dependencies não contêm informações de nível de fase.

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

Neste exemplo, há três trabalhos (a, b e c). O trabalho 'a' é sempre ignorado devido a condition: false. A tarefa b é executada porque não tem condições associadas. O trabalho c é executado porque todas as suas dependências são bem-sucedidas (trabalho b) ou ignoradas (trabalho 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

Neste exemplo, o Trabalho B depende de uma variável de saída do Trabalho 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

Dependências de trabalho para trabalho entre fases

No nível do trabalho, você também pode referenciar saídas de um trabalho em uma fase anterior. Isso requer o uso do contexto stageDependencies.

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

Neste exemplo, o trabalho B1 é executado se o trabalho A1 for ignorado. O trabalho B2 verifica o valor da variável de saída do trabalho A1 para determinar se ele deve ser executado.

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

Se um trabalho depender de uma variável definida por um trabalho de implantação em uma fase diferente, a sintaxe será diferente. No exemplo a seguir, o trabalho run_tests será executado, se o trabalho de implantação build_job definir runTests como true. Observe que a chave usada para o dicionário 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:
        ...

Variáveis de saída do trabalho de implantação

Se uma fase depender de uma variável definida por um trabalho de implantação em uma fase diferente, a sintaxe será diferente. No exemplo a seguir, a fase test depende da implantação build_job configuração shouldTest para true. Observe que, no condition da fase test, build_job aparece duas vezes.

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

No exemplo acima, a condição referencia um ambiente e não um recurso de ambiente. Para referenciar um recurso de ambiente, você precisará adicionar o nome do recurso de ambiente à condição de dependências. No exemplo a seguir, a condição referencia um recurso de máquina virtual de ambiente chamado 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