Definir variáveis
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
As variáveis oferecem uma forma conveniente de inserir os principais bits de dados em várias partes do pipeline. O uso mais comum de variáveis é definir um valor que você pode usar em seu pipeline. Todas as variáveis são cadeias de caracteres e são mutáveis. O valor de uma variável pode mudar de execução para execução ou de trabalho para trabalho do pipeline.
Quando você define a mesma variável em vários locais com o mesmo nome, a variável com escopo mais local tem precedência. Portanto, uma variável definida no nível do trabalho pode substituir uma variável definida no nível de fase. Uma variável definida no nível de fase substitui uma variável definida no nível raiz do pipeline. Uma variável definida no nível raiz do pipeline substitui uma variável definida na interface do usuário de configurações do pipeline. Para saber mais sobre como trabalhar com variáveis definidas no trabalho, no estágio e no nível raiz, consulte Escopo da variável.
Você pode usar variáveis com expressões para atribuir valores condicionalmente e personalizar ainda mais os pipelines.
As variáveis são diferentes dos parâmetros de runtime. Os parâmetros de runtime são tipados e disponíveis durante a análise de modelo.
Variáveis definidas pelo usuário
Ao definir uma variável, você pode usar sintaxes diferentes (macro, expressão de modelo ou runtime) e a sintaxe que você usa determina onde, no pipeline, sua variável é renderizada.
Em pipelines YAML, você pode definir variáveis no nível raiz, de fase e de trabalho. Você também pode especificar variáveis fora de um pipeline YAML na interface do usuário. Quando você define uma variável na interface do usuário, essa variável pode ser criptografada e definida como secreta.
As variáveis definidas pelo usuário podem ser definidas como somente leitura. Há restrições de nomenclatura para variáveis (exemplo: você não pode usar secret no início de um nome de variável).
Você pode usar um grupo de variáveis para disponibilizar variáveis em vários pipelines.
Use modelos para definir variáveis em um arquivo usado em vários pipelines.
Variáveis de várias linhas definidas pelo usuário
O Azure DevOps dá suporte a variáveis de várias linhas, mas há algumas limitações.
Componentes downstream, como tarefas de pipeline, podem não manipular os valores de variável corretamente.
O Azure DevOps não alterará os valores de variáveis definidos pelo usuário. Os valores variáveis precisam ser formatados corretamente antes de serem passados como variáveis de várias linhas. Ao formatar sua variável, evite caracteres especiais, não use nomes restritos e use um formato de delimitador que funcione para o sistema operacional do agente.
Variáveis de várias linhas se comportam de maneira diferente, dependendo do sistema operacional. Para evitar isso, formate variáveis de várias linhas corretamente para o sistema operacional de destino.
O Azure DevOps nunca altera valores de variáveis, mesmo que você forneça formatação incompatível.
Variáveis do sistema
Além das variáveis definidas pelo usuário, o Azure Pipelines tem variáveis de sistema com valores predefinidos. Por exemplo, a variável Build.BuildId predefinida fornece a ID de cada build e pode ser usada para identificar diferentes execuções de pipeline. Você pode usar a variável Build.BuildId em scripts ou tarefas quando precisar de um valor exclusivo.
Se você estiver usando YAML ou pipelines de build clássicos, confira variáveis predefinidas para obter uma lista abrangente de variáveis do sistema.
Se você estiver usando pipelines de lançamento clássicos, confira Variáveis de versão.
As variáveis do sistema são definidas com o valor atual delas quando você executa o pipeline. Algumas variáveis são definidas automaticamente. Como um autor de pipeline ou usuário final, você altera o valor de uma variável do sistema antes da execução do pipeline.
As variáveis de sistema são somente leitura.
Variáveis de ambiente
As variáveis de ambiente são específicas para o sistema operacional que você está usando. Eles são injetados em um pipeline de maneiras específicas para cada plataforma. O formato corresponde a como as variáveis de ambiente são formatadas para sua plataforma de script específica.
Em sistemas UNIX (macOS e Linux), as variáveis de ambiente têm o formato $NAME. No Windows, o formato é %NAME% para lote e $env:NAME no PowerShell.
As variáveis definidas pelo sistema e pelo usuário também são injetadas como variáveis de ambiente para sua plataforma. Quando as variáveis são convertidas em variáveis de ambiente, os nomes de variáveis passam a ficar em maiúsculas e os pontos se transformam em sublinhados. Por exemplo, o nome de variável any.variable se torna $ANY_VARIABLE.
Há restrições de nomenclatura de variáveis para variáveis de ambiente (exemplo: você não pode usar secret no início de um nome de variável).
Restrições de nomenclatura de recursos
As variáveis de ambiente e definidas pelo usuário podem consistir em letras, números e nos caracteres .e _. Não use prefixos de variáveis reservados pelo sistema. Eles são endpoint, input, secret, path e securefile. Qualquer variável que comece com uma dessas cadeias de caracteres (independentemente da capitalização) não estará disponível para suas tarefas e scripts.
Noções básicas sobre sintaxe de variáveis
O Azure Pipelines suporta três maneiras diferentes de referenciar variáveis: macro, expressão de modelo e expressão de runtime. Você pode usar cada sintaxe para uma finalidade diferente e cada uma delas tem algumas limitações.
Em um pipeline, as variáveis de expressão de modelo (${{ variables.var }}) são processadas em tempo de build, antes do runtime iniciar. A sintaxe de macro ($(var)) de variáveis é processada durante o runtime, antes da execução de uma tarefa. As expressões de runtime ($[variables.var]) também são processadas durante o runtime, mas devem ser usadas com condições e expressões. Quando se usa uma expressão de runtime, ela deve ocupar todo o lado direito de uma definição.
Neste exemplo, você pode ver que a expressão de modelo ainda tem o valor inicial da variável depois que a variável é atualizada. O valor das atualizações da variável de sintaxe de macro. O valor da expressão de modelo não é alterado porque todas as variáveis de expressão de modelo são processadas em tempo de build antes da execução das tarefas. Por outro lado, as variáveis de sintaxe de macro são avaliadas antes da execução de cada tarefa.
variables:
- name: one
value: initialValue
steps:
- script: |
echo ${{ variables.one }} # outputs initialValue
echo $(one)
displayName: First variable pass
- bash: echo "##vso[task.setvariable variable=one]secondValue"
displayName: Set new variable value
- script: |
echo ${{ variables.one }} # outputs initialValue
echo $(one) # outputs secondValue
displayName: Second variable pass
Variáveis de sintaxe de macro
A maioria dos exemplos de documentação usa a sintaxe de macro ($(var)). A sintaxe de macro foi projetada para interpolar valores de variáveis em entradas de tarefa e em outras variáveis.
Variáveis com sintaxe de macro são processadas antes que uma tarefa seja executada durante o runtime. O runtime ocorre após a expansão do modelo. Quando o sistema encontra uma expressão de macro, ele substitui a expressão pelo conteúdo da variável. Se não houver nenhuma variável com esse nome, a expressão de macro não será alterada. Por exemplo, se $(var) não puder ser substituída, $(var) não será substituída por nada.
As variáveis de sintaxe de macro permanecem inalteradas sem nenhum valor, porque um valor vazio como $() pode significar algo para a tarefa que você está executando, e o agente não deve presumir que você deseja que esse valor seja substituído. Por exemplo, se você usar $(foo) para fazer referência à variável foo em uma tarefa do Bash, substituir todas as expressões $() na entrada para a tarefa poderá interromper seus scripts Bash.
As variáveis de macro só são expandidas quando usadas para um valor, não como uma palavra-chave. Os valores aparecem no lado direito de uma definição de pipeline. O seguinte é válido: key: $(value). O seguinte não é válido: $(key): value. As variáveis de macro não são expandidas quando usadas para exibir um nome de trabalho em linha. Em vez disso, você precisa usar a propriedade displayName.
Observação
As variáveis de sintaxe de macro são expandidas apenas para stages, jobs e steps.
Você não pode, por exemplo, usar a sintaxe de macro dentro de um resource ou trigger.
Este exemplo usa a sintaxe macro com Bash, PowerShell e uma tarefa de script. A sintaxe para chamar uma variável com sintaxe de macro é a mesma para todos os três.
variables:
- name: projectName
value: contoso
steps:
- bash: echo $(projectName)
- powershell: echo $(projectName)
- script: echo $(projectName)
Expressão de modelo
Você pode usar a sintaxe de expressão de modelo para expandir parâmetros de modelo e variáveis (${{ variables.var }}). As variáveis de modelo processam em tempo de build e são substituídas antes do início do runtime. As expressões de modelo são projetadas para reutilizar partes do YAML como modelos.
As variáveis de modelo se unem silenciosamente a cadeias de caracteres vazias quando nenhum valor substituto é encontrado. As expressões de modelo, ao contrário das expressões de macro e runtime, podem aparecer como chaves (lado esquerdo) ou valores (lado direito). O seguinte é válido: ${{ variables.key }} : ${{ variables.value }}.
Sintaxe da expressão lambda
Você pode usar a sintaxe de expressão de runtime para variáveis expandidas em runtime ($[variables.var]). As variáveis de expressão de runtime se agrupam silenciosamente a cadeias de caracteres vazias quando nenhum valor substituto é encontrado. Use expressões de runtime em condições de trabalho para dar suporte à execução condicional de trabalhos ou fases inteiras.
As variáveis de expressão de runtime só são expandidas quando são usadas para um valor, não como uma palavra-chave. Os valores aparecem no lado direito de uma definição de pipeline. O seguinte é válido: key: $[variables.value]. O seguinte não é válido: $[variables.key]: value. A expressão de runtime precisa ocupar todo o lado direito de um par chave-valor. Por exemplo, key: $[variables.value] é válida, mas key: $[variables.value] foo não é válida.
| Sintaxe | Exemplo | Quando ele é processado? | Onde ele se expande em uma definição de pipeline? | Como ele é renderizado quando não encontrado? |
|---|---|---|---|---|
| Macro | $(var) |
runtime antes de uma tarefa ser executada | valor (lado direito) | imprime $(var) |
| expressão de modelo | ${{ variables.var }} |
tempo de build | chave ou valor (lado esquerdo ou direito) | cadeia de caracteres vazia |
| expressão de runtime | $[variables.var] |
runtime | valor (lado direito) | cadeia de caracteres vazia |
Qual sintaxe devo usar?
Use a sintaxe de macro se estiver fornecendo uma cadeia de caracteres segura ou uma entrada de variável predefinida para uma tarefa.
Escolha uma expressão de runtime se você estiver trabalhando com condições e expressões. No entanto, não use uma expressão de runtime se você não quiser que sua variável vazia seja impressa (exemplo: $[variables.var]). Por exemplo, se você tiver uma lógica condicional que dependa de uma variável ter um valor específico ou nenhum valor. Nesse caso, você deve usar uma expressão de macro.
Normalmente, uma variável de modelo é o padrão a ser usado. Ao aproveitar as variáveis de modelo, o pipeline injetará totalmente o valor da variável no pipeline na compilação do pipeline. Isso é útil ao tentar depurar pipelines. Você pode baixar os arquivos de log e avaliar o valor totalmente expandido que está sendo substituído. Como a variável é substituída, você não deve aproveitar a sintaxe do modelo para valores confidenciais.
Definir variáveis no pipeline
No caso mais comum, você define as variáveis e as usa no arquivo YAML. Isso também permite que você acompanhe as alterações na variável em seu sistema de controle de versão. Você também pode definir variáveis na interface do usuário de configurações de pipeline (consulte a guia Clássico) e referenciá-las em seu YAML.
Aqui está um exemplo que mostra como definir duas variáveis, configuration e platform, e usá-las posteriormente em etapas. Para usar uma variável em uma instrução YAML, encapsule-a em $(). As variáveis não podem ser usadas para definir um repository em uma instrução YAML.
# Set variables once
variables:
configuration: debug
platform: x64
steps:
# Use them once
- task: MSBuild@1
inputs:
solution: solution1.sln
configuration: $(configuration) # Use the variable
platform: $(platform)
# Use them again
- task: MSBuild@1
inputs:
solution: solution2.sln
configuration: $(configuration) # Use the variable
platform: $(platform)
Escopos de variável
No arquivo YAML, você pode definir uma variável em vários escopos:
- No nível raiz, para disponibilizá-la para todos os trabalhos no pipeline.
- No nível de fase, para disponibilizá-lo apenas para uma fase específica.
- No nível de trabalho, para disponibilizá-la somente para um trabalho específico.
Quando você define uma variável na parte superior de um YAML, a variável está disponível para todos os trabalhos e fases no pipeline e é uma variável global. As variáveis globais definidas em um YAML não são visíveis na interface do usuário das configurações do pipeline.
As variáveis no nível de trabalho substituem variáveis no nível raiz e de fase. Variáveis no nível de estágio substituem variáveis no nível raiz.
variables:
global_variable: value # this is available to all jobs
jobs:
- job: job1
pool:
vmImage: 'ubuntu-latest'
variables:
job_variable1: value1 # this is only available in job1
steps:
- bash: echo $(global_variable)
- bash: echo $(job_variable1)
- bash: echo $JOB_VARIABLE1 # variables are available in the script environment too
- job: job2
pool:
vmImage: 'ubuntu-latest'
variables:
job_variable2: value2 # this is only available in job2
steps:
- bash: echo $(global_variable)
- bash: echo $(job_variable2)
- bash: echo $GLOBAL_VARIABLE
A saída de ambos os trabalhos tem esta aparência:
# job1
value
value1
value1
# job2
value
value2
value
Especificar variáveis
Nos exemplos anteriores, a palavra-chave variables é seguida por uma lista de pares chave-valor.
As chaves são os nomes das variáveis e os valores são os valores de variável.
Há outra sintaxe útil quando você deseja usar modelos de variável ou grupos de variáveis.
Com modelos, as variáveis podem ser definidas em um YAML e incluídas em outro arquivo YAML.
Os grupos de variáveis são um conjunto de variáveis que você pode usar em vários pipelines. Eles permitem que você gerencie e organize variáveis que são comuns a vários estágios em um só lugar.
Use essa sintaxe para modelos de variáveis e grupos de variáveis no nível raiz de um pipeline.
Nessa sintaxe alternativa, a palavra-chave variables usa uma lista de especificadores de variável.
Os especificadores de variável são name para uma variável regular, group para um grupo de variáveis e template para incluir um modelo de variável.
O exemplo a seguir demonstra os três.
variables:
# a regular variable
- name: myvariable
value: myvalue
# a variable group
- group: myvariablegroup
# a reference to a variable template
- template: myvariabletemplate.yml
Saiba mais sobre a reutilização de variáveis com modelos.
Acessar variáveis por meio do ambiente
Observe que as variáveis também são disponibilizadas para scripts por meio de variáveis de ambiente. A sintaxe para usar essas variáveis de ambiente depende da linguagem de script.
O nome é em maiúsculas e o . é substituído pelo _. Isso é inserido automaticamente no ambiente de processo. Estes são alguns exemplos:
- Script de lote:
%VARIABLE_NAME% - Script do PowerShell:
$env:VARIABLE_NAME - Script Bash:
$VARIABLE_NAME
Importante
Variáveis predefinidas que contêm caminhos de arquivo são convertidas para o estilo apropriado (estilo do Windows C:\foo\ versus estilo Unix /foo/) com base no tipo de shell e no tipo de host do agente. Se você estiver executando tarefas de script bash no Windows, deverá usar o método de variável de ambiente para acessar essas variáveis em vez do método de variável de pipeline, para garantir que você tenha o estilo de caminho de arquivo correto.
Definir variáveis secretas
Dica
As variáveis secretas não são exportadas automaticamente como variáveis de ambiente. Para usar variáveis secretas em seus scripts, mapeie-as explicitamente para variáveis de ambiente. Para obter mais informações, consulte Definir variáveis secretas.
Não defina variáveis secretas no arquivo YAML. Os sistemas operacionais geralmente registram comandos para os processos executados e você não gostaria que o log incluísse um segredo que você passou como uma entrada. Use o ambiente do script ou mapeie a variável dentro do bloco variables para passar segredos para o pipeline.
Observação
O Azure Pipelines faz um esforço para mascarar segredos ao emitir dados para logs de pipeline, para que você possa ver variáveis adicionais, dados mascarados na saída e logs que não são definidos como segredos.
Você precisa definir variáveis secretas na interface do usuário das configurações do pipeline para o pipeline. Essas variáveis têm como escopo o pipeline em que estão definidas. Você também pode definir variáveis secretas em grupos de variáveis.
Para definir segredos na interface da Web, siga estas etapas:
- Acesse a página Pipelines, selecione o pipeline apropriado e escolha Editar.
- Localize as Variáveis desse pipeline.
- Adicione ou atualize a variável.
- Selecione a opção Manter esse valor em segredo para armazenar a variável de maneira criptografada.
- Salve o pipeline.
As variáveis secretas são criptografadas em estado inativo com uma chave RSA de 2.048 bits. Os segredos estão disponíveis no agente para uso por tarefas e scripts. Seja cauteloso com quem tem acesso para alterar o pipeline.
Importante
Fazemos um esforço para mascarar a exibição de segredos na saída do Azure Pipelines, mas ainda é preciso tomar precauções. Nunca ecoe segredos como saída. Alguns sistemas operacionais registram argumentos de linha de comando. Nunca transmita segredos na linha de comando. Em vez disso, a recomendação é mapear os segredos para variáveis de ambiente.
Nunca mascare as subcadeias de caracteres de segredos. Por exemplo, se "abc123" for definido como um segredo, "abc" não será mascarado nos logs. Isso evita mascarar segredos em um nível muito granular, o que torna os logs ilegíveis. Por esse motivo, os segredos não devem conter dados estruturados. Por exemplo, se "{ "foo": "bar" }" for definido como um segredo, "bar" não será mascarado nos logs.
Ao contrário de uma variável normal, elas não são descriptografadas automaticamente em variáveis de ambiente para scripts. Você precisa mapear explicitamente as variáveis secretas.
O exemplo a seguir mostra como mapear e usar uma variável secreta chamada mySecret em scripts do PowerShell e do Bash. Duas variáveis globais são definidas. GLOBAL_MYSECRET é atribuído o valor de uma variável mySecret secreta, e GLOBAL_MY_MAPPED_ENV_VAR é atribuído o valor de uma variável nonSecretVariable não secreta. Ao contrário de uma variável de pipeline normal, não há nenhuma variável de ambiente chamada MYSECRET.
A tarefa do PowerShell executa um script para imprimir as variáveis.
$(mySecret): esta é uma referência direta à variável secreta e funciona.$env:MYSECRET: isso tenta acessar a variável secreta como uma variável de ambiente, que não funciona porque as variáveis secretas não são mapeadas automaticamente para variáveis de ambiente.$env:GLOBAL_MYSECRET: isso tenta acessar a variável secreta por meio de uma variável global, que também não funciona porque as variáveis secretas não podem ser mapeadas dessa maneira.$env:GLOBAL_MY_MAPPED_ENV_VAR: isso acessa a variável não secreta por meio de uma variável global, que funciona.$env:MY_MAPPED_ENV_VAR: isso acessa a variável secreta por meio de uma variável de ambiente específica da tarefa, que é a maneira recomendada de mapear variáveis secretas para variáveis de ambiente.
variables:
GLOBAL_MYSECRET: $(mySecret) # this will not work because the secret variable needs to be mapped as env
GLOBAL_MY_MAPPED_ENV_VAR: $(nonSecretVariable) # this works because it's not a secret.
steps:
- powershell: |
Write-Host "Using an input-macro works: $(mySecret)"
Write-Host "Using the env var directly does not work: $env:MYSECRET"
Write-Host "Using a global secret var mapped in the pipeline does not work either: $env:GLOBAL_MYSECRET"
Write-Host "Using a global non-secret var mapped in the pipeline works: $env:GLOBAL_MY_MAPPED_ENV_VAR"
Write-Host "Using the mapped env var for this task works and is recommended: $env:MY_MAPPED_ENV_VAR"
env:
MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable
- bash: |
echo "Using an input-macro works: $(mySecret)"
echo "Using the env var directly does not work: $MYSECRET"
echo "Using a global secret var mapped in the pipeline does not work either: $GLOBAL_MYSECRET"
echo "Using a global non-secret var mapped in the pipeline works: $GLOBAL_MY_MAPPED_ENV_VAR"
echo "Using the mapped env var for this task works and is recommended: $MY_MAPPED_ENV_VAR"
env:
MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable
A saída de ambas as tarefas no script anterior teria esta aparência:
Using an input-macro works: ***
Using the env var directly does not work:
Using a global secret var mapped in the pipeline does not work either:
Using a global non-secret var mapped in the pipeline works: foo
Using the mapped env var for this task works and is recommended: ***
Você também pode usar variáveis secretas fora dos scripts. Por exemplo, você pode mapear variáveis secretas para tarefas usando a definição variables. Este exemplo mostra como usar as variáveis secretas $(vmsUser) e $(vmsAdminPass) em uma tarefa de cópia de arquivo do Azure.
variables:
VMS_USER: $(vmsUser)
VMS_PASS: $(vmsAdminPass)
pool:
vmImage: 'ubuntu-latest'
steps:
- task: AzureFileCopy@4
inputs:
SourcePath: 'my/path'
azureSubscription: 'my-subscription'
Destination: 'AzureVMs'
storage: 'my-storage'
resourceGroup: 'my-rg'
vmsAdminUserName: $(VMS_USER)
vmsAdminPassword: $(VMS_PASS)
Variáveis secretas de referência em grupos de variáveis
Este exemplo mostra como fazer referência a um grupo de variáveis no arquivo YAML e também como adicionar variáveis no YAML. Há duas variáveis usadas do grupo de variáveis: user e token. A variável token é secreta e é mapeada para a variável de ambiente $env:MY_MAPPED_TOKEN para que possa ser referenciada no YAML.
Esse YAML faz uma chamada REST para recuperar uma lista de versões e gera o resultado.
variables:
- group: 'my-var-group' # variable group
- name: 'devopsAccount' # new variable defined in YAML
value: 'contoso'
- name: 'projectName' # new variable defined in YAML
value: 'contosoads'
steps:
- task: PowerShell@2
inputs:
targetType: 'inline'
script: |
# Encode the Personal Access Token (PAT)
# $env:USER is a normal variable in the variable group
# $env:MY_MAPPED_TOKEN is a mapped secret variable
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $env:USER,$env:MY_MAPPED_TOKEN)))
# Get a list of releases
$uri = "https://vsrm.dev.azure.com/$(devopsAccount)/$(projectName)/_apis/release/releases?api-version=5.1"
# Invoke the REST call
$result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}
# Output releases in JSON
Write-Host $result.value
env:
MY_MAPPED_TOKEN: $(token) # Maps the secret variable $(token) from my-var-group
Importante
Por padrão, com repositórios do GitHub, as variáveis secretas associadas ao pipeline não são disponibilizadas para builds de solicitação de pull de forks. Para obter mais informações, confira Contribuições de forks.
Compartilhar variáveis entre pipelines
Para compartilhar variáveis entre vários pipelines em seu projeto, use a interface da Web. Em Biblioteca, use grupos de variáveis.
Usar variáveis de saída por meio de tarefas
Algumas tarefas definem variáveis de saída, que você pode consumir em etapas downstream, trabalhos e fases. No YAML, você pode acessar variáveis entre trabalhos e fases usando dependências.
Ao referenciar trabalhos de matriz em tarefas downstream, você precisará usar uma sintaxe diferente. Confira Definir uma variável de saída de vários trabalhos. Você também precisa usar uma sintaxe diferente para variáveis em trabalhos de implantação. Consulte Suporte para variáveis de saída em trabalhos de implantação.
Algumas tarefas definem variáveis de saída, que você pode consumir em etapas downstream e trabalhos dentro da mesma fase. No YAML, você pode acessar variáveis entre trabalhos usando dependências.
- Para fazer referência a uma variável de uma tarefa diferente dentro do mesmo trabalho, use
TASK.VARIABLE. - Para fazer referência a uma variável de uma tarefa de um trabalho diferente, use
dependencies.JOB.outputs['TASK.VARIABLE'].
Observação
Por padrão, cada fase em um pipeline depende daquele imediatamente anterior a ele no arquivo YAML. Se você precisar se referir a uma fase que não seja imediatamente anterior à atual, poderá substituir esse padrão automático adicionando uma seção dependsOn à fase.
Observação
Os exemplos a seguir usam a sintaxe de pipeline padrão. Se você estiver usando pipelines de implantação, a sintaxe variável e a variável condicional serão diferentes. Para obter informações sobre a sintaxe específica a ser usada, confira Trabalhos de implantação.
Para esses exemplos, suponha que temos uma tarefa chamada MyTask, que define uma variável de saída chamada MyVar.
Saiba mais sobre a sintaxe em Expressões – Dependências.
Usar saídas no mesmo trabalho
steps:
- task: MyTask@1 # this step generates the output variable
name: ProduceVar # because we're going to depend on it, we need to name the step
- script: echo $(ProduceVar.MyVar) # this step uses the output variable
Usar saídas em um trabalho diferente
jobs:
- job: A
steps:
# assume that MyTask generates an output variable called "MyVar"
# (you would learn that from the task's documentation)
- task: MyTask@1
name: ProduceVar # because we're going to depend on it, we need to name the step
- job: B
dependsOn: A
variables:
# map the output variable from A into this job
varFromA: $[ dependencies.A.outputs['ProduceVar.MyVar'] ]
steps:
- script: echo $(varFromA) # this step uses the mapped-in variable
Usar saídas em uma fase diferente
Para usar a saída de um estágio diferente, o formato para fazer referência a variáveis é stageDependencies.STAGE.JOB.outputs['TASK.VARIABLE']. No nível de estágio, mas não no nível de trabalho, é possível usar essas variáveis em condições.
As variáveis de saída só estão disponíveis na próxima fase downstream. Se várias fases consumirem a mesma variável de saída, use a condição dependsOn.
stages:
- stage: One
jobs:
- job: A
steps:
- task: MyTask@1 # this step generates the output variable
name: ProduceVar # because we're going to depend on it, we need to name the step
- stage: Two
dependsOn:
- One
jobs:
- job: B
variables:
# map the output variable from A into this job
varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
steps:
- script: echo $(varFromA) # this step uses the mapped-in variable
- stage: Three
dependsOn:
- One
- Two
jobs:
- job: C
variables:
# map the output variable from A into this job
varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
steps:
- script: echo $(varFromA) # this step uses the mapped-in variable
Você também pode passar variáveis entre fases com uma entrada de arquivo. Para fazer isso, você precisará definir variáveis na segunda fase no nível do trabalho e, em seguida, passar as variáveis como entradas env:.
## script-a.sh
echo "##vso[task.setvariable variable=sauce;isOutput=true]crushed tomatoes"
## script-b.sh
echo 'Hello file version'
echo $skipMe
echo $StageSauce
## azure-pipelines.yml
stages:
- stage: one
jobs:
- job: A
steps:
- task: Bash@3
inputs:
filePath: 'script-a.sh'
name: setvar
- bash: |
echo "##vso[task.setvariable variable=skipsubsequent;isOutput=true]true"
name: skipstep
- stage: two
jobs:
- job: B
variables:
- name: StageSauce
value: $[ stageDependencies.one.A.outputs['setvar.sauce'] ]
- name: skipMe
value: $[ stageDependencies.one.A.outputs['skipstep.skipsubsequent'] ]
steps:
- task: Bash@3
inputs:
filePath: 'script-b.sh'
name: fileversion
env:
StageSauce: $(StageSauce) # predefined in variables section
skipMe: $(skipMe) # predefined in variables section
- task: Bash@3
inputs:
targetType: 'inline'
script: |
echo 'Hello inline version'
echo $(skipMe)
echo $(StageSauce)
A saída de fases no pipeline anterior tem esta aparência:
Hello inline version
true
crushed tomatoes
Listar variáveis
Você pode listar todas as variáveis em seu pipeline com o comando az pipelines variable list. Para começar, confira Introdução à CLI do Azure DevOps.
az pipelines variable list [--org]
[--pipeline-id]
[--pipeline-name]
[--project]
Parâmetros
- org: a URL da organização do Azure DevOps. Você pode configurar a organização padrão usando
az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado usandogit config. Exemplo:--org https://dev.azure.com/MyOrganizationName/. - pipeline-id: obrigatório se pipeline-name não for fornecido. ID do pipeline.
- pipeline-name: obrigatório se pipeline-id não for fornecido, mas ignorado se pipeline-id for fornecido. Nome do pipeline.
- project: nome ou ID do projeto. Você pode configurar o grupo padrão usando
az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado usandogit config.
Exemplo
O comando a seguir lista todas as variáveis no pipeline com a ID 12 e mostra o resultado em formato de tabela.
az pipelines variable list --pipeline-id 12 --output table
Name Allow Override Is Secret Value
------------- ---------------- ----------- ------------
MyVariable False False platform
NextVariable False True platform
Configuration False False config.debug
Definir variáveis em scripts
Os scripts podem definir variáveis que serão consumidas posteriormente nas etapas subsequentes no pipeline. Todas as variáveis definidas por esse método são tratadas como cadeias de caracteres. Para definir uma variável de um script, use uma sintaxe de comando e imprima para stdout.
Definir uma variável com escopo de trabalho a partir de um script
Para definir uma variável a partir de um script, use o task.setvariable comando logging. Isso atualiza as variáveis de ambiente para os trabalhos subsequentes. Trabalhos subsequentes têm acesso à nova variável com sintaxe de macro e em tarefas como variáveis de ambiente.
Quando issecret é definido como true, o valor da variável é salvo como segredo e mascarado do log. Para obter mais informações sobre variáveis secretas, confira comandos de registro em log.
steps:
# Create a variable
- bash: |
echo "##vso[task.setvariable variable=sauce]crushed tomatoes" # remember to use double quotes
# Use the variable
# "$(sauce)" is replaced by the contents of the `sauce` variable by Azure Pipelines
# before handing the body of the script to the shell.
- bash: |
echo my pipeline variable is $(sauce)
A variável de pipeline também será adicionada ao ambiente das etapas subsequentes. Você não pode usar a variável na etapa definida.
steps:
# Create a variable
# Note that this does not update the environment of the current script.
- bash: |
echo "##vso[task.setvariable variable=sauce]crushed tomatoes"
# An environment variable called `SAUCE` has been added to all downstream steps
- bash: |
echo "my environment variable is $SAUCE"
- pwsh: |
Write-Host "my environment variable is $env:SAUCE"
A saída do pipeline anterior.
my environment variable is crushed tomatoes
my environment variable is crushed tomatoes
Definir uma variável de saída de vários trabalhos
Se você quiser disponibilizar uma variável para trabalhos futuros, precisará marcá-la como uma variável de saída usando isOutput=true. Em seguida, você pode mapeá-lo para trabalhos futuros usando a sintaxe $[] e incluindo o nome da etapa que define a variável. Variáveis de saída de vários trabalhos só funcionam para trabalhos na mesma fase.
Para passar variáveis para trabalhos em fases diferentes, use a sintaxe de dependências de fase.
Observação
Por padrão, cada fase em um pipeline depende daquele imediatamente anterior a ele no arquivo YAML. Portanto, cada fase pode usar variáveis de saída da fase anterior. Para acessar outras fases, você precisará alterar o grafo de dependência, por exemplo, se a fase 3 exigir uma variável da fase 1, você precisará declarar uma dependência explícita na fase 1.
Ao criar uma variável de saída de vários trabalhos, você deve atribuir a expressão a uma variável. Neste YAML, $[ dependencies.A.outputs['setvarStep.myOutputVar'] ] é atribuído à variável $(myVarFromJobA).
jobs:
# Set an output variable from job A
- job: A
pool:
vmImage: 'windows-latest'
steps:
- powershell: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the value"
name: setvarStep
- script: echo $(setvarStep.myOutputVar)
name: echovar
# Map the variable into job B
- job: B
dependsOn: A
pool:
vmImage: 'ubuntu-latest'
variables:
myVarFromJobA: $[ dependencies.A.outputs['setvarStep.myOutputVar'] ] # map in the variable
# remember, expressions require single quotes
steps:
- script: echo $(myVarFromJobA)
name: echovar
A saída do pipeline anterior.
this is the value
this is the value
Se você estiver definindo uma variável de uma fase para outra, use stageDependencies.
stages:
- stage: A
jobs:
- job: A1
steps:
- bash: echo "##vso[task.setvariable variable=myStageOutputVar;isOutput=true]this is a stage output var"
name: printvar
- stage: B
dependsOn: A
variables:
myVarfromStageA: $[ stageDependencies.A.A1.outputs['printvar.myStageOutputVar'] ]
jobs:
- job: B1
steps:
- script: echo $(myVarfromStageA)
Se você estiver definindo uma variável de uma matriz ou fatia para referenciar a variável ao acessá-la de um trabalho downstream, você precisará incluir:
- O nome do trabalho.
- A etapa.
jobs:
# Set an output variable from a job with a matrix
- job: A
pool:
vmImage: 'ubuntu-latest'
strategy:
maxParallel: 2
matrix:
debugJob:
configuration: debug
platform: x64
releaseJob:
configuration: release
platform: x64
steps:
- bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the $(configuration) value"
name: setvarStep
- bash: echo $(setvarStep.myOutputVar)
name: echovar
# Map the variable from the debug job
- job: B
dependsOn: A
pool:
vmImage: 'ubuntu-latest'
variables:
myVarFromJobADebug: $[ dependencies.A.outputs['debugJob.setvarStep.myOutputVar'] ]
steps:
- script: echo $(myVarFromJobADebug)
name: echovar
jobs:
# Set an output variable from a job with slicing
- job: A
pool:
vmImage: 'ubuntu-latest'
parallel: 2 # Two slices
steps:
- bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the slice $(system.jobPositionInPhase) value"
name: setvarStep
- script: echo $(setvarStep.myOutputVar)
name: echovar
# Map the variable from the job for the first slice
- job: B
dependsOn: A
pool:
vmImage: 'ubuntu-latest'
variables:
myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ]
steps:
- script: "echo $(myVarFromJobsA1)"
name: echovar
Certifique-se de prefixar o nome do trabalho para as variáveis de saída de um trabalho de implantação. Nesse caso, o nome do trabalho é A:
jobs:
# Set an output variable from a deployment
- deployment: A
pool:
vmImage: 'ubuntu-latest'
environment: staging
strategy:
runOnce:
deploy:
steps:
- bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the deployment variable value"
name: setvarStep
- bash: echo $(setvarStep.myOutputVar)
name: echovar
# Map the variable from the job for the first slice
- job: B
dependsOn: A
pool:
vmImage: 'ubuntu-latest'
variables:
myVarFromDeploymentJob: $[ dependencies.A.outputs['A.setvarStep.myOutputVar'] ]
steps:
- bash: "echo $(myVarFromDeploymentJob)"
name: echovar
Definir as variáveis 
Definir as variáveis 
Definir as variáveis Definir variáveis usando expressões
Você pode definir uma variável usando uma expressão. Já encontramos um caso disso para definir uma variável para a saída de outra de um trabalho anterior.
- job: B
dependsOn: A
variables:
myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ] # remember to use single quotes
Você pode usar qualquer uma das expressões compatíveis para definir uma variável. Aqui está um exemplo de como definir uma variável para atuar como um contador que começa em 100, é incrementado em 1 para cada execução e é redefinido para 100 todos os dias.
jobs:
- job:
variables:
a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
steps:
- bash: echo $(a)
Para obter mais informações sobre contadores, dependências e outras expressões, confira expressões.
Definir variáveis configuráveis para etapas
Você pode definir settableVariables dentro de uma etapa ou especificar que nenhuma variável pode ser definida.
Neste exemplo, o script não pode definir uma variável.
steps:
- script: echo This is a step
target:
settableVariables: none
Neste exemplo, o script permite a variável sauce, mas não a variável secretSauce. Você verá um aviso na página de execução do pipeline.
steps:
- bash: |
echo "##vso[task.setvariable variable=Sauce;]crushed tomatoes"
echo "##vso[task.setvariable variable=secretSauce;]crushed tomatoes with garlic"
target:
settableVariables:
- sauce
name: SetVars
- bash:
echo "Sauce is $(sauce)"
echo "secretSauce is $(secretSauce)"
name: OutputVars
Permitir na hora da fila
Se uma variável aparecer no bloco variables de um arquivo YAML, o valor dela será fixo e não poderá ser substituído no tempo de espera. A melhor prática é definir suas variáveis em um arquivo YAML, mas há momentos em que isso não é razoável. Por exemplo, talvez você queira definir uma variável secreta, em vez de ter a variável exposta em seu YAML. Ou talvez seja necessário definir manualmente um valor de variável durante a execução do pipeline.
Você tem duas opções para definir valores de tempo de espera. Você pode definir uma variável na interface do usuário e selecionar a opção Permitir que os usuários substituam esse valor ao executar esse pipeline ou você pode usar parâmetros de runtime. Se a variável não for um segredo, a melhor prática será usar parâmetros de runtime.
Para definir uma variável no momento da fila, adicione uma nova variável no pipeline e selecione a opção de substituição.
Para permitir que uma variável seja definida no tempo de espera, verifique se a variável também não aparece no bloco variables de um pipeline ou trabalho. Se você definir uma variável no bloco de variáveis de um YAML e na interface do usuário, o valor no YAML terá prioridade.
Expansão de variáveis
Quando você define uma variável com o mesmo nome em vários escopos, a precedência a seguir se aplica (primeiro, a precedência mais alta).
- Variável no nível de trabalho definida no arquivo YAML
- Variável no nível de fase definida no arquivo YAML
- Variável no nível de pipeline definida no arquivo YAML
- Conjunto de variáveis na hora da fila
- Conjunto de variáveis de pipeline na interface do usuário das configurações de pipeline
No exemplo a seguir, a mesma variável a é definida no nível do pipeline e no nível do trabalho no arquivo YAML. Ela também é definida em um grupo de variáveis G e como uma variável na interface do usuário de configurações do pipeline.
variables:
a: 'pipeline yaml'
stages:
- stage: one
displayName: one
variables:
- name: a
value: 'stage yaml'
jobs:
- job: A
variables:
- name: a
value: 'job yaml'
steps:
- bash: echo $(a) # This will be 'job yaml'
Quando você definir uma variável com o mesmo nome no mesmo escopo, o último valor definido terá precedência.
stages:
- stage: one
displayName: Stage One
variables:
- name: a
value: alpha
- name: a
value: beta
jobs:
- job: I
displayName: Job I
variables:
- name: b
value: uno
- name: b
value: dos
steps:
- script: echo $(a) #outputs beta
- script: echo $(b) #outputs dos
Observação
Ao definir uma variável no arquivo YAML, não a defina no editor da Web como configurável no momento da fila. Atualmente, você não pode alterar variáveis definidas no arquivo YAML no tempo de espera. Se você precisar que uma variável seja configurável no tempo de espera, não a defina no arquivo YAML.
As variáveis são expandidas uma vez quando a execução é iniciada e novamente no início de cada etapa. Por exemplo:
jobs:
- job: A
variables:
a: 10
steps:
- bash: |
echo $(a) # This will be 10
echo '##vso[task.setvariable variable=a]20'
echo $(a) # This will also be 10, since the expansion of $(a) happens before the step
- bash: echo $(a) # This will be 20, since the variables are expanded just before the step
Há duas etapas no exemplo anterior. A expansão de $(a) ocorre uma vez no início do trabalho e uma vez no início de cada uma das duas etapas.
Como as variáveis são expandidas no início de um trabalho, você não pode usá-las em uma estratégia. No exemplo a seguir, você não pode usar a variável a para expandir a matriz de trabalho, pois a variável só está disponível no início de cada trabalho expandido.
jobs:
- job: A
variables:
a: 10
strategy:
matrix:
x:
some_variable: $(a) # This does not work
Se a variável a for uma variável de saída de um trabalho anterior, você poderá usá-la em um trabalho futuro.
- job: A
steps:
- powershell: echo "##vso[task.setvariable variable=a;isOutput=true]10"
name: a_step
# Map the variable into job B
- job: B
dependsOn: A
variables:
some_variable: $[ dependencies.A.outputs['a_step.a'] ]
Expansão recursiva
No agente, as variáveis referenciadas usando a sintaxe $( ) são expandidas recursivamente.
Por exemplo:
variables:
myInner: someValue
myOuter: $(myInner)
steps:
- script: echo $(myOuter) # prints "someValue"
displayName: Variable is $(myOuter) # display name is "Variable is someValue"