Использование классических переменных выпуска и артефактов
Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019
Классические переменные выпуска и артефактов — удобный способ обмена данными и транспорта на протяжении всего конвейера. Каждая переменная хранится в виде строки, и ее значение может изменяться между разными выполнениями конвейера.
Переменные отличаются от параметров среды выполнения, доступных только во время анализа шаблона.
При создании задач по развертыванию приложения на каждом этапе в процессах CI/CD DevOps переменные помогут вам:
Определите более универсальный конвейер развертывания один раз, а затем легко настройте его для каждого этапа. Например, переменную можно использовать для представления строка подключения для веб-развертывания, а значение этой переменной можно изменить с одного этапа на другой. Это пользовательские переменные.
Используйте сведения о контексте конкретного выпуска, этапа, артефактов или агента , в котором выполняется конвейер развертывания. Например, скрипту может потребоваться доступ к расположению сборки, чтобы скачать ее, или в рабочий каталог агента для создания временных файлов. Это переменные по умолчанию.
Примечание.
Дополнительные сведения о конвейерах YAML см. в определяемых пользователем переменных и предопределенных переменных.
Переменные по умолчанию
Сведения о контексте выполнения предоставляются для выполнения задач с помощью переменных по умолчанию. Задачи и скрипты могут использовать эти переменные для поиска сведений о системе, выпуске, стадии или агенте, в котором они выполняются. За исключением System.Debug, эти переменные доступны только для чтения, и их значения автоматически задаются системой. Некоторые из наиболее важных переменных описаны в следующих таблицах. Чтобы просмотреть полный список, просмотрите текущие значения всех переменных.
Совет
Текущие значения всех переменных для выпуска можно просмотреть и использовать переменную по умолчанию для запуска выпуска в режиме отладки.
Системные
| Имя переменной | Description |
|---|---|
| System.TeamFoundationServerUri | URL-адрес подключения службы в Azure Pipelines. Используйте это из скриптов или задач для вызова REST API Azure Pipelines. Пример: https://fabrikam.vsrm.visualstudio.com/ |
| System.TeamFoundationCollectionUri | URL-адрес коллекции Team Foundation или Azure Pipelines. Используйте это из скриптов или задач для вызова REST API в других службах, таких как управление сборкой и версиями. Пример: https://dev.azure.com/fabrikam/ |
| System.CollectionId | Идентификатор коллекции, к которой принадлежит эта сборка или выпуск. Пример: 6c6f3423-1c84-4625-995a-f7f143a1e43d |
| System.DefinitionId | Идентификатор конвейера выпуска, к которому принадлежит текущий выпуск. Пример: 1 |
| System.TeamProject | Имя проекта, к которому принадлежит эта сборка или выпуск. Пример: Fabrikam |
| System.TeamProjectId | Идентификатор проекта, которому принадлежит эта сборка или выпуск. Пример: 79f5c12e-3337-4151-be41-a268d2c73344 |
| System.ArtifactsDirectory | Каталог, в который загружаются артефакты во время развертывания выпуска. Каталог очищается перед каждым развертыванием, если требуется скачивание артефактов в агент. То же, что и Agent.ReleaseDirectory и System.DefaultWorkingDirectory. Пример: C:\agent\_work\r1\a |
| System.DefaultWorkingDirectory | Каталог, в который загружаются артефакты во время развертывания выпуска. Каталог очищается перед каждым развертыванием, если требуется скачивание артефактов в агент. То же, что и Agent.ReleaseDirectory и System.ArtifactsDirectory. Пример: C:\agent\_work\r1\a |
| System.WorkFolder | Рабочий каталог для этого агента, в котором вложенные папки создаются для каждой сборки или выпуска. То же, что и Agent.RootDirectory и Agent.WorkFolder. Пример: C:\agent\_work |
| System.Debug | Это единственная системная переменная, которую могут задать пользователи. Задайте для этого значение true, чтобы запустить выпуск в режиме отладки, чтобы помочь в поиске ошибок. Пример: true |
Выпуск
| Имя переменной | Description |
|---|---|
| Release.AttemptNumber | Количество развертываний этого выпуска на этом этапе. Пример: 1 |
| Release.DefinitionEnvironmentId | Идентификатор этапа в соответствующем конвейере выпуска. Пример: 1 |
| Release.DefinitionId | Идентификатор конвейера выпуска, к которому принадлежит текущий выпуск. Пример: 1 |
| Release.DefinitionName | Имя конвейера выпуска, к которому относится текущий выпуск. Пример: fabrikam-cd |
| Release.Deployment.RequestedFor | Отображаемое имя удостоверения, которое активировало (запущено) развертывание в настоящее время. Пример: Mateo Escobedo |
| Release.Deployment.RequestedForEmail | Адрес электронной почты удостоверения, активировав (запущенного) развертывание в настоящее время. Пример: mateo@fabrikam.com |
| Release.Deployment.RequestedForId | Идентификатор удостоверения, активировав (запущенного) развертывание в настоящее время. Пример: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.DeploymentID | Идентификатор развертывания. Уникальное задание. Пример: 254 |
| Release.DeployPhaseID | Идентификатор этапа, в котором выполняется развертывание. Пример: 127 |
| Release.EnvironmentId | Идентификатор экземпляра этапа в выпуске, в котором выполняется развертывание. Пример: 276 |
| Release.EnvironmentName | Имя этапа, на котором выполняется развертывание. Пример: Dev |
| Release.EnvironmentUri | URI экземпляра этапа в выпуске, в котором выполняется развертывание. Пример: vstfs://ReleaseManagement/Environment/276 |
| Release.Environments. {stage-name}.status | Состояние развертывания этапа. Пример: InProgress |
| Release.PrimaryArtifactSourceAlias | Псевдоним источника первичного артефакта Пример: fabrikam\_web |
| Release.Reason | Причина развертывания. Поддерживаются значения:ContinuousIntegration — выпуск, запущенный в непрерывном развертывании после завершения сборки.Manual — выпуск, запущенный вручную.None — причина развертывания не указана.Schedule — выпуск, запущенный из расписания. |
| Release.ReleaseDescription | Текстовое описание, предоставленное во время выпуска. Пример: Critical security patch |
| Release.ReleaseId | Идентификатор текущей записи выпуска. Пример: 118 |
| Release.ReleaseName | Имя текущего выпуска. Пример: Release-47 |
| Release.ReleaseUri | Универсальный код ресурса (URI) текущего выпуска. Пример: vstfs://ReleaseManagement/Release/118 |
| Release.ReleaseWebURL | URL-адрес для этого выпуска. Пример: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary |
| Release.RequestedFor | Отображаемое имя удостоверения, которое активировало выпуск. Пример: Mateo Escobedo |
| Release.RequestedForEmail | Адрес электронной почты удостоверения, активировав выпуск. Пример: mateo@fabrikam.com |
| Release.RequestedForId | Идентификатор удостоверения, активировав выпуск. Пример: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.SkipArtifactsDownload | Логическое значение, указывающее, следует ли пропускать скачивание артефактов в агент. Пример: FALSE |
| Release.TriggeringArtifact.Alias | Псевдоним артефакта, активировавшего выпуск. Это пусто, если выпуск был запланирован или активирован вручную. Пример: fabrikam\_app |
Этап выпуска
| Имя переменной | Description |
|---|---|
| Release.Environments. {имя сцены}. Статус | Состояние развертывания этого выпуска на заданном этапе. Пример: NotStarted |
Агент
| Имя переменной | Description |
|---|---|
| Agent.Name | Имя агента, зарегистрированного в пуле агентов. Скорее всего, это отличается от имени компьютера. Пример: fabrikam-agent |
| Agent.MachineName | Имя компьютера, на котором настроен агент. Пример: fabrikam-agent |
| Agent.Version | Версия программного обеспечения агента. Пример: 2.109.1 |
| Agent.JobName | Имя выполняемого задания, например выпуска или сборки. Пример: Release |
| Agent.HomeDirectory | Папка, в которой установлен агент. Эта папка содержит код и ресурсы агента. Пример: C:\agent |
| Agent.ReleaseDirectory | Каталог, в который загружаются артефакты во время развертывания выпуска. Каталог очищается перед каждым развертыванием, если требуется скачивание артефактов в агент. Аналогично System.ArtifactsDirectory и System.DefaultWorkingDirectory. Пример: C:\agent\_work\r1\a |
| Agent.RootDirectory | Рабочий каталог для этого агента, в котором вложенные папки создаются для каждой сборки или выпуска. То же, что и agent.WorkFolder и System.WorkFolder. Пример: C:\agent\_work |
| Agent.WorkFolder | Рабочий каталог для этого агента, в котором вложенные папки создаются для каждой сборки или выпуска. То же, что и Agent.RootDirectory и System.WorkFolder. Пример: C:\agent\_work |
| Agent.DeploymentGroupId | Идентификатор группы развертывания, в который регистрируется агент. Это доступно только в заданиях группы развертывания. Пример: 1 |
Общие артефакты
Для каждого артефакта, на который ссылается выпуск, можно использовать следующие переменные артефакта. Не все переменные имеют смысл для каждого типа артефакта. В таблице ниже перечислены переменные артефакта по умолчанию и приведены примеры значений, которые они имеют в зависимости от типа артефакта. Если пример пуст, это означает, что переменная не заполняется для этого типа артефакта.
Замените {alias} заполнитель значением, указанным для псевдонима артефакта или значением по умолчанию, созданным для конвейера выпуска.
| Имя переменной | Description |
|---|---|
| Release.Artifacts. {alias}. DefinitionId | Идентификатор конвейера сборки или репозитория. Пример Azure Pipelines: 1Пример GitHub: fabrikam/asp |
| Release.Artifacts. {alias}. DefinitionName | Имя конвейера сборки или репозитория. Пример Azure Pipelines: fabrikam-ciПример TFVC: $/fabrikamПример Git: fabrikamПример GitHub: fabrikam/asp (main) |
| Release.Artifacts. {alias}. BuildNumber | Номер сборки или идентификатор фиксации. Пример Azure Pipelines: 20170112.1Пример Jenkins/TeamCity: 20170112.1Пример TFVC: Changeset 3Пример Git: 38629c964Пример GitHub: 38629c964 |
| Release.Artifacts. {alias}. BuildId | Идентификатор сборки. Пример Azure Pipelines: 130Пример Jenkins/TeamCity: 130Пример GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11 |
| Release.Artifacts. {alias}. BuildURI | URL-адрес сборки. Пример Azure Pipelines: vstfs://build-release/Build/130Пример GitHub: https://github.com/fabrikam/asp |
| Release.Artifacts. {alias}. SourceBranch | Полный путь и имя ветви, из которой был построен источник. Пример Azure Pipelines: refs/heads/main |
| Release.Artifacts. {alias}. SourceBranchName | Имя только ветви, из которой был построен источник. Пример Azure Pipelines: main |
| Release.Artifacts. {alias}. SourceVersion | Фиксация, созданная. Пример Azure Pipelines: bc0044458ba1d9298cdc649cb5dcf013180706f7 |
| Release.Artifacts. {alias}. Репозиторий.Provider | Тип репозитория, из которого был построен источник. Пример Azure Pipelines: Git |
| Release.Artifacts. {alias}. ЗапрошенныйForID | Идентификатор учетной записи, которая активировала сборку. Пример Azure Pipelines: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.Artifacts. {alias}. RequestedFor | Имя учетной записи, запрашивающей сборку. Пример Azure Pipelines: Mateo Escobedo |
| Release.Artifacts. {alias}. Тип | Тип источника артефакта, например Build. Пример Azure Pipelines: BuildПример Jenkins: JenkinsПример TeamCity: TeamCityПример TFVC: TFVCПример Git: GitПример GitHub: GitHub |
| Release.Artifacts. {alias}. PullRequest.TargetBranch | Полный путь и имя ветви, которая является целью запроса на вытягивание. Эта переменная инициализируется только в том случае, если выпуск активируется потоком запроса на вытягивание. Пример Azure Pipelines: refs/heads/main |
| Release.Artifacts. {alias}. PullRequest.TargetBranchName | Имя только ветви, которая является целью запроса на вытягивание. Эта переменная инициализируется только в том случае, если выпуск активируется потоком запроса на вытягивание. Пример Azure Pipelines: main |
См. также псевдоним источника артефакта
Основной артефакт
Вы назначаете один из артефактов в качестве основного артефакта в конвейере выпуска. Для указанного первичного артефакта Azure Pipelines заполняет следующие переменные.
| Имя переменной | Эквивалентно |
|---|---|
| Build.DefinitionId | Release.Artifacts. {Основной псевдоним артефакта}. DefinitionId |
| Build.DefinitionName | Release.Artifacts. {Основной псевдоним артефакта}. DefinitionName |
| Build.BuildNumber | Release.Artifacts. {Основной псевдоним артефакта}. BuildNumber |
| Build.BuildId | Release.Artifacts. {Основной псевдоним артефакта}. BuildId |
| Build.BuildURI | Release.Artifacts. {Основной псевдоним артефакта}. BuildURI |
| Build.SourceBranch | Release.Artifacts. {Основной псевдоним артефакта}. SourceBranch |
| Build.SourceBranchName | Release.Artifacts. {Основной псевдоним артефакта}. SourceBranchName |
| Build.SourceVersion | Release.Artifacts. {Основной псевдоним артефакта}. SourceVersion |
| Build.Repository.Provider | Release.Artifacts. {Основной псевдоним артефакта}. Репозиторий.Provider |
| Build.RequestedForID | Release.Artifacts. {Основной псевдоним артефакта}. ЗапрошенныйForID |
| Build.RequestedFor | Release.Artifacts. {Основной псевдоним артефакта}. RequestedFor |
| Build.Type | Release.Artifacts. {Основной псевдоним артефакта}. Тип |
| Build.PullRequest.TargetBranch | Release.Artifacts. {Основной псевдоним артефакта}. PullRequest.TargetBranch |
| Build.PullRequest.TargetBranchName | Release.Artifacts. {Основной псевдоним артефакта}. PullRequest.TargetBranchName |
Использование переменных по умолчанию
Переменные по умолчанию можно использовать двумя способами — в качестве параметров для задач в конвейере выпуска или в скриптах.
Вы можете напрямую использовать переменную по умолчанию в качестве входных данных для задачи.
Например, чтобы передать Release.Artifacts.{Artifact alias}.DefinitionName источник артефакта, псевдоним которого ASPNET4.CI задаче, будет использоваться$(Release.Artifacts.ASPNET4.CI.DefinitionName).
Чтобы использовать переменную по умолчанию в скрипте, необходимо сначала заменить . имена _переменных по умолчанию на .
Например, чтобы распечатать значение переменной Release.Artifacts.{Artifact alias}.DefinitionName артефакта для источника артефактов, псевдоним которого ASPNET4.CI в скрипте PowerShell, будет использоваться$env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME.
Обратите внимание, что исходное имя псевдонима источника артефакта ASPNET4.CIзаменяется ASPNET4_CI.
Просмотр текущих значений всех переменных
Откройте представление конвейеров сводки для выпуска и выберите нужный этап. В списке шагов выберите "Инициализация задания".
Откроется журнал для этого шага. Прокрутите вниз, чтобы просмотреть значения, используемые агентом для этого задания.
Запуск выпуска в режиме отладки
Отображение дополнительных сведений в виде выпуска выполняется и в файлах журнала путем выполнения всего выпуска или только задач на отдельном этапе выпуска в режиме отладки. Это поможет устранить проблемы и сбои.
Чтобы инициировать режим отладки для всего выпуска, добавьте переменную с именем
System.Debugсо значениемtrueна вкладку "Переменные" конвейера выпуска.Чтобы инициировать режим отладки для одного этапа, откройте диалоговое окно "Настройка этапа" в контекстном меню этапа и добавьте переменную с именем
System.Debugсо значениемtrueна вкладку "Переменные".Кроме того, создайте группу переменных, содержащую переменную с именем
System.Debugзначенияtrue, и свяжите эту группу переменных с конвейером выпуска.
Совет
Если возникла ошибка, связанная с подключением службы Azure RM, см. статью "Практическое руководство. Устранение неполадок с подключениями к службе Azure Resource Manager".
Пользовательские переменные
Пользовательские переменные можно определить в различных область.
Совместное использование значений во всех определениях в проекте с помощью групп переменных. Выберите группу переменных, если необходимо использовать одни и те же значения во всех определениях, этапах и задачах в проекте, и вы хотите изменить значения в одном месте. Вы определяете группы переменных и управляете ими на вкладке "Библиотека ".
Совместное использование значений на всех этапах с помощью переменных конвейера выпуска. Выберите переменную конвейера выпуска, если необходимо использовать одно и то же значение во всех этапах и задачах в конвейере выпуска, и вы хотите иметь возможность изменить значение в одном месте. Эти переменные определяются и управляются на вкладке "Переменные" в конвейере выпуска. На странице "Переменные конвейера" откройте раскрывающийся список "Область" и выберите "Освободить". По умолчанию при добавлении переменной устанавливается значение Release область.
Совместное использование значений для всех задач на одном этапе с помощью переменных этапа. Используйте переменную уровня этапа для значений, которые зависят от этапа до этапа (и одинаковы для всех задач на этапе). Эти переменные определяются и управляются на вкладке "Переменные " конвейера выпуска. На странице "Переменные конвейера" откройте раскрывающийся список "Область" и выберите необходимый этап. При добавлении переменной задайте область соответствующей среды.
Использование пользовательских переменных в проекте, конвейере выпуска и стадии область поможет вам:
Избегайте дублирования значений, что упрощает обновление всех вхождений как одной операции.
Храните конфиденциальные значения таким образом, чтобы они не видели или изменялись пользователями конвейеров выпуска. Присвойте свойству конфигурации безопасную (секретную) переменную, выбрав
значок (блокировка) рядом с переменной.Внимание
Значения скрытых (секретных) переменных безопасно хранятся на сервере и не могут просматриваться пользователями после сохранения. Во время развертывания служба выпуска Azure Pipelines расшифровывает эти значения при ссылке на задачи и передает их агенту через безопасный канал HTTPS.
Примечание.
Создание пользовательских переменных может перезаписать стандартные переменные. Например, переменная среды Пути PowerShell. Если вы создаете пользовательскую Path переменную в агенте Windows, она перезаписывает $env:Path переменную, и PowerShell не сможет выполняться.
Использование пользовательских переменных
Чтобы использовать пользовательские переменные в задачах сборки и выпуска, просто заключите имя переменной в скобки и предшествуйте ему символом $ . Например, если у вас есть переменная с именем adminUserName, можно вставить текущее значение этой переменной в параметр задачи как $(adminUserName).
Примечание.
Переменные в разных группах, связанных с конвейером в одном область (например, задание или этап), будут сталкиваться, и результат может быть непредсказуемым. Убедитесь, что для переменных во всех группах переменных используются разные имена.
Определение и изменение переменных в скрипте
Чтобы определить или изменить переменную из скрипта, используйте task.setvariable команду ведения журнала.
Обратите внимание, что обновленное значение переменной область выполняемого задания и не выполняется между заданиями или этапами.
Имена переменных преобразуются в верхний регистр, а символы "." и " заменяются "_".
Например, Agent.WorkFolder преобразуется в AGENT_WORKFOLDER.
В Windows вы обращаетесь к этому как %AGENT_WORKFOLDER% или $env:AGENT_WORKFOLDER.
В Linux и macOS используется $AGENT_WORKFOLDER.
Совет
Скрипт можно запустить на следующей платформе:
- Агент Windows с помощью задачи пакетного скрипта или задачи скрипта PowerShell.
- агент macOS или Linux с помощью задачи скрипта Оболочки.
Скрипт пакетной службы
sauce Задание и secret.Sauce переменные
@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic
Чтение переменных
Аргументы
"$(sauce)" "$(secret.Sauce)"
Скрипт
@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)
Выходные данные консоли из чтения переменных:
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)
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по