Usar variáveis em pipelines de versão clássica
Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019
O uso de variáveis em pipelines de liberação Classic é uma maneira conveniente de trocar e transportar dados em todo o pipeline. Cada variável é armazenada como uma cadeia de caracteres e seu valor pode mudar entre execuções de pipeline.
Ao contrário dos parâmetros de tempo de execução, que só estão disponíveis no momento da análise do modelo, as variáveis nos pipelines de versão clássica são acessíveis durante todo o processo de implantação
Ao configurar tarefas para implantar seu aplicativo em cada estágio do pipeline de versão Classic, as variáveis podem ajudá-lo a:
Simplifique a personalização: defina um pipeline de implantação genérico uma vez e adapte-o facilmente para diferentes estágios. Por exemplo, use uma variável para representar a cadeia de conexão de uma implantação da Web, ajustando seu valor conforme necessário para cada estágio. Estas são conhecidas como variáveis personalizadas.
Aproveite as informações contextuais: acesse detalhes sobre o contexto da versão, como um estágio, um artefato ou o agente que executa a implantação. Por exemplo, seus scripts podem exigir o local de compilação para download ou o diretório de trabalho do agente para criar arquivos temporários. Estas são referidas como variáveis padrão.
Nota
Para pipelines YAML, consulte variáveis definidas pelo usuário e variáveis predefinidas para obter mais detalhes.
Variáveis predefinidas
As variáveis padrão fornecem informações essenciais sobre o contexto de execução para suas tarefas e scripts em execução. Essas variáveis permitem que você acesse detalhes sobre o sistema, a versão, o estágio ou o agente no qual eles estão sendo executados.
Com exceção de System.Debug, as variáveis padrão são somente leitura, com seus valores definidos automaticamente pelo sistema.
Algumas das variáveis mais significativas são descritas nas tabelas a seguir. Para exibir a lista completa, consulte Exibir os valores atuais de todas as variáveis.
Variáveis do sistema
Nome da variável | Description |
---|---|
System.TeamFoundationServerUri | A URL da conexão de serviço no Azure Pipelines. Use isso de seus scripts ou tarefas para chamar APIs REST do Azure Pipelines. Exemplo: https://fabrikam.vsrm.visualstudio.com/ |
System.TeamFoundationCollectionUri | A URL da coleção Team Foundation ou Azure Pipelines. Use isso de seus scripts ou tarefas para chamar APIs REST em outros serviços, como controle de compilação e versão. Exemplo: https://dev.azure.com/fabrikam/ |
System.CollectionId | A ID da coleção à qual esta compilação ou versão pertence. Exemplo: 6c6f3423-1c84-4625-995a-f7f143a1e43d |
System.DefinitionId | A ID do pipeline de liberação ao qual a versão atual pertence. Exemplo: 1 |
System.TeamProject | O nome do projeto ao qual esta compilação ou versão pertence. Exemplo: Fabrikam |
System.TeamProjectId | A ID do projeto ao qual esta compilação ou versão pertence. Exemplo: 79f5c12e-3337-4151-be41-a268d2c73344 |
System.ArtifactsDirectory | O diretório para o qual os artefatos são baixados durante a implantação de uma versão. O diretório é limpo antes de cada implantação se exigir que os artefatos sejam baixados para o agente. O mesmo que Agent.ReleaseDirectory e System.DefaultWorkingDirectory. Exemplo: C:\agent\_work\r1\a |
System.DefaultWorkingDirectory | O diretório para o qual os artefatos são baixados durante a implantação de uma versão. O diretório é limpo antes de cada implantação se exigir que os artefatos sejam baixados para o agente. O mesmo que Agent.ReleaseDirectory e System.ArtifactsDirectory. Exemplo: C:\agent\_work\r1\a |
System.WorkFolder | O diretório de trabalho para este agente, onde subpastas são criadas para cada compilação ou versão. O mesmo que Agent.RootDirectory e Agent.WorkFolder. Exemplo: C:\agent\_work |
System.Debug | Esta é a única variável de sistema que pode ser definida pelos usuários. Defina isso como true para executar a versão no modo de depuração para ajudar na localização de falhas. Exemplo: true |
Variáveis de liberação
Nome da variável | Description |
---|---|
Release.AttemptNumber | O número de vezes que esta versão é implantada neste estágio. Exemplo: 1 |
Release.DefinitionEnvironmentId | A ID do estágio no pipeline de liberação correspondente. Exemplo: 1 |
Release.DefinitionId | A ID do pipeline de liberação ao qual a versão atual pertence. Exemplo: 1 |
Release.DefinitionName | O nome do pipeline de liberação ao qual a versão atual pertence. Exemplo: fabrikam-cd |
Release.Deployment.RequestedFor | O nome para exibição da identidade que disparou (iniciou) a implantação atualmente em andamento. Exemplo: Mateo Escobedo |
Release.Deployment.RequestedForEmail | O endereço de e-mail da identidade que acionou (iniciou) a implantação atualmente em andamento. Exemplo: mateo@fabrikam.com |
Release.Deployment.RequestedForId | A ID da identidade que disparou (iniciou) a implantação atualmente em andamento. Exemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
Release.DeploymentID | A ID da implantação. Único por trabalho. Exemplo: 254 |
Release.DeployPhaseID | A ID da fase em que a implantação está sendo executada. Exemplo: 127 |
Release.EnvironmentId | A ID da instância do estágio em uma versão para a qual a implantação está atualmente em andamento. Exemplo: 276 |
Release.EnvironmentName | O nome do estágio para o qual a implantação está atualmente em andamento. Exemplo: Dev |
Release.EnvironmentUri | O URI da instância do estágio em uma versão para a qual a implantação está atualmente em andamento. Exemplo: vstfs://ReleaseManagement/Environment/276 |
Release.Environments. {nome do estágio}.status | O status de implantação do estágio. Exemplo: InProgress |
Release.PrimaryArtifactSourceAlias | O alias da fonte de artefato primária. Exemplo: fabrikam\_web |
Release.Reason | O motivo da implantação. Os valores suportados são:ContinuousIntegration - a versão iniciada em Continuous Deployment após a conclusão de uma compilação.Manual - A liberação foi iniciada manualmente.None - O motivo da implantação não foi especificado.Schedule - O lançamento começou a partir de um cronograma. |
Release.ReleaseDescription | A descrição do texto fornecida no momento do lançamento. Exemplo: Critical security patch |
Release.ReleaseId | O identificador do registro de lançamento atual. Exemplo: 118 |
Release.ReleaseName | O nome da versão atual. Exemplo: Release-47 |
Release.ReleaseUri | O URI da versão atual. Exemplo: vstfs://ReleaseManagement/Release/118 |
Release.ReleaseWebURL | O URL desta versão. Exemplo: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary |
Release.RequestedFor | O nome para exibição da identidade que disparou a liberação. Exemplo: Mateo Escobedo |
Release.RequestedForEmail | O endereço de e-mail da identidade que acionou a liberação. Exemplo: mateo@fabrikam.com |
Release.RequestedForId | A ID da identidade que disparou a liberação. Exemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
Release.SkipArtifactsBaixar | Valor booleano que especifica se o download de artefatos para o agente deve ou não ser ignorado. Exemplo: FALSE |
Release.TriggeringArtifact.Alias | O pseudônimo do artefato que desencadeou a liberação. Isso fica vazio quando a liberação foi agendada ou acionada manualmente. Exemplo: fabrikam\_app |
Variáveis do estágio de liberação
Nome da variável | Description |
---|---|
Release.Environments. {nome artístico}. Situação | O status de implantação desta versão dentro de um estágio especificado. Exemplo: NotStarted |
Variáveis do agente
Nome da variável | Description |
---|---|
Agent.Name | O nome do agente conforme registrado no pool de agentes. É provável que isso seja diferente do nome do computador. Exemplo: fabrikam-agent |
Agent.MachineName | O nome do computador no qual o agente está configurado. Exemplo: fabrikam-agent |
Agent.Version | A versão do software do agente. Exemplo: 2.109.1 |
Agent.JobName | O nome do trabalho que está sendo executado, como Release ou Build. Exemplo: Release |
Agent.HomeDirectory | A pasta onde o agente está instalado. Esta pasta contém o código e os recursos para o agente. Exemplo: C:\agent |
Agent.ReleaseDirectory | O diretório para o qual os artefatos são baixados durante a implantação de uma versão. O diretório é limpo antes de cada implantação se exigir que os artefatos sejam baixados para o agente. O mesmo que System.ArtifactsDirectory e System.DefaultWorkingDirectory. Exemplo: C:\agent\_work\r1\a |
Agent.RootDirectory | O diretório de trabalho para este agente, onde subpastas são criadas para cada compilação ou versão. O mesmo que Agent.WorkFolder e System.WorkFolder. Exemplo: C:\agent\_work |
Agent.WorkFolder | O diretório de trabalho para este agente, onde subpastas são criadas para cada compilação ou versão. O mesmo que Agent.RootDirectory e System.WorkFolder. Exemplo: C:\agent\_work |
Agent.DeploymentGroupId | A ID do grupo de implantação no qual o agente está registrado. Isso está disponível apenas em trabalhos de grupo de implantação. Exemplo: 1 |
Variáveis de artefatos de liberação
Para cada artefato referenciado em uma versão, você pode usar as seguintes variáveis de artefato. Observe que nem todas as variáveis se aplicam a todos os tipos de artefatos. A tabela abaixo lista variáveis de artefato padrão e fornece exemplos de seus valores com base no tipo de artefato. Se um exemplo estiver vazio, isso indica que a variável não é aplicável para esse tipo de artefato.
Substitua o espaço reservado {alias}
pelo valor especificado para o alias de origem do artefato ou pelo valor padrão gerado para o pipeline de liberação.
Nome da variável | Description |
---|---|
Release.Artifacts. {alias}. DefinitionId | O identificador do pipeline ou repositório de compilação. Exemplos: Azure Pipelines: 1 GitHub: fabrikam/asp |
Release.Artifacts. {alias}. DefinitionName | O nome do pipeline ou repositório de compilação. Exemplos: Azure Pipelines: fabrikam-ci CVF: $/fabrikam Git: fabrikam GitHub: fabrikam/asp (main) |
Release.Artifacts. {alias}. Número de compilação | O número de compilação ou o identificador de confirmação. Exemplos: Azure Pipelines: 20170112.1 Jenkins: 20170112.1 CVF: Changeset 3 Git: 38629c964 GitHub: 38629c964 |
Release.Artifacts. {alias}. BuildId | O identificador de compilação. Exemplos: Azure Pipelines: 130 Jenkins: 130 GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11 |
Release.Artifacts. {alias}. BuildURI | A URL para a compilação. Exemplos: Azure Pipelines: vstfs://build-release/Build/130 GitHub: https://github.com/fabrikam/asp |
Release.Artifacts. {alias}. SourceBranch | O caminho completo e o nome da ramificação a partir da qual a fonte foi construída. Exemplos: Azure Pipelines: refs/heads/main |
Release.Artifacts. {alias}. SourceBranchName | O nome apenas da ramificação a partir da qual a fonte foi construída. Exemplos: Azure Pipelines: main |
Release.Artifacts. {alias}. FonteVersão | O compromisso que foi construído. Exemplos: Azure Pipelines: bc0044458ba1d9298cdc649cb5dcf013180706f7 |
Release.Artifacts. {alias}. Repositório.Provedor | O tipo de repositório a partir do qual a fonte foi construída. Exemplos: Azure Pipelines: Git |
Release.Artifacts. {alias}. RequestedForID | O identificador da conta que disparou a compilação. Exemplos: Azure Pipelines: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
Release.Artifacts. {alias}. SolicitadoPara | O nome da conta que solicitou a compilação. Exemplos: Azure Pipelines: Mateo Escobedo |
Release.Artifacts. {alias}. Tipo | O tipo de fonte de artefato, como Build.Examples Azure Pipelines: Build Jenkins: Jenkins CVF: TFVC Git: Git GitHub: GitHub |
Release.Artifacts. {alias}. PullRequest.TargetBranch | O caminho completo e o nome da ramificação que é o destino de uma solicitação pull. Essa variável é inicializada somente se a liberação for acionada por um fluxo de solicitação pull. Exemplos: Azure Pipelines: refs/heads/main |
Release.Artifacts. {alias}. PullRequest.TargetBranchName | O nome somente da ramificação que é o destino de uma solicitação pull. Essa variável é inicializada somente se a liberação for acionada por um fluxo de solicitação pull. Exemplos: Azure Pipelines: main |
Variáveis primárias do artefato
Em pipelines de liberação clássicos, se você estiver usando vários artefatos, poderá designar um como o artefato principal. Os Pipelines do Azure preencherão as seguintes variáveis para o artefato primário designado.
Nome da variável | O mesmo que |
---|---|
Build.DefinitionId | Release.Artifacts. {Alias de artefato primário}. DefinitionId |
Build.DefinitionName | Release.Artifacts. {Alias de artefato primário}. DefinitionName |
Build.BuildNumber | Release.Artifacts. {Alias de artefato primário}. Número de compilação |
Build.BuildId | Release.Artifacts. {Alias de artefato primário}. BuildId |
Build.BuildURI | Release.Artifacts. {Alias de artefato primário}. BuildURI |
Build.SourceBranch | Release.Artifacts. {Alias de artefato primário}. SourceBranch |
Build.SourceBranchName | Release.Artifacts. {Alias de artefato primário}. SourceBranchName |
Build.SourceVersion | Release.Artifacts. {Alias de artefato primário}. FonteVersão |
Build.Repository.Provider | Release.Artifacts. {Alias de artefato primário}. Repositório.Provedor |
Build.RequestedForID | Release.Artifacts. {Alias de artefato primário}. RequestedForID |
Build.RequestedFor | Release.Artifacts. {Alias de artefato primário}. SolicitadoPara |
Build.Type | Release.Artifacts. {Alias de artefato primário}. Tipo |
Build.PullRequest.TargetBranch | Release.Artifacts. {Alias de artefato primário}. PullRequest.TargetBranch |
Build.PullRequest.TargetBranchName | Release.Artifacts. {Alias de artefato primário}. PullRequest.TargetBranchName |
Usar variáveis padrão
Você pode usar as variáveis padrão de duas maneiras: como parâmetros para tarefas em um pipeline de liberação ou dentro de seus scripts.
Você pode usar uma variável padrão diretamente como uma entrada para uma tarefa. Por exemplo, para passar Release.Artifacts.{Artifact alias}.DefinitionName
como um argumento para uma tarefa do PowerShell para um artefato com ASPNET4.CI como alias, você usaria $(Release.Artifacts.ASPNET4.CI.DefinitionName)
.
Para usar uma variável padrão em seu script, você deve primeiro substituir o .
nos nomes de variáveis padrão por _
. Por exemplo, para imprimir o valor de Release.Artifacts.{Artifact alias}.DefinitionName
um artefato com ASPNET4.CI como alias em um script do PowerShell, use $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME
. Observe que o alias original, ASPNET4.CI, é substituído por ASPNET4_CI.
Variáveis personalizadas
As variáveis personalizadas podem ser definidas em vários escopos.
Grupos de variáveis: use grupos de variáveis para compartilhar valores em todas as definições em um projeto. Isso é útil quando você deseja usar os mesmos valores em definições, estágios e tarefas dentro de um projeto e gerenciá-los a partir de um único local. Defina e gerencie grupos de variáveis na Biblioteca de Pipelines>.
Variáveis de pipeline de liberação: use variáveis de pipeline de liberação para compartilhar valores em todos os estágios dentro de um pipeline de liberação. Isso é ideal para cenários em que você precisa de um valor consistente entre estágios e tarefas, com a capacidade de atualizá-lo de um único local. Defina e gerencie essas variáveis na guia Variáveis do pipeline de liberação. Na página Variáveis de pipeline, defina a lista suspensa Escopo como Release ao adicionar uma variável.
Variáveis de estágio: use variáveis de estágio para compartilhar valores dentro de um estágio específico de um pipeline de liberação. Isso é útil para valores que diferem de estágio para estágio, mas são consistentes em todas as tarefas dentro de um estágio. Defina e gerencie essas variáveis na guia Variáveis do pipeline de liberação. Na página Variáveis de Pipeline, defina a lista suspensa Escopo como o ambiente apropriado ao adicionar uma variável.
O uso de variáveis personalizadas nos níveis de projeto, pipeline de liberação e estágio ajuda a:
Evite a duplicação de valores, facilitando a atualização de todas as ocorrências com uma única alteração.
Proteja valores confidenciais impedindo que sejam visualizados ou modificados pelos utilizadores. Para marcar uma variável como segura (secreta), selecione o
ícone ao lado da variável.
Importante
Os valores das variáveis ocultas (secret) são armazenados com segurança no servidor e não podem ser visualizados pelos usuários depois de serem salvos. Durante a implantação, o Azure Pipelines descriptografa esses valores quando referenciados por tarefas e os passa para o agente por meio de um canal HTTPS seguro.
Nota
A criação de variáveis personalizadas pode substituir variáveis padrão. Por exemplo, se você definir uma variável Path personalizada em um agente do Windows, ela substituirá a variável $env:Path, o que pode impedir que o PowerShell seja executado corretamente.
Usar variáveis personalizadas
Para usar variáveis personalizadas em suas tarefas, coloque o nome da variável entre parênteses e preceda-o com um $ caractere. Por exemplo, se você tiver uma variável chamada adminUserName, poderá inserir seu valor atual em uma tarefa como $(adminUserName)
.
Nota
Variáveis de diferentes grupos ligadas a um pipeline no mesmo escopo (por exemplo, trabalho ou estágio) podem entrar em conflito, levando a resultados imprevisíveis. Para evitar isso, certifique-se de que as variáveis em todos os seus grupos de variáveis tenham nomes exclusivos.
Definir e modificar suas variáveis em um script
Para definir ou modificar uma variável a partir de um script, use o task.setvariable
comando log. O valor da variável atualizada tem como escopo o trabalho que está sendo executado e não persiste entre trabalhos ou estágios. Observe que os nomes das variáveis são transformados em maiúsculas, com "." e " " substituídos por "_".
Por exemplo, Agent.WorkFolder
passa a AGENT_WORKFOLDER
.
- No Windows, acesse essa variável como
%AGENT_WORKFOLDER%
ou$env:AGENT_WORKFOLDER
. - No Linux e macOS, use
$AGENT_WORKFOLDER
o .
Gorjeta
Você pode executar um script em:
- Um agente do Windows usando uma tarefa de script em lote ou uma tarefa do PowerShell.
- Um agente macOS ou Linux usando uma tarefa de script Shell.
Script em lote
Definir as
sauce
variáveis e secret.Sauce
@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic
Leia as variáveis
Argumentos
"$(sauce)" "$(secret.Sauce)"
Script
@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil the secret)
Saída do console a partir da leitura das variáveis:
No problem reading crushed tomatoes or crushed tomatoes
But I cannot read
But I can read ******** (but the log is redacted so I do not spoil the secret)
Exibir os valores atuais de todas as variáveis
Selecione Pipelines Releases e, em seguida, selecione seu pipeline de>release.
Abra a vista de resumo da sua versão e selecione a fase em que está interessado. Na lista de etapas, escolha Inicializar trabalho.
Isso abre os logs para esta etapa. Role para baixo para ver os valores usados pelo agente para este trabalho.
Executar uma versão no modo de depuração
Executar uma versão no modo de depuração pode ajudá-lo a diagnosticar e resolver problemas ou falhas, exibindo informações adicionais durante a execução da versão. Você pode ativar o modo de depuração para toda a versão ou apenas para as tarefas dentro de um estágio de lançamento específico.
Para habilitar o modo de depuração para uma versão inteira, adicione uma variável nomeada
System.Debug
com o valortrue
à guia Variáveis do pipeline de versão.Para habilitar o modo de depuração para um estágio específico, abra a caixa de diálogo Configurar estágio no menu de atalho do estágio e adicione uma variável nomeada
System.Debug
com o valortrue
à guia Variáveis .Como alternativa, crie um grupo de variáveis contendo uma variável nomeada
System.Debug
com o valortrue
e vincule esse grupo de variáveis ao pipeline de liberação.
Gorjeta
Se você encontrar um erro relacionado às conexões de serviço ARM do Azure, consulte Como solucionar problemas de conexões de serviço do Azure Resource Manager para obter mais detalhes.