Expressões

Serviços do Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Importante

Para ver o conteúdo disponível para a sua plataforma, certifique-se de que seleciona a versão correta deste artigo no seletor de versões que está localizado acima do índice. O suporte de funcionalidades difere consoante esteja a trabalhar a partir dos Serviços do Azure DevOps ou de uma versão no local do Azure DevOps Server, cujo nome foi mudado a partir do Team Foundation Server (TFS).
Para saber que versão no local está a utilizar, consulte Procurar a sua plataforma e versão do Azure DevOps

As expressões podem ser utilizadas em vários locais onde precisa de especificar uma cadeia, valor booleano ou numérico ao criar um pipeline. A utilização mais comum de expressões encontra-se em condições para determinar se um trabalho ou passo deve ser executado.

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

Outra utilização comum de expressões é a definição de variáveis. As expressões podem ser avaliadas no tempo de compilação ou no tempo de execução. As expressões de tempo de compilação podem ser utilizadas em qualquer lugar; As expressões runtime podem ser utilizadas em variáveis e condições. As expressões runtime destinam-se a calcular os conteúdos das variáveis e do estado (por 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 sintaxes de expressão de tempo de runtime e compilação é principalmente o contexto disponível. Numa expressão de tempo de compilação (${{ <expression> }}), tem acesso e parameters definiu variablesestaticamente . Numa expressão de runtime ($[ <expression> ]), tem acesso a mais variables , mas sem parâmetros.

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

Literais

Como parte de uma expressão, pode utilizar literais booleanos, nulos, números, cadeias ou versões.

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

Booleano

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

Nulo

Nulo é uma expressão literal especial devolvida a partir de uma falha de dicionário, por exemplo, (variables['noSuch']). Nulo pode ser o resultado de uma expressão, mas não pode ser chamado diretamente numa expressão.

Número

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

String

Tem de ser uma citação única. Por exemplo: 'this is a string'.

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

Pode utilizar um caráter de pipe (|) para cadeias multiline.

myKey: |
  one
  two
  three

Versão

Um número de versão com até quatro segmentos. Tem de começar com um número e conter dois ou três carateres de ponto (.). Por exemplo: 1.2.3.4.

Variáveis

Como parte de uma expressão, pode aceder a variáveis com uma de duas sintaxes:

• Sintaxe do índice: variables['MyVar']
• Sintaxe de dereferência de propriedades: variables.MyVar

Para utilizar a sintaxe de dereferência de propriedades, o nome da propriedade tem de:

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

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

• Se criar pipelines com o YAML, as variáveis de pipeline estão disponíveis.
• Se criar pipelines de compilação com o editor clássico, as variáveis de compilação estão disponíveis.
• Se criar pipelines de versão com o editor clássico, as variáveis de versão estão disponíveis.

As variáveis são sempre cadeias de carateres. Se quiser utilizar valores escritos, deve utilizar os parâmetros .

Nota

Existe uma limitação para utilizar variáveis com expressões para pipelines Clássicos e YAML ao configurar essas variáveis através da IU do separador variáveis. As variáveis 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 sejam avaliadas corretamente. Por exemplo, temos uma variável a cujo valor $[ <expression> ] é utilizado como parte para o valor da variável b. Uma vez que a ordem de processamento de 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 são permitidas através da palavra-chave de 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 incorporadas podem ser utilizadas em expressões.

e

• Avalia se True todos os parâmetros são True
• Parâmetros min: 2. Parâmetros máximos: N
• Lança parâmetros para Booleano para avaliação
• Circuitos curtos após o primeiro False
• Exemplo: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

coalesce

• Avalia os parâmetros por ordem e devolve o valor que não é igual a cadeia nula ou vazia.
• Parâmetros min: 2. Parâmetros máximos: N
• Exemplo: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

contains

• Avalia se o True parâmetro esquerdo Cadeia contém o parâmetro direito
• Parâmetros min: 2. Parâmetros máximos: 2
• Lança parâmetros para Cadeia para avaliação
• Efetua uma comparação ordinal de casos ignorados
• Exemplo: contains('ABCDE', 'BCD') (devolve Verdadeiro)

contémValue

• True Avalia se o parâmetro esquerdo é uma matriz e qualquer item é igual ao parâmetro direito. Também avalia True se o parâmetro esquerdo é um objeto e o valor de qualquer propriedade é igual ao parâmetro direito.
• Parâmetros min: 2. Parâmetros máximos: 2
• Se o parâmetro esquerdo for uma matriz, converta cada item para corresponder ao tipo do parâmetro direito. Se o parâmetro esquerdo for um objeto, converta o valor de cada propriedade para corresponder ao tipo do parâmetro direito. A comparação de igualdade para cada item específico avalia False se a conversão falha.
• Comparação ordinal de casos ignorados para Cadeias
• Curtos circuitos após a primeira partida

Nota

Não existe sintaxe literal num pipeline YAML para especificar uma matriz. Esta função é de utilização limitada em pipelines gerais. Destina-se a ser utilizado no contexto do decorador de pipelines com matrizes fornecidas pelo sistema, como a lista de passos.

Pode utilizar a containsValue expressão para localizar um valor correspondente num objeto. Eis um exemplo que demonstra procurar na lista de ramos 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

• Utilize um objeto complexo e produza-o como JSON.
• Parâmetros min: 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 utilizada numa expressão que defina uma variável. Não pode ser utilizado como parte de uma condição para um passo, trabalho ou fase.
• Avalia um número que é incrementado com cada execução de um pipeline.
• Parâmetros: 2. prefix e seed.
• O prefixo é uma expressão de cadeia. Um valor separado do contador é monitorizado para cada valor exclusivo de prefixo. Deve prefix utilizar carateres UTF-16.
• Seed é o valor inicial do contador

Pode criar um contador que é automaticamente incrementado por um em cada execução do pipeline. Quando define um contador, fornece um prefix e um seed. Eis um exemplo que demonstra isto.

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 será 100. Na segunda execução será 101, desde que o valor de major ainda seja 1.

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

Mais tarde, se editar o ficheiro YAML e definir o valor de major volta para 1, o valor do contador será retomado onde ficou para esse prefixo. Neste exemplo, retoma a 102.

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

Nota

pipeline.startTime não está disponível fora das expressões. pipeline.startTimesystem.pipelineStartTime formatação num objeto de data e hora para que esteja disponível para trabalhar com expressões. O fuso horário predefinido 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)

