Использование переменных в классических конвейерах выпуска
Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019
Использование переменных в классических конвейерах выпуска — это удобный способ обмена данными и транспорта на протяжении всего конвейера. Каждая переменная хранится в виде строки, а ее значение может изменяться между выполнением конвейера.
В отличие от параметров среды выполнения, которые доступны только во время анализа шаблона, переменные в классических конвейерах выпуска доступны во всем процессе развертывания.
При настройке задач для развертывания приложения на каждом этапе классического конвейера выпуска переменные помогут вам:
Упрощение настройки. Определите универсальный конвейер развертывания один раз и легко адаптируйте его для различных этапов. Например, используйте переменную для представления строка подключения веб-развертывания, изменив его значение по мере необходимости для каждого этапа. Они называются пользовательскими переменными.
Используйте контекстную информацию: доступ к сведениям о контексте выпуска, таких как этап, артефакт или агент , выполняющий развертывание. Например, для сценариев может потребоваться расположение сборки для скачивания или рабочий каталог агента для создания временных файлов. Они называются переменными по умолчанию.
Примечание.
Дополнительные сведения о конвейерах 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: 1GitHub: fabrikam/asp |
| Release.Artifacts. {alias}. DefinitionName | Имя конвейера сборки или репозитория. Примеры: Azure Pipelines: fabrikam-ciTFVC: $/fabrikamGit: fabrikamGitHub: fabrikam/asp (main) |
| Release.Artifacts. {alias}. BuildNumber | Номер сборки или идентификатор фиксации. Примеры: Azure Pipelines: 20170112.1Дженкинс: 20170112.1TFVC: Changeset 3Git: 38629c964GitHub: 38629c964 |
| Release.Artifacts. {alias}. BuildId | Идентификатор сборки. Примеры: Azure Pipelines: 130Дженкинс: 130GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11 |
| Release.Artifacts. {alias}. BuildURI | URL-адрес сборки. Примеры: Azure Pipelines: vstfs://build-release/Build/130GitHub: 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.Examples Azure Pipelines: BuildДженкинс: JenkinsTFVC: TFVCGit: GitGitHub: 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 в качестве аргумента задачу PowerShell для артефакта с 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.
Пользовательские переменные
Пользовательские переменные можно определить в различных областях.
Группы переменных: используйте группы переменных для совместного использования значений во всех определениях проекта. Это полезно, если вы хотите использовать одни и те же значения для определений, этапов и задач в проекте и управления ими из одного расположения. Определение групп переменных и управление ими в библиотеке конвейеров>.
Переменные конвейера выпуска: используйте переменные конвейера выпуска для совместного использования значений на всех этапах конвейера выпуска. Это идеально подходит для сценариев, в которых требуется согласованное значение между этапами и задачами, с возможностью его обновления из одного расположения. Определите эти переменные и управляйте ими на вкладке "Переменные " конвейера выпуска. На странице "Переменные конвейера" задайте раскрывающийся список "Область " для выпуска при добавлении переменной.
Переменные этапа: используйте переменные этапа для совместного использования значений в определенном этапе конвейера выпуска. Это полезно для значений, которые отличаются от этапа до этапа, но согласованы во всех задачах на этапе. Определите эти переменные и управляйте ими на вкладке "Переменные " конвейера выпуска. На странице "Переменные конвейера" в раскрывающемся списке "Область" задайте соответствующую среду при добавлении переменной.
Использование пользовательских переменных на уровне проекта, конвейера выпуска и этапов помогает:
Избегайте дедупликации значений, что упрощает обновление всех вхождений с помощью одного изменения.
Защита конфиденциальных значений путем предотвращения их просмотра или изменения пользователями. Чтобы пометить переменную как безопасную (секретную), щелкните
значок рядом с переменной.Внимание
Значения скрытых переменных (секрет) безопасно хранятся на сервере и не могут просматриваться пользователями после их сохранения. Во время развертывания Azure Pipelines расшифровывает эти значения при ссылке на задачи и передает их агенту через безопасный канал HTTPS.
Примечание.
Создание пользовательских переменных может перезаписать стандартные переменные. Например, если вы определяете пользовательскую переменную пути в агенте 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)
Просмотр текущих значений всех переменных
Выберите "Выпуски конвейеров>" и выберите конвейер выпуска.
Откройте представление сводки для выпуска и выберите нужный этап. В списке шагов выберите "Инициализация задания".
Откроется журнал для этого шага. Прокрутите вниз, чтобы просмотреть значения, используемые агентом для этого задания.
Запуск выпуска в режиме отладки
Запуск выпуска в режиме отладки позволяет диагностировать и устранять проблемы или сбои, отображая дополнительные сведения во время выполнения выпуска. Вы можете включить режим отладки для всего выпуска или только для задач на определенном этапе выпуска.
Чтобы включить режим отладки для всего выпуска, добавьте переменную с именем
System.Debugсо значениемtrueна вкладку "Переменные" конвейера выпуска.Чтобы включить режим отладки для определенного этапа, откройте диалоговое окно "Настройка этапа " в контекстном меню этапа и добавьте переменную с именем
System.Debugсо значениемtrueна вкладку "Переменные ".Кроме того, создайте группу переменных, содержащую переменную с именем
System.Debugзначенияtrue, и свяжите эту группу переменных с конвейером выпуска.
Совет
Если возникла ошибка, связанная с подключениями к службе Azure ARM, см. статью Устранение неполадок с подключениями к службе Azure Resource Manager.