Expressões

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Importante

Selecione a versão deste artigo que corresponde à sua plataforma e versão. O seletor de versão está acima do índice. pesquise sua plataforma e versão do Azure DevOps.

As expressões podem ser usadas em muitos locais em que você precisa especificar um valor de cadeia de caracteres, booliano ou numérico ao criar um pipeline. Quando uma expressão retorna uma matriz, regras de indexação normais são aplicáveis, e o índice começa com 0.

O uso mais comum de expressões está em condições para determinar se um trabalho ou etapa deve ser executado.

# 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. As expressões podem ser avaliadas em tempo de compilação ou em runtime. As expressões de tempo de compilação podem ser usadas em qualquer lugar. As expressões de runtime podem ser usadas em variáveis e condições. As expressões de runtime são destinadas como uma maneira de 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

Uma expressão pode ser um literal, uma referência a uma variável, uma referência a uma dependência, uma função ou uma combinação aninhada válida delas.

Literais

Como parte de uma expressão, você pode usar literais boolianos, nulos, numéricos, de cadeia de caracteres ou de versão.

# Examples
variables:
  someBoolean: ${{ true }} # case insensitive, so True or TRUE also works
  someNumber: ${{ -1.2 }}
  someString: ${{ 'a b c' }}
  someVersion: ${{ 1.2.3 }}

Boolean

True e False são expressões literais boolianas.

Nulo

Nulo é uma expressão literal especial que é retornada de um erro de dicionário, por exemplo (variables['noSuch']). Nulo pode ser a saída de uma expressão, mas não pode ser chamado diretamente dentro de uma expressão.

Número

Começa com '-', '.' ou '0' a '9'.

String

Deve estar entre aspas simples. Por exemplo: 'this is a string'.

Para expressar uma aspa única literal, escape-a com uma aspa única. Por exemplo: 'It''s OK if they''re using contractions.'.

Você pode usar um caractere de pipe (|) para cadeias de caracteres de várias linhas.

myKey: |
  one
  two
  three

Versão

Um número de versão com até quatro segmentos. Deve começar com um número e conter dois ou três caracteres de período (.). Por exemplo: 1.2.3.4.

Variáveis

Como parte de uma expressão, você pode acessar variáveis usando uma das duas sintaxes:

• Sintaxe de índice: variables['MyVar']
• Sintaxe de desreferência de propriedade: variables.MyVar

Para usar a sintaxe de propriedade de desreferência, o nome da propriedade deve:

• Começar com a-Z ou _
• Ser seguido por a-Z 0-9 ou _

Dependendo do contexto de execução, diferentes variáveis estão disponíveis.

• Se você criar pipelines usando YAML, as variáveis de pipeline estarão disponíveis.
• Se você criar pipelines de build usando o editor clássico, as variáveis de build estarão disponíveis.
• Se você criar pipelines de lançamento usando o editor clássico, as variáveis de lançamento estarão disponíveis.

As variáveis são sempre cadeias de caracteres. Se você quiser usar valores tipados, deverá usar parâmetros.

Observação

Há uma limitação para usar variáveis com expressões para pipelines Clássico e YAML, ao configurar essas variáveis usando a interface do usuário da guia de variáveis. As variáveis definidas como expressões não devem depender de outra variável com expressão em valor, pois não é garantido que ambas as expressões serão avaliadas corretamente. Por exemplo, temos uma variável a cujo valor $[ <expression> ] é usado como parte para o valor da variável b. Como a ordem das variáveis de processamento não é garantida, a variável b pode ter um valor incorreto da variável a após a avaliação.

As construções descritas são permitidas apenas durante a configuração de variáveis por meio da palavra-chave variáveis no pipeline YAML. É necessário colocar as variáveis na ordem em que devem ser processadas, para obter os valores corretos após o processamento.

Funções

As funções internas a seguir podem ser usadas em expressões.

e

• Avalia como True, se todos os parâmetros forem True
• Parâmetros mínimos: 2. Parâmetros máximos: N
• Converte parâmetros em Booliano para avaliação
• Curtos-circuitos após a primeira False
• Exemplo: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

coalesce

• Avalia os parâmetros em ordem (da esquerda para a direita) e retorna o primeiro valor que não é igual a null ou empty-string.
• Nenhum valor será retornado se os valores de parâmetros forem todos caracteres nulos ou vazios.
• Parâmetros mínimos: 2. Parâmetros máximos: N
• Exemplo: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

contém