Eis 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 estão no âmbito de um pipeline. Por outras palavras, o respetivo valor é incrementado para cada execução desse pipeline. Não existem contadores com âmbito de projeto.

endsWith

• Avalia se o True parâmetro esquerdo Cadeia termina com o parâmetro direito
• Parâmetros min: 2. Parâmetros máximos: 2
• Lança parâmetros para Cadeia para avaliação
• Efetua uma comparação ordinal de casos ignorados
• Exemplo: endsWith('ABCDE', 'DE') (devolve Verdadeiro)

eq

• Avalia se os True parâmetros são iguais
• Parâmetros min: 2. Parâmetros máximos: 2
• Converte o parâmetro direito para corresponder ao tipo de parâmetro esquerdo. Devolve False se a conversão falhar.
• Comparação ordinal de casos ignorados para Cadeias
• Exemplo: eq(variables.letters, 'ABC')

formato

• Avalia os parâmetros à direita e insere-os na cadeia de parâmetros à esquerda
• Parâmetros min: 1. Parâmetros máximos: N
• Exemplo: format('Hello {0} {1}', 'John', 'Doe')
• Utiliza os especificadores de formato de data e hora personalizados do .NET para formatação de datas (yyyy, , MMyy, M, ddd, HH, H, mmm, ss, s, f, ff, , ) Kffff
• Exemplo: format('{0:yyyyMMdd}', pipeline.startTime). Neste caso pipeline.startTime , é uma variável de objeto de data/hora especial.
• Escape duplicando chavetas. Por exemplo: format('literal left brace {{ and literal right brace }}')

ge

• True Avalia se o parâmetro esquerdo é maior ou igual ao parâmetro direito
• Parâmetros min: 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 casos ignorados para Cadeias
• Exemplo: ge(5, 5) (devolve Verdadeiro)

gt

• True Avalia se o parâmetro esquerdo é maior do que o parâmetro direito
• Parâmetros min: 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 casos ignorados para Cadeias
• Exemplo: gt(5, 2) (devolve Verdadeiro)

para dentro

• True Avalia se o parâmetro esquerdo é igual a qualquer parâmetro à direita
• Parâmetros min: 1. Parâmetros máximos: N
• Converte parâmetros à direita para corresponder ao tipo de parâmetro esquerdo. A comparação de igualdade avalia False se a conversão falhar.
• Comparação ordinal de casos ignorados para Cadeias
• Circuitos curtos após a primeira partida
• Exemplo: in('B', 'A', 'B', 'C') (devolve Verdadeiro)

