Azure DevOps CLI в YAML-конвейере Azure

Azure DevOps Services

Note

Эта функция развертывается на этой и следующей неделе. Если вы еще не видите эту функцию в проекте служб Azure DevOps, вернитесь обратно через несколько дней.

Azure DevOps CLI позволяет управлять ресурсами Azure DevOps из командной строки. Выполните команды CLI в конвейере YAML с задачей AzureCLI@3 , чтобы автоматизировать общие задачи DevOps в рамках рабочего процесса CI/CD. Агенты Windows и Linux, размещенные Microsoft, уже включают Azure CLI и расширение Azure DevOps CLI.

Для проверки подлинности используйте подключение службы Azure DevOps, поддерживаемое федерацией удостоверений рабочей нагрузки Microsoft Entra. Мы рекомендуем этот подход, так как он устраняет управление учетными данными. Используйте личный маркер доступа (PAT), только если подключение к службе недоступно.

Проверка подлинности с помощью Azure DevOps

Некоторые команды cli Azure DevOps, такие как az devops configure и az devops --help, не требуют проверки подлинности. Они не подключаются к Azure DevOps. Большинство команд взаимодействуют с Azure DevOps и требуют проверки подлинности.

Вы можете пройти проверку подлинности с помощью маркера безопасности System.AccessToken , используемого запущенным конвейером, назначив его переменной среды с именем AZURE_DEVOPS_EXT_PAT, как показано в следующем примере.

Использование System.AccessToken зависит от наличия PAT. В качестве более безопасной альтернативы используйте подключение к службе. Инструкции по настройке см. в разделе "Управление подключениями к службе".

- bash: |
    az pipelines build list --organization '$(System.TeamFoundationCollectionUri)' --project '$(System.TeamProject)'
  displayName: 'Show build list'
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

При наличии нескольких шагов, требующих проверки подлинности, добавьте AZURE_DEVOPS_EXT_PAT переменную среды на каждый шаг.

Для получения дополнительной информации о применении маркера безопасности, используемого активным конвейером, см. статью Доступ к репозиториям, артефактам и другим ресурсам.

Дополнительные сведения о проверке подлинности с помощью личного маркера доступа (PAT) см. в разделе "Вход с помощью личного маркера доступа".

Войдите в CLI Azure DevOps, используя агентов, размещённых на платформах Windows и Linux.

Организуемые Microsoft агенты для Windows и Linux предварительно настроены с предустановленными Azure CLI и расширением Azure DevOps CLI.

В следующем примере показано, как войти в Azure DevOps и выполнить несколько команд. В этом примере используется образ агента ubuntu-latest Microsoft. Его можно заменить любым из других образов Windows или образов, размещенных на Linux.

В этом примере выполняется проверка подлинности с помощью интерфейса командной строки Azure DevOps. Он использует маркер безопасности System.AccessToken , используемый запущенным конвейером.

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- bash: az --version
  displayName: 'Show Azure CLI version'

- bash: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true
  displayName: 'Set default Azure DevOps organization and project'

- bash: |
    az pipelines build list
    git pr list
  displayName: 'Show build list and PRs'
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

Установка расширения интерфейса командной строки Azure DevOps на размещенных агентах macOS

Агенты, размещенные в macOS от Microsoft, имеют установленный Azure CLI, но не имеют расширение Azure DevOps CLI. Чтобы установить расширение CLI Azure DevOps, выполните следующую команду в конвейере перед вызовами Azure DevOps CLI.

# Install Azure DevOps extension
- bash: az extension add -n azure-devops
  displayName: 'Install Azure DevOps extension'

Обновление версии размещенного агента Azure CLI

Агенты, размещённые Microsoft, обычно развертывают еженедельные обновления для программного обеспечения в виртуальные среды. Для некоторых средств используется последняя версия во время развертывания. В других случаях инструмент привязан к определённым версиям.

  • Чтобы проверить включенное программное обеспечение и их версии для агентов, размещенных Microsoft, включая установленную версию Azure CLI и расширения CLI Azure DevOps, следуйте ссылкам Included Software в таблице Software.
  • Чтобы проверить текущую версию Azure CLI, см. статью Как установить Azure CLI.

