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. Procure a sua plataforma e versão do Azure DevOps.

As expressões podem ser usadas em muitos lugares onde você precisa especificar um valor de cadeia de caracteres, booleano ou número ao criar um pipeline. Quando uma expressão retorna uma matriz, regras normais de indexação se aplicam e o índice começa com 0.

O uso mais comum de expressões é 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 tempo de execução. As expressões de tempo de compilação podem ser usadas em qualquer lugar; expressões de tempo de execução podem ser usadas em variáveis e condições. As expressões de tempo de execução destinam-se como uma forma de calcular o conteúdo de variáveis e o 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 de tempo de compilação é principalmente o contexto disponível. Em uma expressão em tempo de compilação (${{ <expression> }}), você tem acesso e parameters definido variablesestaticamente . 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

Uma expressão pode ser 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 destes.

Literais

Como parte de uma expressão, você pode usar literais booleanos, nulos, numéricos, strings 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 booleanas.

Nulo

Nulo é uma expressão literal especial que é retornada de uma falha 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 ser cotado simples. Por exemplo: 'this is a string'.

Para expressar uma única citação literal, escape-a com uma única citação. 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 ponto (.). 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 do índice: variables['MyVar']
• Sintaxe de desreferência de propriedade: variables.MyVar

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

• Comece 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 compilação usando o editor clássico, as variáveis de compilação estarão disponíveis.
• Se você criar pipelines de liberação usando o editor clássico, as variáveis de liberação estarão disponíveis.

As variáveis são sempre strings. Se você quiser usar valores digitados, então você deve usar parâmetros em vez disso.

Nota

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

As construções descritas só são permitidas enquanto as variáveis de configuração 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 seguintes funções internas podem ser usadas em expressões.

e

• Avalia se True todos os parâmetros são True
• Parâmetros mínimos: 2. Parâmetros máximos: N
• Projeta parâmetros para Boolean para avaliação
• Curto-circuitos após o primeiro 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 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')

contém

• Avalia se o True parâmetro left String contém o parâmetro right
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte parâmetros em String para avaliação
• Executa a comparação ordinal de casos ignorados
• Exemplo: contains('ABCDE', 'BCD') (retorna True)

contémValor

• Avalia True se o parâmetro left é uma matriz, e qualquer item é igual ao parâmetro right. Também avalia True se o parâmetro left é um objeto e o valor de qualquer propriedade é igual ao parâmetro right.
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Se o parâmetro left for uma matriz, converta cada item para corresponder ao tipo do parâmetro right. Se o parâmetro left for um objeto, converta o valor de cada propriedade para corresponder ao tipo do parâmetro right. A comparação de igualdade para cada item específico avalia False se a conversão falha.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Curto-circuitos após o primeiro jogo

Nota

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

Você pode usar a containsValue expressão para encontrar um valor correspondente em um objeto. Este é um exemplo que demonstra procurar na lista de ramificações de origem uma correspondência para 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

• 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"
    ]
  }
}

counter

• Esta 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 que é 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 de contador é rastreado para cada valor exclusivo de prefixo. O prefix deve usar caracteres UTF-16.
• Seed é o valor inicial do contador

Você pode criar um contador que é automaticamente incrementado por um em cada execução do seu pipeline. Ao definir um contador, você fornece um prefix e um seed. Aqui está um exemplo 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 corrida é 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. Execuções subsequentes incrementam o contador para 101, 102, 103, ...

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

Aqui está outro exemplo de configuração de 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.

Nota

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 ele esteja disponível para trabalhar com expressões. O fuso horário padrão para pipeline.startTime é UTC. 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 execuções de PRs e CI.

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

Os contadores têm como escopo um pipeline. Em outras palavras, seu valor é incrementado para cada execução desse pipeline. Não há contadores com escopo de projeto.

termina com

• Avalia se o True parâmetro left String termina com o parâmetro right
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte parâmetros em String para avaliação
• Executa a comparação ordinal de casos ignorados
• Exemplo: endsWith('ABCDE', 'DE') (retorna True)

eq

• Avalia se os True parâmetros são iguais
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro direito para corresponder ao tipo de parâmetro esquerdo. Retorna False se a conversão falhar.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Exemplo: eq(variables.letters, 'ABC')

format

• Avalia os parâmetros à direita e os insere na cadeia de caracteres 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, HmmssdfHHffffmffsK)
• 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 }}')

ge

• Avalia True se o parâmetro esquerdo é maior ou igual ao parâmetro direito
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro direito para corresponder ao tipo de parâmetro esquerdo. Erros se a conversão falhar.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Exemplo: ge(5, 5) (retorna True)

