Использование переменных в классических конвейерах выпуска
Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019
Использование переменных в классических потоках выпуска — это удобный способ обмена и транспортировки данных на протяжении всего процесса. Каждая переменная хранится в виде строки, а ее значение может изменяться между выполнением конвейера.
В отличие от параметров среды выполнения, которые доступны только во время анализа шаблона, переменные в классических конвейерах выпуска доступны во всем процессе развертывания.
При настройке задач для развертывания приложения на каждом этапе классического конвейера выпуска переменные помогут вам:
Упрощение настройки. Определите универсальный конвейер развертывания один раз и легко адаптируйте его для различных этапов. Например, используйте переменную для представления строки подключения веб-развертывания, изменяя ее значение по мере необходимости для каждого этапа. Они называются пользовательскими переменными.
Используйте контекстную информацию: получите доступ к сведениям о контексте выпуска, таким как этап, артефакт или агент, выполняющий развертывание. Например, для сценариев может потребоваться расположение сборки для скачивания или рабочий каталог агента для создания временных файлов. Они называются переменными по умолчанию.
Примечание.
Дополнительные сведения о конвейерах YAML см. в разделах определяемые пользователем переменные и предопределенные переменные.
Переменные по умолчанию
Переменные по умолчанию предоставляют важные сведения о контексте выполнения для выполняемых задач и скриптов. Эти переменные позволяют получить доступ к сведениям о системе, выпуске, стадии или агенте, в котором они работают.
За исключением System.Debug переменные по умолчанию доступны только для чтения, а их значения автоматически задаются системой.
Некоторые из наиболее важных переменных описаны в следующих таблицах. Чтобы просмотреть полный список, просмотрите текущие значения всех переменных.
Системные переменные
| Имя переменной | Описание |
|---|---|
| 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 |
Переменные выпуска
| Имя переменной | Описание |
|---|---|
| Релиз.НомерПопытки | Количество развертываний этого выпуска на этом этапе. Пример: 1 |
| Release.DefinitionEnvironmentId | Идентификатор этапа в соответствующем конвейере выпуска. Пример: 1 |
| Release.DefinitionId | Идентификатор конвейера выпуска, к которому принадлежит текущий выпуск. Пример: 1 |
| Release.DefinitionName | Имя конвейера выпуска, к которому относится текущий выпуск. Пример: fabrikam-cd |
| Выпуск.Развертывание.ЗапрошеноДля | Отображаемое имя удостоверения, которое активировало (запущено) развертывание в настоящее время. Пример: Mateo Escobedo |
| Запрос на развертывание для электронной почты | Адрес электронной почты удостоверения, запустившего развертывание, выполняемого в данный момент. Пример: mateo@fabrikam.com |
| Release.Deployment.RequestedForId | Идентификатор удостоверения, запустившего развертывание, в настоящее время в процессе. Пример: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.DeploymentID | Идентификатор развертывания. Уникально для каждой работы. Пример: 254 |
| Release.DeployPhaseID | Идентификатор этапа, в котором выполняется развертывание. Пример: 127 |
| Release.EnvironmentId | Идентификатор экземпляра этапа в выпуске, для которого в настоящее время выполняется развертывание. Пример: 276 |
| Выпуск.Название_среды | Название этапа, на котором в настоящее время выполняется развертывание. Пример: Dev |
| Release.EnvironmentUri | URI экземпляра этапа в выпуске, в котором выполняется развертывание. Пример: vstfs://ReleaseManagement/Environment/276 |
| Release.Environments.{stage-name}.status | Состояние развертывания этапа. Пример: InProgress |
| Release.PrimaryArtifactSourceAlias | Псевдоним первичного источника артефактов. Пример: fabrikam\_web |
| Причина выпуска | Причина развертывания. Поддерживаются значения:ContinuousIntegration — выпуск, запущенный в процессе непрерывного развертывания после завершения сборки.Manual — выпуск был запущен вручную.None — причина развертывания не указана.Schedule — выпуск, запущенный по расписанию. |
| Описание релиза | Текстовое описание, предоставленное во время выпуска. Пример: 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 |
| Запрос на выпуск | Отображаемое имя идентификатора, вызвавшего выпуск. Пример: Mateo Escobedo |
| Release.RequestedForEmail | Адрес электронной почты личности, вызвавшей выпуск. Пример: mateo@fabrikam.com |
| Release.RequestedForId | Идентификатор удостоверения, активировавшего релиз. Пример: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.SkipArtifactsDownload | Логическое значение, указывающее, следует ли пропустить загрузку артефактов агенту. Пример: FALSE |
| Release.TriggeringArtifact.Alias | Псевдоним артефакта, который вызвал выпуск. Это пусто, если выпуск был запланирован или активирован вручную. Пример: fabrikam\_app |
Переменные этапа выпуска
| Имя переменной | Описание |
|---|---|
| Release.Environments.{название этапа}.Статус | Состояние развертывания этого выпуска на заданном этапе. Пример: NotStarted |
Переменные агента
| Имя переменной | Описание |
|---|---|
| Agent.Name | Имя агента, зарегистрированного в пуле агентов. Скорее всего, это отличается от имени компьютера. Пример: fabrikam-agent |
| Agent.MachineName | Имя компьютера, на котором настроен агент. Пример: fabrikam-agent |
| Агент.Версия | Версия программного обеспечения агента. Пример: 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} заполнитель значением, указанным для псевдонима источника артефакта или значением по умолчанию, созданным для конвейера выпуска.
| Имя переменной | Описание |
|---|---|
| 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}.Репозиторий.Поставщик | Тип репозитория, из которого был построен источник. Примеры: Azure Pipelines: Git |
| Release.Artifacts.{alias}.RequestedForID | Идентификатор учетной записи, которая активировала сборку. Примеры: 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 | Полный путь и имя ветки, на которую нацелен pull request. Эта переменная инициализируется только в том случае, если релиз запускается потоком pull request. Примеры: Azure Pipelines: refs/heads/main |
| Release.Artifacts. {alias}. PullRequest.TargetBranchName | Имя ветви, которая является целью пулл-реквеста. Эта переменная инициализируется только в том случае, если выпуск активируется процессом pull request. Примеры: 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.{Основной псевдоним артефакта}.ИсходнаяВерсия |
| Build.Repository.Provider | Release.Artifacts.{Основной псевдоним артефакта}.Репозиторий.Провайдер |
| Build.RequestedForID | Release.Artifacts.{Основной псевдоним артефакта}.ЗапрашивающийID |
| 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.
Примечание.
Создание пользовательских переменных может перезаписать стандартные переменные. Например, если вы определяете пользовательскую переменную 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)
Просмотр текущих значений всех переменных
Выберите Конвейеры>Выпуски, а затем выберите конвейер выпуска.
Откройте сводный отчет о выпуске и выберите интересующий вас этап. В списке шагов выберите "Инициализация задания".
Откроется журнал для этого шага. Прокрутите вниз, чтобы просмотреть значения, используемые агентом для этого задания.
Запуск релиза в режиме отладки
Запуск выпуска в режиме отладки позволяет диагностировать и устранять проблемы или сбои, отображая дополнительные сведения во время выполнения выпуска. Вы можете включить режим отладки для всего выпуска или только для задач на определенном этапе выпуска.
Чтобы включить режим отладки для всего выпуска, добавьте переменную с именем
System.Debugсо значениемtrueна вкладку "Переменные" конвейера выпуска.Чтобы включить режим отладки для определенного этапа, откройте диалоговое окно "Настройка этапа " в контекстном меню этапа и добавьте переменную с именем
System.Debugсо значениемtrueна вкладку "Переменные ".Кроме того, создайте группу переменных, содержащую переменную с именем
System.Debugзначенияtrue, и свяжите эту группу переменных с конвейером выпуска.
Совет
Если возникла ошибка, связанная с подключениями к службе Azure ARM, см. статью Устранение неполадок с подключениями к службе Azure Resource Manager.