• Avalia True, se o parâmetro à esquerda Cadeia de Caracteres contiver o parâmetro à direita
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte parâmetros em Cadeia de Caracteres para avaliação
• Executa a comparação de ordinais que não diferenciam maiúsculas e minúsculas
• Exemplo: contains('ABCDE', 'BCD') (returna True)

containsValue

• Avalia True, se o parâmetro à esquerda for uma matriz e qualquer item for igual ao parâmetro à direita. Também avalia True, se o parâmetro à esquerda for um objeto e o valor de qualquer propriedade for igual ao parâmetro à direita.
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Se o parâmetro à esquerda for uma matriz, converta cada item para corresponder ao tipo do parâmetro à direita. Se o parâmetro à esquerda for um objeto, converta o valor de cada propriedade para corresponder ao tipo do parâmetro à direita. A comparação de igualdade para cada item específico é avaliada False, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Curtos-circuitos após a primeira correspondência

Observação

Não há sintaxe literal em um pipeline YAML para especificar uma matriz. Essa função é de uso limitado em pipelines gerais. Ela se destina ao uso no contexto do decorador de pipeline com matrizes fornecidas pelo sistema, como a lista de etapas.

Você pode usar a expressão containsValue para encontrar um valor correspondente em um objeto. Aqui está um exemplo que demonstra a procura de uma correspondência na lista de ramificações de origem Build.SourceBranch.

parameters:
- name: branchOptions
  displayName: Source branch options
  type: object
  default:
    - refs/heads/main
    - refs/heads/test

jobs:
  - job: A1 
    steps:
    - ${{ each value in parameters.branchOptions }}:
      - script: echo ${{ value }}

  - job: B1 
    condition: ${{ containsValue(parameters.branchOptions, variables['Build.SourceBranch']) }}
    steps:
      - script: echo "Matching branch found"

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

• Essa função só pode ser usada em uma expressão que define uma variável. Ele não pode ser usado como parte de uma condição para uma etapa, trabalho ou estágio.
• Avalia um número incrementado com cada execução de um pipeline.
• Parâmetros: 2. prefix e seed.
• Prefixo é uma expressão de cadeia de caracteres. Um valor separado do contador é acompanhado para cada valor exclusivo do prefixo. O prefix deve usar caracteres UTF-16.
• Semente é o valor inicial do contador

Você pode criar um contador que é incrementado por um automaticamente em cada execução do pipeline. Ao definir um contador, você fornece um prefix e um seed. Veja um exemplo de código que demonstra isso.

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 acima na primeira execução do pipeline é 100. Na segunda execução é 101, desde que o valor de major ainda seja 1.

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

Posteriormente, se você editar o arquivo YAML e definir o valor de major como 1 novamente, o valor do contador será retomado de onde parou para esse prefixo. Neste exemplo, ele é retomado em 102.

Aqui está outro exemplo de como definir uma variável para atuar como um contador que começa em 100, é incrementado em 1 para cada execução e é redefinido para 100 todos os dias.

Observação

pipeline.startTime não está disponível fora das expressões. pipeline.startTime formata system.pipelineStartTime em um objeto de data e hora para que esteja disponível para trabalhar com expressões. O fuso horário padrão para pipeline.startTime é UTC. Você pode alterar o fuso horário da sua organização.

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

Aqui está um exemplo de ter 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, seu valor é incrementado para cada execução desse pipeline. Não há contadores com o escopo do projeto.

endsWith

• Avalia True, se o parâmetro à esquerda Cadeia de Caracteres contiver o parâmetro à direita
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte parâmetros em Cadeia de Caracteres para avaliação
• Executa a comparação de ordinais que não diferenciam maiúsculas e minúsculas
• Exemplo: endsWith('ABCDE', 'DE') (returna True)

eq

• Avalia True, se os parâmetros forem iguais
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro à direita para corresponder ao tipo de parâmetro à esquerda. Retorna False, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Exemplo: eq(variables.letters, 'ABC')

format

• 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 }}')

ge

• Avalia True, se o parâmetro à esquerda for maior que ou igual ao parâmetro à direita
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro à direita para corresponder ao tipo de parâmetro à esquerda. Erros, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Exemplo: ge(5, 5) (returna True)

gt

• Avalia True, se o parâmetro à esquerda for maior que o parâmetro à direita
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro à direita para corresponder ao tipo de parâmetro à esquerda. Erros, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Exemplo: gt(5, 2) (returna True)

em

• Avalia True, se o parâmetro à esquerda for igual a qualquer parâmetro à direita
• Parâmetros mínimos: 1. Parâmetros máximos: N
• Converte os parâmetros à direita para corresponder ao tipo de parâmetro à esquerda. A comparação de igualdade avalia False, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Curtos-circuitos após a primeira correspondência
• Exemplo: in('B', 'A', 'B', 'C') (returna True)