gt

• Avalia True se o parâmetro esquerdo é maior que o parâmetro direito
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro direito para corresponder ao tipo de parâmetro esquerdo. Erros se a conversão falhar.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Exemplo: gt(5, 2) (retorna True)

presente em

• Avalia se o True parâmetro esquerdo é igual a qualquer parâmetro direito
• Parâmetros mínimos: 1. Parâmetros máximos: N
• Converte parâmetros à direita para corresponder ao tipo de parâmetro esquerdo. A comparação de igualdade avalia se a False conversão falhar.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Curto-circuitos após o primeiro jogo
• Exemplo: in('B', 'A', 'B', 'C') (retorna 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. 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

le

• Avalia True se o parâmetro esquerdo é menor ou igual ao parâmetro direito
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro direito para corresponder ao tipo de parâmetro esquerdo. Erros se a conversão falhar.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Exemplo: le(2, 2) (retorna True)

length

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

inferior

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

lt

• Avalia se o True parâmetro esquerdo é menor que o parâmetro direito
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro direito para corresponder ao tipo de parâmetro esquerdo. Erros se a conversão falhar.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Exemplo: lt(2, 5) (retorna True)

ne

• Avalia se os True parâmetros não são iguais
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte o parâmetro direito para corresponder ao tipo de parâmetro esquerdo. Retorna True se a conversão falhar.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Exemplo: ne(1, 2) (retorna True)

not

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

nãoEm

• Avalia True se o parâmetro left não é igual a qualquer parâmetro right
• Parâmetros mínimos: 1. Parâmetros máximos: N
• Converte parâmetros à direita para corresponder ao tipo de parâmetro esquerdo. A comparação de igualdade avalia se a False conversão falhar.
• Comparação ordinal de maiúsculas e minúsculas para Strings
• Curto-circuitos após o primeiro jogo
• Exemplo: notIn('D', 'A', 'B', 'C') (retorna True)

ou

• Avalia True se algum parâmetro é True
• Parâmetros mínimos: 2. Parâmetros máximos: N
• Projeta parâmetros para Boolean para avaliação
• Curto-circuitos após o primeiro True
• Exemplo: or(eq(1, 1), eq(2, 3)) (retorna True, curto-circuitos)

replace

• 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') (devoluções http://server/saml/consume)

split

• Divide uma cadeia de caracteres em substrings com base nos caracteres de delimitação 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 são os caracteres delimitadores
• Retorna uma matriz de substrings. A matriz inclui cadeias de caracteres vazias quando os caracteres de delimitação 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 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 }}
  

começaCom

• Avalia se a True cadeia de caracteres do parâmetro esquerdo começa com o parâmetro direito
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Converte parâmetros em String para avaliação
• Executa a comparação ordinal de casos ignorados
• Exemplo: startsWith('ABCDE', 'AB') (retorna True)

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') devoluções BAH

xor

• Avalia True se exatamente um parâmetro é True
• Parâmetros mínimos: 2. Parâmetros máximos: 2
• Projeta parâmetros para Boolean para avaliação
• Exemplo: xor(True, False) (retorna True)

Funções de verificação do status do 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.

sempre

• Sempre avalia para True (mesmo quando cancelado). Nota: Uma falha crítica ainda pode impedir a execução de uma tarefa. Por exemplo, se a obtenção de fontes falhou.

Cancelado

• Avalia se True o pipeline foi cancelado.

com falhas

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

bem sucedido

• Para um passo, equivalente a in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
• Use com dependsOn ao trabalhar com trabalhos e você deseja avaliar se um trabalho anterior foi bem-sucedido. Os trabalhos são projetados para serem executados em paralelo, enquanto os estágios são executados sequencialmente.
• Para um emprego:
  • Sem argumentos, avalia apenas True se todos os trabalhos anteriores no gráfico de dependência foram bem-sucedidos ou parcialmente bem-sucedidos.
  • Com nomes de trabalho como argumentos, avalia se todos esses trabalhos foram bem-sucedidos True ou parcialmente bem-sucedidos.
  • Avalia se False o pipeline foi cancelado.

succeededOrFailed

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

• Para um emprego:

  • Sem argumentos, avalia independentemente True de algum trabalho no gráfico de dependência ter sido bem-sucedido ou reprovado.
  • Com nomes de cargos como argumentos, avalia True se algum desses trabalhos teve sucesso ou fracasso.
  • Você pode querer usar not(canceled()) em vez disso quando houver trabalhos ignorados anteriores no gráfico de dependência.

  Isto é como always(), exceto que irá avaliar False quando o pipeline é cancelado.

