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 variables
estaticamente .
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-Z
0-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ãoTrue
- 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 avaliaTrue
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
eseed
. - 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.startTime
system.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
, ,MM
yy
,M
,dd
d
,HH
,H
,m
mm
,ss
,s
,f
,ff
, , )K
ffff
- Exemplo:
format('{0:yyyyMMdd}', pipeline.startTime)
. Neste casopipeline.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')
devolvefoo
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')
(devolvehttp://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')
devolveBAH
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.
- Sem argumentos, avalia-o
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.
- Sem argumentos, avalia apenas se todas as tarefas
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á avaliadoFalse
quando o pipeline for cancelado.- Sem argumentos, avalia se
Inserção condicional
Pode utilizar if
, elseif
e 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.
Pode utilizar if
para atribuir valores variáveis condicionalmente ou definir entradas para tarefas. Também pode executar condicionalmente um passo quando uma condição é cumprida.
As elseif
cláusulas e else
estão disponíveis a partir do Azure DevOps 2022 e não estão disponíveis para Azure DevOps Server 2020 e versões anteriores do Azure DevOps.
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_job
shouldTest
para true
. Repare que, na condition
test
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#'sInt32.TryParse
com InvariantCulture e as seguintes regras: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. SeTryParse
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. SeTryParse
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)"