Бөлісу құралы:


Использование переменных в классических конвейерах выпуска

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: 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
Дженкинс: 20170112.1
TFVC: Changeset 3
Git: 38629c964
GitHub: 38629c964
Release.Artifacts. {alias}. BuildId Идентификатор сборки. Примеры:

Azure Pipelines: 130
Дженкинс: 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.Examples

Azure Pipelines: Build
Дженкинс: Jenkins
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 в качестве аргумента задачу 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.

Снимок экрана: использование переменной по умолчанию в встроенном скрипте PowerShell.

Пользовательские переменные

Пользовательские переменные можно определить в различных областях.

  • Группы переменных: используйте группы переменных для совместного использования значений во всех определениях проекта. Это полезно, если вы хотите использовать одни и те же значения для определений, этапов и задач в проекте и управления ими из одного расположения. Определение групп переменных и управление ими в библиотеке конвейеров>.

  • Переменные конвейера выпуска: используйте переменные конвейера выпуска для совместного использования значений на всех этапах конвейера выпуска. Это идеально подходит для сценариев, в которых требуется согласованное значение между этапами и задачами, с возможностью его обновления из одного расположения. Определите эти переменные и управляйте ими на вкладке "Переменные " конвейера выпуска. На странице "Переменные конвейера" задайте раскрывающийся список "Область " для выпуска при добавлении переменной.

  • Переменные этапа: используйте переменные этапа для совместного использования значений в определенном этапе конвейера выпуска. Это полезно для значений, которые отличаются от этапа до этапа, но согласованы во всех задачах на этапе. Определите эти переменные и управляйте ими на вкладке "Переменные " конвейера выпуска. На странице "Переменные конвейера" в раскрывающемся списке "Область" задайте соответствующую среду при добавлении переменной.

Использование пользовательских переменных на уровне проекта, конвейера выпуска и этапов помогает:

  • Избегайте дедупликации значений, что упрощает обновление всех вхождений с помощью одного изменения.

  • Защита конфиденциальных значений путем предотвращения их просмотра или изменения пользователями. Чтобы пометить переменную как безопасную (секретную), щелкните висячий замок значок рядом с переменной.

    Внимание

    Значения скрытых переменных (секрет) безопасно хранятся на сервере и не могут просматриваться пользователями после их сохранения. Во время развертывания 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.

Совет

Скрипт можно запустить в:

Скрипт пакетной службы

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)

Просмотр текущих значений всех переменных

  1. Выберите "Выпуски конвейеров>" и выберите конвейер выпуска.

  2. Откройте представление сводки для выпуска и выберите нужный этап. В списке шагов выберите "Инициализация задания".

    Снимок экрана: шаг инициализации задания.

  3. Откроется журнал для этого шага. Прокрутите вниз, чтобы просмотреть значения, используемые агентом для этого задания.

    Снимок экрана: переменные, используемые агентом.

Запуск выпуска в режиме отладки

Запуск выпуска в режиме отладки позволяет диагностировать и устранять проблемы или сбои, отображая дополнительные сведения во время выполнения выпуска. Вы можете включить режим отладки для всего выпуска или только для задач на определенном этапе выпуска.

  • Чтобы включить режим отладки для всего выпуска, добавьте переменную с именем System.Debug со значением true на вкладку "Переменные" конвейера выпуска.

  • Чтобы включить режим отладки для определенного этапа, откройте диалоговое окно "Настройка этапа " в контекстном меню этапа и добавьте переменную с именем System.Debug со значением true на вкладку "Переменные ".

  • Кроме того, создайте группу переменных, содержащую переменную с именем System.Debug значения true, и свяжите эту группу переменных с конвейером выпуска.

Совет

Если возникла ошибка, связанная с подключениями к службе Azure ARM, см. статью Устранение неполадок с подключениями к службе Azure Resource Manager.