join

• 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

le

• Avalia True, se o parâmetro à esquerda for menor que ou igual ao parâmetro à direita
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro à direita para corresponder ao tipo de parâmetro à esquerda. Erros, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Exemplo: le(2, 2) (returna True)

comprimento

• Retorna o comprimento de uma cadeia de caracteres ou de uma matriz, qualquer uma delas que venha do sistema ou de um parâmetro
• Parâmetros mínimos: 1. Parâmetros máximos: 1
• Exemplo: length('fabrikam') retorna 8

lower

• 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 em minúsculas de uma cadeia de caracteres
• Exemplo: lower('FOO') retorna foo

lt

• Avalia True, se o parâmetro à esquerda for menor que o parâmetro à direita
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro à direita para corresponder ao tipo de parâmetro à esquerda. Erros, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Exemplo: lt(2, 5) (returna True)

ne

• Avalia True, se os parâmetros não forem iguais
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro à direita para corresponder ao tipo de parâmetro à esquerda. Retorna True, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Exemplo: ne(1, 2) (returna True)

não

• Avalia True, se o parâmetro for False
• Parâmetros mínimos: 1. Parâmetros máximos: 1
• Converte o valor em Booliano para avaliação
• Exemplo: not(eq(1, 2)) (returna True)

notIn

• Avalia True se o parâmetro left não é igual a nenhum parâmetro right
• Parâmetros mínimos: 1. Parâmetros máximos: N
• Converte os parâmetros à direita para corresponder ao tipo de parâmetro à esquerda. A comparação de igualdade avalia False, se a conversão falhar.
• Comparação de ordinais que não diferenciam maiúsculas e minúsculas para Cadeias de Caracteres
• Curtos-circuitos após a primeira correspondência
• Exemplo: notIn('D', 'A', 'B', 'C') (returna True)

ou

• Avalia True, se algum parâmetro for True
• Parâmetros mínimos: 2. Parâmetros máximos: N
• Converte parâmetros em Booliano para avaliação
• Curtos-circuitos após a primeira True
• Exemplo: or(eq(1, 1), eq(2, 3)) (retorna True, curtos-circuitos)

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)

split

• Divide uma cadeia de caracteres em substrings baseadas 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 corresponde aos caracteres delimitadores
• Retorna uma matriz de substrings. A matriz inclui cadeias de caracteres vazias quando os caracteres delimitadores são exibidos 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 }}
  

startsWith

• Avalia True, se a cadeia de caracteres do parâmetro à esquerda começar com o parâmetro à direita
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte parâmetros em Cadeia de Caracteres para avaliação
• Executa a comparação de ordinais que não diferenciam maiúsculas e minúsculas
• Exemplo: startsWith('ABCDE', 'AB') (returna True)

upper

• 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

xor

• Avalia True, se exatamente um parâmetro forTrue
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte parâmetros em Booliano para avaliação
• Exemplo: xor(True, False) (returna True)

Funções de verificação de status de trabalho

Você pode usar as seguintes funções de verificação de status como expressões em condições, mas não em definições de variáveis.

always

• Sempre avalia como True (mesmo quando cancelado). Observação: uma falha crítica ainda pode impedir a execução de uma tarefa. Por exemplo, se houver falha ao obter as fontes.

cancelado

• Avalia como True, se o pipeline foi cancelado.

falhou

• Para uma etapa, equivalente a eq(variables['Agent.JobStatus'], 'Failed').
• Para um trabalho:
  • Sem argumentos, avalia como True, somente se algum trabalho anterior no grafo de dependência falhou.
  • Com nomes de trabalho como argumentos, avalia como True, somente se algum desses trabalhos falhou.

bem-sucedido

• Para uma etapa, equivalente a in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
• Use com dependsOn ao lidar com trabalhos e quando você desejar avaliar se um trabalho anterior foi bem-sucedido. Os trabalhos são criados para serem executados paralelamente, enquanto as fases são executadas sequencialmente.
• Para um trabalho:
  • Sem argumentos, avalia como True, somente se todos os trabalhos anteriores no grafo de dependência foram bem-sucedidos ou parcialmente bem-sucedidos.
  • Com nomes de trabalho como argumentos, avalia como True, se todos esses trabalhos foram bem-sucedidos ou parcialmente bem-sucedidos.
  • Avalia como False, se o pipeline for cancelado.

succeededOrFailed