Вы можете обновить Azure CLI на размещенных образах, выполнив следующие команды в вашем конвейере.

# Specify python version
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update to latest Azure CLI version
- bash: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

При необходимости установите расширение интерфейса командной строки Azure DevOps

Если ваш конвейер выполняется на нескольких размещённых Microsoft образах виртуальных машин, на некоторых из которых не установлено расширение Azure DevOps CLI, можно установить условно.

trigger:
- main

# Run on multiple Microsoft-hosted agent images
strategy:
  matrix:
    linux24:
      imageName: "ubuntu-24.04"
    linux22:
      imageName: "ubuntu-22.04"
    mac15:
      imageName: "macos-15"
    mac14:
      imageName: "macos-14"
    windows2025:
      imageName: "windows-2025"
  maxParallel: 3

pool:
  vmImage: $(imageName)

steps:
- bash: az --version
  displayName: 'Show Azure CLI version'

# Install Azure DevOps CLI extension only on macOS images
- bash: az extension add -n azure-devops
  condition: contains(variables.imageName, 'mac')
  displayName: 'Install Azure DevOps extension'

# Azure DevOps CLI extension call that does not require login or credentials
# since it configures the local environment
- bash: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true
  displayName: 'Set default Azure DevOps organization and project'

# Call that does require credentials, use the System.AccessToken PAT
# and assign to AZURE_DEVOPS_EXT_PAT which is known to Azure DevOps CLI extension
- bash: |
    az pipelines build list
    git pr list
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
  displayName: 'Show build list and PRs'

Azure DevOps CLI с локальными агентами

Для установки или обновления Azure DevOps CLI в локальном агенте можно использовать следующие методы.

Установите Azure CLI и расширение Azure DevOps CLI вручную

Установка расширений Azure CLI и Azure DevOps CLI на вашем локальном агенте во время подготовки образа виртуальной машины для агента быстрее, чем их установка при каждом запуске пайплайна.

Чтобы установить Azure CLI на образе локального агента, см. раздел Install Azure CLI. Существуют отдельные инструкции по Windows, Linux и macOS.

После установки Azure CLI установите расширение CLI Azure DevOps CLI.

Установите Azure CLI и расширение Azure DevOps CLI в ваш конвейер

В следующем примере настройки расширения Azure CLI и Azure DevOps CLI для локального агента с помощью конвейера имеются следующие предварительные требования.

# Specify python version if you have side-by-side versions
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update pip to latest
- bash: python -m pip install --upgrade pip
  displayName: 'Upgrade pip'

# Update to latest Azure CLI version, min version required for Azure DevOps is 2.10.1
- bash: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

Установите расширение Azure CLI DevOps:

  • установлен Azure CLI версии 2.10.1 или более поздней версии.
  • Существует версия bash, установленная на агенте и в системном пути. Для использования задачи bash требуется установить bash.
# Install Azure DevOps extension
- bash: az extension add -n azure-devops
  displayName: 'Install Azure DevOps extension'

# Now you can make calls into Azure DevOps CLI
# ...

В следующем примере сначала устанавливается Azure CLI, а затем расширение Azure DevOps CLI.

steps:
# Specify python version if you have side-by-side versions
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update pip to latest
- bash: python -m pip install --upgrade pip
  displayName: 'Upgrade pip'

# Update to latest Azure CLI version, min version required for Azure DevOps is 2.10.1
- bash: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

# Install Azure DevOps extension
- bash: az extension add -n azure-devops
  displayName: 'Install Azure DevOps extension'

# Now you can make calls into Azure DevOps CLI
# ...

Присвоение результатов вызова интерфейса командной строки Azure DevOps переменной

Чтобы сохранить результаты вызова интерфейса командной строки Azure DevOps в переменную конвейера, используйте синтаксис task.setvariable, описанный в Set переменных в скриптах. Следующий пример получает идентификатор группы переменных с именем Fabrikam-2023 и использует это значение в следующем шаге.