aderir

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

Neste exemplo, é adicionado um ponto e vírgula 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

• True Avalia se o parâmetro esquerdo é menor ou igual ao parâmetro direito
• Parâmetros min: 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 casos ignorados para Cadeias
• Exemplo: le(2, 2) (devolve Verdadeiro)

length

• Devolve o comprimento de uma cadeia ou de uma matriz, ou uma que provém do sistema ou que provém de um parâmetro
• Parâmetros min: 1. Parâmetros máximos 1
• Exemplo: length('fabrikam') devolve 8

inferior

• Converte uma cadeia ou valor variável em todos os carateres em minúsculas
• Parâmetros min: 1. Parâmetros máximos 1
• Devolve o equivalente em minúsculas de uma cadeia
• Exemplo: lower('FOO') devolve foo

lt

• True Avalia se o parâmetro esquerdo é menor que o parâmetro direito
• Parâmetros min: 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 casos ignorados para Cadeias
• Exemplo: lt(2, 5) (devolve Verdadeiro)

ne

• Avalia se os True parâmetros não são iguais
• Parâmetros min: 2. Parâmetros máximos: 2
• Converte o parâmetro direito para corresponder ao tipo de parâmetro esquerdo. Devolve True se a conversão falhar.
• Comparação ordinal de casos ignorados para Cadeias
• Exemplo: ne(1, 2) (devolve Verdadeiro)

not

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

notIn

• True Avalia se o parâmetro esquerdo não é igual a qualquer parâmetro à direita
• Parâmetros min: 1. Parâmetros máximos: N
• Converte parâmetros à direita para corresponder ao tipo de parâmetro esquerdo. A comparação de igualdade avalia False se a conversão falhar.
• Comparação ordinal de casos ignorados para Cadeias
• Circuitos curtos após a primeira partida
• Exemplo: notIn('D', 'A', 'B', 'C') (devolve Verdadeiro)

ou

• True Avalia se existe algum parâmetroTrue
• Parâmetros min: 2. Parâmetros máximos: N
• Lança parâmetros para Booleano para avaliação
• Circuitos curtos após o primeiro True
• Exemplo: or(eq(1, 1), eq(2, 3)) (devolve True, short-circuits)

substituir

• Devolve uma nova cadeia na qual todas as instâncias de uma cadeia na instância atual são substituídas por outra cadeia
• Parâmetros min: 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 carateres delimitados especificados
• Parâmetros min: 2. Parâmetros máximos: 2
• O primeiro parâmetro é a cadeia a dividir
• O segundo parâmetro são os carateres delimitadores
• Devolve uma matriz de subcadeias. A matriz inclui cadeias vazias quando os carateres delimitadores aparecem consecutivos 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 }}
  

startsWith

• Avalia se a cadeia de parâmetros True à esquerda começa com o parâmetro direito
• Parâmetros min: 2. Parâmetros máximos: 2
• Lança parâmetros para Cadeia para avaliação
• Efetua uma comparação ordinal de casos ignorados
• Exemplo: startsWith('ABCDE', 'AB') (devolve Verdadeiro)

superior

• Converte uma cadeia ou valor variável em todos os carateres em maiúsculas
• Parâmetros min: 1. Parâmetros máximos 1
• Devolve o equivalente em maiúsculas de uma cadeia
• Exemplo: upper('bah') devolve BAH

xor

• True Avalia se exatamente um parâmetro éTrue
• Parâmetros min: 2. Parâmetros máximos: 2
• Lança parâmetros para Booleano para avaliação
• Exemplo: xor(True, False) (devolve Verdadeiro)

Funções de verificação do estado da tarefa

Pode utilizar as seguintes funções de verificação de estado como expressões em condições, mas não em definições variáveis.

sempre

• Avalia sempre como 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 origens tiver falhado.

cancelado

• Avalia se True o pipeline foi cancelado.

falhou

• Para um passo, equivalente a eq(variables['Agent.JobStatus'], 'Failed').
• Para um trabalho:
  • Sem argumentos, avalia-o True apenas se alguma tarefa anterior no gráfico de dependência falhar.
  • Com os nomes dos trabalhos como argumentos True , avalia apenas se alguma dessas tarefas tiver falhado.

com êxito