• Para uma etapa, equivalente a in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed')

• Para um trabalho:

  • Sem argumentos, avalia como True, independentemente de algum trabalho no grafo de dependência ter sido bem-sucedido ou falhado.
  • Com nomes de trabalho como argumentos, avalia como True, se algum desses trabalhos foi bem-sucedido ou falhou.
  • Convém usar not(canceled()) quando houver trabalhos ignorados anteriormente no grafo de dependência.

  Parece com always(), exceto que avaliará como False, quando o pipeline for cancelado.

Inserção condicional

Você pode usar cláusulas if, elseif e else 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.

Os condicionais só funcionam ao usar a sintaxe de modelo. Saiba mais sobre sintaxe de variáveis.

Para modelos, você pode usar a inserção condicional ao adicionar uma sequência ou mapeamento. Saiba mais sobre inserção condicional em modelos.

Atribuir uma variável condicionalmente

variables:
  ${{ if eq(variables['Build.SourceBranchName'], 'main') }}: # only works if you have a main branch
    stageName: prod

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo ${{variables.stageName}}

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. Aqui, o valor de foo retorna true na condição 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"

palavra-chave Each

Você pode usar 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 }}

Além disso, você pode iterar usando os elementos aninhados em 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. Você pode usar 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 que têm caracteres entre aspas (' ou "), confira 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.

Tipo

Descrição

Dependência entre estágios (diferentes estágios)

Referência a uma variável de saída de um estágio anterior de um trabalho em um estágio diferente em uma condição no stages.

• Sintaxe: and(succeeded(), eq(stageDependencies.<stage-name>.outputs['<job-name>.<step-name>.<variable-name>'], 'true'))
• Exemplo: and(succeeded(), eq(stageDependencies.A.outputs['A1.printvar.shouldrun'], 'true'))

Dependência entre trabalhos (mesmo estágio)

Referência a uma variável de saída em um trabalho diferente no mesmo estágio no stages.

• Sintaxe: and(succeeded(), eq(dependencies.<job-name>.outputs['<step-name>.<variable-name>'], 'true'))
• Exemplo: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))

Dependência entre trabalho e estágio (diferentes estágios)

Referência a uma variável de saída em um estágio diferente em um job.

• Sintaxe: eq(stageDependencies.<stage-name>.<job-name>.outputs['<step-name>.<variable-name>'], 'true')
• Exemplo: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')

Dependência entre estágios (trabalho de implantação)

Referência a uma variável de saída em um trabalho de implentação de um estágio diferente no stages.

• Sintaxe: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<deployment-job-name>.<step-name>.<variable-name>'], 'true')
• Exemplo: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')

Dependência entre estágios (trabalho de implantação com recurso)

Referência a uma variável de saída em um trabalho de implentação que inclui um recurso em um estágio diferente no stages.

• Sintaxe: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<Deploy_resource-name>.<step-name>.<variable-name>'], 'true')
• Exemplo: eq(dependencies.build.outputs['build_job.Deploy_winVM.setRunTests.runTests'], 'true')

Há também sintaxes diferentes para variáveis de saída em trabalhos de implantação, 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 como JSON, teria a seguinte aparência:

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

Observação

Os exemplos a seguir usam a sintaxe de pipeline padrão. Se você estiver usando pipelines de implantação, a sintaxe variável e a variável condicional serão diferentes. Para obter informações sobre a sintaxe específica a ser usada, confira Trabalhos de implantação.

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

Neste exemplo, há dois estágios, A e B. O estágio A tem a condição false e nunca será executado como resultado. 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, também há 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

Observação

Por padrão, cada fase em um pipeline depende daquele imediatamente anterior a ele no arquivo YAML. Se você precisar se referir a uma fase que não seja imediatamente anterior à atual, poderá substituir esse padrão automático adicionando uma seção dependsOn à fase.

Dependências de trabalho para trabalho em 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 será ignorado por causa de condition: false. O trabalho b é executado porque não há 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

Matrizes filtradas

Ao operar em uma coleção de itens, você pode usar a sintaxe * para aplicar uma matriz filtrada. Uma matriz filtrada retorna todos os objetos/elementos, independentemente dos nomes.

Como exemplo, considere uma matriz de objetos chamada foo. Queremos obter uma matriz dos valores da propriedade id em cada objeto de nossa matriz.

[
    { "id": 1, "a": "avalue1"},
    { "id": 2, "a": "avalue2"},
    { "id": 3, "a": "avalue3"}
]

Você pode fazer o seguinte:

foo.*.id

