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. Pode avaliar expressões em tempo de compilação ou em tempo de execução. Use expressões em tempo de compilação em qualquer lugar; use expressões em tempo de execução em variáveis e condições. Use expressões de tempo de execução para calcular o conteúdo das variáveis e do 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 em tempo de execução e em tempo de compilação reside principalmente no contexto disponível. Em uma expressão em tempo de compilação (${{ <expression> }}), você tem acesso a parameters e a variables definidas estaticamente. Em uma expressão de tempo de execução ($[ <expression> ]), você tem acesso a mais variables , mas nenhum parâmetro.

Neste exemplo, uma expressão de tempo de execução 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 por ordem (da esquerda para a direita) e devolve o primeiro valor que não é nulo nem uma cadeia vazia.
• Não retorna valor se todos os valores dos parâmetros forem nulos ou cadeias vazias.
• Parâmetros mínimos: 2. Parâmetros máximos: N.
• Exemplo: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• Pegue um objeto complexo e produza-o 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 do script:

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

contador

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

Pode criar um contador que é incrementado automaticamente por um cada vez que o seu pipeline é executado. Quando defines um contador, fornece um prefix e um seed. O exemplo seguinte demonstra este 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 sequência, o valor é 101, desde que o valor de major permaneça 1.

Se editar o ficheiro YAML e atualizar o valor da variável major para 2, o valor de minor é 100 na próxima execução do pipeline. As corridas seguintes incrementam o contador para 101, 102, 103, e assim sucessivamente.

Se mais tarde editar o ficheiro YAML e definir novamente o valor de major para 1, o valor do contador retoma onde ficou para esse prefixo. Neste exemplo, retoma-se em 102.

O exemplo seguinte mostra como definir uma variável para funcionar como contador que começa em 100, incrementa 1 para cada corrida e reinicia para 100 todos os dias.

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

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

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

Os contadores estão limitados a um pipeline. Ou seja, o pipeline incrementa o valor do contador para cada execução. Nenhum contador é definido pelo âmbito do projeto.

formato

• Avalia os parâmetros à direita e insere-os na string de parâmetro principal
• 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, dHHHmmmsssfffffffK)
• Exemplo: format('{0:yyyyMMdd}', pipeline.startTime). Neste caso pipeline.startTime , é uma variável de objeto de data e hora especial.
• Fuja dobrando chaves. Por exemplo: format('literal left brace {{ and literal right brace }}')

IFI

• 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 um Pull Request (PR).

aderir

• 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. Objetos complexos são convertidos em cadeia de caracteres vazia.
• Se o parâmetro certo não for uma matriz, o resultado será o parâmetro certo 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

mais baixo

• Converte uma cadeia ou valor variável para todos os caracteres minúsculos.
• Parâmetros mínimos: 1. Parâmetros máximos: 1.
• Retorna a versão em minúsculas de uma cadeia de caracteres.
• Exemplo: lower('FOO') devolve foo.

substituir

• Devolve uma nova cadeia em que todas as instâncias de uma cadeia na instância atual são substituídas por outra cadeia.
• Parâmetros mínimos: 3. Parâmetros máximos: 3.
• replace(a, b, c): devolve 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') (devolve http://server/saml/consume).

dividir

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

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

• Exemplo de utilização 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 uma cadeia de caracteres ou um valor de variável em todos os caracteres maiúsculos
• Parâmetros mínimos: 1. Parâmetros máximos: 1.
• Devolve o equivalente em maiúsculas de uma cadeia de caracteres
• Exemplo: upper('bah') retorna BAH

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

Definir condicionalmente uma entrada de tarefa

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 condicionalmente uma etapa

Se não houver um conjunto de variáveis ou se o valor de foo não corresponder às if condições, a else instrução será executada. Neste exemplo, o valor de foo retorna verdadeiro 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"

Cada palavra-chave

Use a each palavra-chave 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 }}

Também podes iterar por elementos aninhados num 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 fazer referência a trabalhos ou estágios anteriores. Usar dependências para:

• Fazer referência ao status do trabalho de um trabalho anterior
• Fazer referência ao estado de uma fase anterior
• Variáveis de saída de referência no trabalho anterior no mesmo estágio
• Variáveis de saída de referência na etapa anterior de um estágio
• Referenciar variáveis de saída num trabalho num estágio anterior no estágio seguinte.

O contexto é chamado dependencies para tarefas e estágios e funciona de forma semelhante a variáveis. Se te referires a uma variável de saída de um trabalho noutro estágio, o contexto será denominado stageDependencies.

Se tiver problemas com variáveis de saída que têm caracteres de aspas (' ou ") nelas, consulte este guia de resolução de problemas.

Visão geral da sintaxe de dependência

A sintaxe de referenciação de variáveis de saída com dependências varia 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 funcione.

A sintaxe das variáveis de saída em tarefas de implementação varia consoante a estratégia de implementação. Para obter mais informações, consulte Trabalhos de implantação.

Dependências de estágio a estágio

Estruturalmente, o dependencies objeto é um mapa de nomes de trabalho e estágio para results e outputs. Expresso como JSON, assemelha-se a:

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

Use esta forma de dependencies para mapear variáveis ou verificar condições a um nível de estágio.

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

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

Os estágios também podem usar variáveis de saída de outro estágio. Neste exemplo, existem dois estágios. O estágio A inclui um trabalho, A1, que define uma variável shouldrun de saída como true. O estágio B é executado quando shouldrun é true. Porque shouldrun é true, executa-se o Estágio 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

Dependências de tarefa para tarefa em uma fase

No nível de trabalho dentro de um único estágio, os dependencies dados não contêm informações de nível de estágio.

"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). A tarefa a é sempre ignorada por causa de condition: false. O trabalho b executa-se porque não tem condições associadas. O trabalho c é executado porque todas as suas dependências são bem-sucedidas (trabalho b) ou foram 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 tarefa para tarefa entre estágios

No nível do trabalho, você também pode fazer referência aos resultados de um trabalho em um estágio anterior. Para isso, é necessário usar o stageDependencies contexto.

"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 caso o trabalho A1 seja 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 um estágio diferente, a sintaxe será diferente. No exemplo a seguir, o trabalho run_tests será executado se o trabalho de implantação build_job estiver configurado runTests para true. Observe que a chave usada para o outputs dicionário é 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 um estágio depende de uma variável definida por um trabalho de implantação em um estágio diferente, a sintaxe é diferente. No exemplo a seguir, o estágio test depende da configuração build_job de implantação shouldTest como true. Repare que na condition da etapa 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 faz referência a um ambiente e não a um recurso ambiental. Para fazer referência a 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 faz referência a 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