• Para um passo, equivalente a in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
• Utilize com dependsOn quando trabalhar com trabalhos e quer avaliar se uma tarefa anterior foi bem-sucedida. As tarefas são concebidas para serem executadas em paralelo enquanto as fases são executadas sequencialmente.
• Para um trabalho:
  • Sem argumentos, avalia apenas se todas as tarefas True anteriores no gráfico de dependências foram bem-sucedidas ou com êxito parcial.
  • Com os nomes dos trabalhos como argumentos, avalia se todas essas tarefas True foram bem-sucedidas ou parcialmente bem-sucedidas.
  • Avalia se False o pipeline foi cancelado.

succeededOrFailed

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

• Para um trabalho:

  • Sem argumentos, avalia se True algum trabalho no grafo de dependência teve êxito ou falhou.
  • Com os nomes dos trabalhos como argumentos, avalia se alguma dessas tarefas True teve êxito ou falhou.
  • Em vez disso, poderá querer utilizar not(canceled()) quando existem tarefas ignoradas anteriores no gráfico de dependências.

  Isto é como always(), exceto que será avaliado False quando o pipeline for cancelado.

Inserção condicional

Pode utilizar if, elseife else cláusulas para atribuir valores variáveis condicionalmente ou definir entradas para tarefas. Também pode executar condicionalmente um passo quando uma condição é cumprida.

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

Para modelos, pode utilizar 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 um passo

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

Palavra-chave each

Pode utilizar a each palavra-chave para percorrer os 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, 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 utilizar o contexto de dependências para referenciar tarefas ou fases anteriores. Pode utilizar dependências para:

• Referenciar o estado da tarefa de uma tarefa anterior
• Referenciar o estado da fase de uma fase anterior
• Referenciar variáveis de saída na tarefa anterior na mesma fase
• Variáveis de saída de referência na fase anterior numa fase
• Referenciar variáveis de saída numa tarefa numa fase anterior na fase seguinte

O contexto é chamado dependencies para trabalhos e fases e funciona muito como variáveis. Dentro de uma tarefa, se se referir a uma variável de saída de uma tarefa noutra fase, o contexto chama-se stageDependencies.