Isso informa ao sistema para operar em foo como uma matriz filtrada e selecionar a propriedade id.

Isso retornaria:

[ 1, 2, 3 ]

Conversão de tipo

Os valores em uma expressão podem ser convertidos de um tipo para outro, à medida que a expressão é avaliada. Quando uma expressão é avaliada, os parâmetros são unidos ao tipo de dados relevante e, em seguida, transformados novamente em cadeias de caracteres.

Por exemplo, neste YAML, os valores True e False são convertidos em 1 e 0 quando a expressão é avaliada. A função lt() retorna True quando o parâmetro à esquerda é menor que o parâmetro à direita.

variables:
  firstEval: $[lt(False, True)] # 0 vs. 1, True
  secondEval: $[lt(True, False)] # 1 vs. 0, False

steps:
- script: echo $(firstEval)
- script: echo $(secondEval)

Quando você usa a expressão para avaliar a equivalência, os eq() valores são implicitamente convertidos em números (false para 0 e true para 1).

variables:
  trueAsNumber: $[eq('true', true)] # 1 vs. 1, True
  falseAsNumber: $[eq('false', true)] # 0 vs. 1, False

steps:
- script: echo $(trueAsNumber)
- script: echo $(falseAsNumber)

Neste próximo exemplo, os valores variables.emptyString e a cadeia de caracteres vazia são avaliados como cadeias de caracteres vazias. A função coalesce() avalia os parâmetros em ordem e retorna o primeiro valor que não é igual a null ou empty-string.

variables:
  coalesceLiteral: $[coalesce(variables.emptyString, '', 'literal value')]

steps:
- script: echo $(coalesceLiteral) # outputs literal value

As regras de conversão detalhadas são listadas mais abaixo.

De/para	Boolean	Nulo	Número	String	Versão
Booliano	-	-	Sim	Sim	-
Nulo	Sim	-	Sim	Sim	-
Número	Sim	-	-	Sim	Parcial
Cadeia de caracteres	Sim	Parcial	Parcial	-	Parcial
Versão	Sim	-	-	Sim	-

Boolean

Para número:

• False → 0
• True → 1

Para cadeia de caracteres:

• False → 'False'
• True → 'True'

Nulo

• Para Booliano: False
• Para número: 0
• Para cadeia de caracteres: '' (a cadeia de caracteres vazia)

Número

• Para booliano: 0 → False, qualquer outro número → True
• Para versão: Deve ser maior que zero e deve conter um decimal diferente de zero. Deve ser menor que Int32.MaxValue (componente decimal também).
• Para cadeia de caracteres: converte o número em uma cadeia de caracteres sem separador de milhares e sem separador decimal.

String

• Para booliano: '' (a cadeia de caracteres vazia) → False, qualquer outra cadeia de caracteres → True
• Para nulo: '' (a cadeia de caracteres vazia) → Null, qualquer outra cadeia de caracteres não conversível
• Para número: '' (a cadeia de caracteres vazia) → 0, caso contrário, executa Int32.TryParse do C# usando InvariantCulture e as seguintes regras: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | Allowtrailingwhite. Se TryParse falhar, não será conversível.
• Para a versão: executa o Version.TryParse do C#. Deve conter, no mínimo, o componente Principal e Secundário. Se TryParse falhar, não será conversível.

Versão

• Para Booliano: True
• Para cadeia de caracteres: Major.Minor, Major.Minor.Build ou Major.Minor.Build.Revision.

Perguntas frequentes

Quero fazer algo que não seja apoiado por expressões. Quais opções tenho para estender a funcionalidade de Pipelines?

Você pode personalizar seu Pipeline com um script que inclui uma expressão. Por exemplo, esse snippet usa a variável BUILD_BUILDNUMBER e a divide com Bash. Esse script gera duas novas variáveis, $MAJOR_RUN e $MINOR_RUN, para os números de execução principal e secundário. As duas variáveis são usadas para criar duas variáveis de pipeline, $major e $minor, com task.setvariable. Essas variáveis estão disponíveis para as etapas downstream. Para compartilhar variáveis entre pipelines, confira Grupos de variáveis.

steps:
- bash: |
    MAJOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f1)
    echo "This is the major run number: $MAJOR_RUN"
    echo "##vso[task.setvariable variable=major]$MAJOR_RUN"

    MINOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f2)
    echo "This is the minor run number: $MINOR_RUN"
    echo "##vso[task.setvariable variable=minor]$MINOR_RUN"

- bash: echo "My pipeline variable for major run is $(major)"
- bash: echo "My pipeline variable for minor run is $(minor)"