variables:
- name: variableGroupId

trigger: none

pool:
  vmImage: "ubuntu-latest"

steps:
- bash: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true
  displayName: 'Set default Azure DevOps organization and project'

- bash: echo "##vso[task.setvariable variable=variableGroupId]$(az pipelines variable-group list --group-name Fabrikam-2023 --query [].id -o tsv)"
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
  displayName: 'Get Fabrikam-2023 variable group id'

- bash: az pipelines variable-group variable list --group-id '$(variableGroupId)'
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
  displayName: 'List variables in Fabrikam-2023 variable group'

Аутентификация через служебное подключение

При использовании подключения службы это подключение предоставляет необходимые учетные данные для команд Azure CLI и Azure DevOps CLI в задаче AzureCLI@3 без необходимости вручную управлять учетными данными в конвейере.

Note

При использовании подключения службы для проверки подлинности с помощью AzureCLI@3 необходимо мануально добавить субъект-службу в организацию Azure DevOps.

Для получения рекомендаций по руководству и подключению к службе без использования PAT см. Управление подключениями к службе.

Этот пример кода определяет новый параметр serviceConnectionс именем существующего подключения к службе. Параметр упоминается в задаче AzureCLI@3. Скрипт использует подключение без секрета для вызова конечной точки REST, а затем перечисляет проекты и пулы.

trigger:
  - main

parameters:
- name: serviceConnection
  displayName: Azure DevOps Service Connection Name
  type: string
  default: my-service-connection

steps:
  - task: AzureCLI@3
    displayName: Secret-less
    inputs:
      connectionType: 'azureDevOps'
      azureDevOpsServiceConnection: '${{ parameters.serviceConnection }}'
      scriptType: 'pscore'
      scriptLocation: 'inlineScript'
      inlineScript: |
        az rest --method get `
                --url "https://status.dev.azure.com/_apis/status/health?api-version=7.1-preview.1" `
                --resource 499b84ac-1321-427f-aa17-267ca6975798 `
                --query "sort_by(services[?id=='Pipelines'].geographies | [], &name)" `
                -o table

        az devops configure -l

        az devops project list --query "value[].{Name:name, Id:id}" `
                              -o table

        az pipelines pool list --query "[].{Id:id, Name:name}" `
                              -o table
      failOnStandardError: true

Присвоение результатов вызова интерфейса командной строки Azure DevOps переменной

Чтобы сохранить результаты вызова интерфейса командной строки Azure DevOps в переменную конвейера, используйте синтаксис task.setvariable, описанный в Set переменных в скриптах. В следующем примере возвращается идентификатор группы переменных с именем Kubernetes, и это значение используется на следующем шаге.

trigger:
  - main

variables:
- name: variableGroupId

parameters:
- name: serviceConnection
  displayName: Azure DevOps Service Connection Name
  type: string
  default: my-service-connection

steps:
  - task: AzureCLI@3
    displayName: Set variable group ID
    inputs:
      connectionType: 'azureDevOps'
      azureDevOpsServiceConnection: '${{ parameters.serviceConnection }}'
      scriptType: 'pscore'
      scriptLocation: 'inlineScript'
      inlineScript: |
        az devops configure -l

        $id = az pipelines variable-group list --group-name kubernetes --query [].id -o tsv
        Write-Host "##vso[task.setvariable variable=variableGroupId]$id"

  - task: AzureCLI@3
    displayName: List variable group variables
    inputs:
      connectionType: 'azureDevOps'
      azureDevOpsServiceConnection: '${{ parameters.serviceConnection }}'
      scriptType: 'pscore'
      scriptLocation: 'inlineScript'
      inlineScript: |
        az pipelines variable-group variable list --group-id '$(variableGroupId)'

Дополнительные примеры работы с переменными, включая работу с переменными между заданиями и этапами, см. в разделе "Определение переменных". Примеры синтаксиса запроса, используемого в предыдущем примере, см. в статье How to query Azure CLI command output using a JMESPath query.

Связанный контент

  • Last updated on