Se tiver problemas com variáveis de saída com carateres de cotação (' ou ") nos mesmos, veja este guia de resolução de problemas.

Fase a fasear dependências

Estruturalmente, o dependencies objeto é um mapa de nomes de tarefas e palcos para results e outputs. Expresso como JSON, teria o seguinte aspeto:

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

Utilize esta forma de dependencies mapear em variáveis ou verificar as condições ao nível da fase. Neste exemplo, a Fase B executa se a Fase A foi bem-sucedida ou ignorada.

Nota

Os exemplos seguintes utilizam a sintaxe do pipeline padrão. Se estiver a utilizar pipelines de implementação, a sintaxe variável e a sintaxe da variável condicional serão diferentes. Para obter informações sobre a sintaxe específica a utilizar, veja Tarefas de implementação.

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 utilizar variáveis de saída de outra fase. Neste exemplo, a Fase B depende de uma variável na Fase A.

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 predefinição, cada fase num pipeline depende da fase imediatamente anterior ao mesmo no ficheiro YAML. Se precisar de fazer referência a uma fase que não seja imediatamente anterior à atual, pode substituir esta predefinição automática ao adicionar uma dependsOn secção à fase.

Dependências de tarefas numa fase

Ao nível da tarefa numa única fase, os dependencies dados não contêm informações ao nível da fase.

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

Neste exemplo, a Tarefa A será sempre ignorada e a Tarefa B será executada. A tarefa C será executada, uma vez que todas as dependências são bem-sucedidas ou ignoradas.

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, a Tarefa B depende de uma variável de saída da Tarefa 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 tarefas para tarefas em várias fases

Ao nível da tarefa, também pode referenciar saídas de uma tarefa numa fase anterior. Isto requer a utilização do stageDependencies contexto.

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

Neste exemplo, a tarefa B1 será executada se a tarefa A1 for ignorada. A tarefa B2 verificará o valor da variável de saída da tarefa A1 para determinar se deve ser executada.

trigger: none

pool:
  vmImage: 'ubuntu-latest'

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 uma tarefa depender de uma variável definida por uma tarefa de implementação numa fase diferente, a sintaxe é diferente. No exemplo seguinte, a tarefa é run_tests executada se a tarefa de build_job implementação estiver definida runTests como true. Repare que a chave utilizada 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:
        ...

Fase consoante a saída da tarefa

Se não forem necessárias alterações após uma compilação, poderá querer ignorar uma fase num pipeline em determinadas condições. Um exemplo é quando está a utilizar o Plano Terraform e pretende acionar a aprovação e aplicar apenas quando o plano contém alterações.

Quando utiliza esta condição numa fase, tem de utilizar a dependencies variável e não stageDependencies.

O exemplo seguinte é um script simples que define uma variável (utilize as suas informações reais do Plano Terraform) num passo numa fase e, em seguida, invoca a segunda fase apenas se a variável tiver um valor específico.

stages:
- stage: plan_dev
  jobs:
  - job: terraform_plan_dev
    steps:
    - bash: echo '##vso[task.setvariable variable=terraform_plan_exitcode;isOutput=true]2'
      name: terraform_plan
- stage: apply_dev
  dependsOn: plan_dev
  condition: eq(dependencies.plan_dev.outputs['terraform_plan_dev.terraform_plan.terraform_plan_exitcode'], '2')
  jobs:
  - job: part_b
    steps:
    - bash: echo "BA"

Se uma fase depender de uma variável definida por uma tarefa de implementação numa fase diferente, a sintaxe é diferente. No exemplo seguinte, a fase test depende da definição de implementação build_jobshouldTest para true. Repare que, na conditiontest fase, 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:
    ...

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

Matrizes filtradas

Ao operar numa coleção de itens, pode utilizar a * sintaxe para aplicar uma matriz filtrada. Uma matriz filtrada devolve todos os objetos/elementos, independentemente dos respetivos nomes.

Por exemplo, considere uma matriz de objetos com o nome foo. Queremos obter uma matriz dos valores da id propriedade em cada objeto na nossa matriz.

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

Podemos fazer o seguinte:

foo.*.id

Isto indica ao sistema para funcionar como uma matriz filtrada e, em foo seguida, selecione a id propriedade.

Isto devolveria:

[ 1, 2, 3 ]

Tipo de fundição

Os valores numa 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 agisados ao tipo de dados relevante e, em seguida, transformados novamente em cadeias de carateres.

Por exemplo, neste YAML, os valores e False são convertidos True em 1 e 0 quando a expressão é avaliada. A função lt() devolve True quando o parâmetro esquerdo é inferior ao parâmetro direito.

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

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

Neste exemplo, os valores variables.emptyString e a cadeia vazia são avaliados como cadeias vazias. A função coalesce() avalia os parâmetros por ordem e devolve o primeiro valor que não é igual a cadeia nula ou vazia.

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

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

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

De/Para	Booleano	Nulo	Número	String	Versão
Booleano	-	-	Yes	Yes	-
Null	Yes	-	Yes	Yes	-
Number	Yes	-	-	Yes	Parcial
String	Yes	Parcial	Parcial	-	Parcial
Versão	Yes	-	-	Yes	-

Booleano

Para número:

• False → 0
• True → 1

Para cadeia:

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

Nulo

• Para Booleano: False
• Para número: 0
• Para cadeia: '' (a cadeia vazia)

Número

• Para Booleano: 0 → False, qualquer outro número → True
• Para a versão: tem de ser maior que zero e tem de conter um decimal diferente de zero. Tem de ser inferior a Int32.MaxValue (também componente decimal).
• Para cadeia: converte o número numa cadeia sem separador de milhares e sem separador decimal.

String

• Para Booleano: '' (a cadeia vazia) → False, qualquer outra cadeia → True
• Para nulo: '' (a cadeia vazia) → Null, qualquer outra cadeia não convertível
• Para numerar: '' (a cadeia vazia) → 0; caso contrário, executa C#'s Int32.TryParse com InvariantCulture e as seguintes regras: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Se TryParse falhar, não será descapotável.
• Para a versão: executa o ficheiro de C#.Version.TryParse Tem de conter, no mínimo, o componente Principal e Secundário. Se TryParse falhar, não será descapotável.

Versão

• Para Booleano: True
• Para cadeia: 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 expandir a funcionalidade pipelines?

Pode personalizar o Pipeline com um script que inclua uma expressão. Por exemplo, este fragmento utiliza a variável e divide-a BUILD_BUILDNUMBER com o Bash. Este script produz duas novas variáveis, $MAJOR_RUN e $MINOR_RUN, para os números de execução principais e menores. Em seguida, $major as duas variáveis são utilizadas para criar duas variáveis de pipeline e $minor com task.setvariable. Estas variáveis estão disponíveis para passos a jusante. Para partilhar variáveis entre pipelines, veja Grupos 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)"