Inserção condicional

Você pode usar if, elseife 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.

As condicionais só funcionam ao usar a sintaxe do modelo. Saiba mais sobre sintaxe variável.

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

Atribuir condicionalmente uma variável

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 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. Aqui 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"

Cada palavra-chave

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

Além disso, você pode iterar através 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 fazer referência a trabalhos ou estágios anteriores. Você pode usar dependências para:

• Fazer referência ao status do trabalho de um trabalho anterior
• Fazer referência ao status do estágio de um estágio 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
• Variáveis de saída de referência em um trabalho em um estágio anterior no estágio seguinte

O contexto é chamado dependencies para trabalhos e estágios e funciona muito como variáveis. Se você se referir a uma variável de saída de um trabalho em outro estágio, o contexto será chamado stageDependencies.

Se você tiver problemas com variáveis de saída com caracteres de aspas (' ou "), consulte este guia de soluçã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.

Tipo

Descrição

dependência estágio a estágio (diferentes estágios)

Fazer referência a uma variável de saída de um estágio anterior em um trabalho em um estágio diferente em uma condição em 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 de trabalho para emprego (mesmo estágio)

Faça referência a uma variável de saída em um trabalho diferente no mesmo estágio em 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 de trabalho para estágio (diferentes estágios)

Referenciar uma variável de saída em um estágio diferente em um jobarquivo .

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

Dependência de estágio a estágio (trabalho de implantação)

Variável de saída de referência em um trabalho de implantação em 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 de estágio a estágio (trabalho de implantação com recurso)

Faça referência a uma variável de saída em um trabalho de implantação que inclua um recurso em 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')

Também há diferentes sintaxes 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.

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, seria parecido:

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

Nota

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

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

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 é executado se o resultado do estágio A for Succeeded, SucceededWithIssuesou 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

Os estágios também podem usar variáveis de saída de outro estágio. Neste exemplo, há também duas etapas. 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, 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

Nota

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

Dependências de trabalho para trabalho dentro de um estágio

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). Job 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 em todos os 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 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 um estágio diferente, a sintaxe será diferente. No exemplo a seguir, o trabalho run_tests será executado se o trabalho de build_job implantação for definido runTests como 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 shouldTest de implantação build_job como true. Repare que no condition palco 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

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 de seus nomes.

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

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

Poderíamos fazer o seguinte:

foo.*.id

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

Isso retornaria:

[ 1, 2, 3 ]

Tipo de fundição

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 aglutinados no 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 para 1 e 0 quando a expressão é avaliada. A função lt() retorna True quando o parâmetro left é menor que o parâmetro right.

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
Booleano	-	-	Sim	Sim	-
Nulo	Sim	-	Sim	Sim	-
Número	Sim	-	-	Sim	Parcial
Cadeia	Sim	Parcial	Parcial	-	Parcial
Versão	Sim	-	-	Sim	-

Boolean

Para numerar:

• False → 0
• True → 1

Para string:

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

Nulo

• Para Booleano: False
• Para numerar: 0
• Para string: '' (a cadeia de caracteres vazia)

Número

• Para Booleano: 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 string: Converte o número em uma string sem separador de milhares e sem separador decimal.

String

• Para Booleano: '' (a cadeia vazia) → False, qualquer outra string → True
• Para null: '' (a cadeia vazia) → Null, qualquer outra string não conversível
• Para numerar: '' (a cadeia vazia) → 0, caso contrário, executa C#'s Int32.TryParse usando InvariantCulture e as seguintes regras: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowMilhares | AllowTrailingWhite. Se TryParse falhar, então não é conversível.
• Para a versão: executa C#'s Version.TryParse. Deve conter componentes principais e secundários no mínimo. Se TryParse falhar, então não é conversível.

Versão

• Para Booleano: True
• Para string: Major.Minor ou Major.Minor.Build ou Major.Minor.Build.Revision.

FAQ

Quero fazer algo que não seja suportado por expressões. Que 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 trecho pega a BUILD_BUILDNUMBER variável e a divide com Bash. Este script produz duas novas variáveis $MAJOR_RUN e $MINOR_RUN, para os números de execução principais e secundários. As duas variáveis são então usadas para criar duas variáveis $major de pipeline e $minor com task.setvariable. Essas variáveis estão disponíveis para etapas a jusante. Para compartilhar variáveis entre pipelines, consulte 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)"