Partilhar via

CLI do Azure DevOps no Azure Pipeline YAML

Serviços de DevOps do Azure

Se quiser usar a CLI do Azure DevOps com um pipeline YAML, você pode usar a extensão Azure DevOps ou usar a tarefa AzureCLI. Os agentes Windows e Linux hospedados pela Microsoft são pré-configurados com a CLI do Azure e a extensão da CLI do Azure DevOps. A extensão da CLI do Azure DevOps executa az devops comandos.

Pode autenticar-se com uma PAT ou pode utilizar a tarefa AzureCLI@2 com uma ligação de serviço. Usar uma conexão de serviço é a opção mais segura porque você não precisará gerenciar credenciais manualmente.

Autenticar com o Azure DevOps

Alguns comandos da CLI do Azure DevOps, como az devops configure e az devops --help, não exigem nenhuma autenticação. Eles não se conectam ao Azure DevOps. A maioria dos comandos interage com o Azure DevOps e requer autenticação.

Você pode autenticar usando o token de segurança System.AccessToken usado pelo pipeline em execução, atribuindo-o a uma variável de ambiente chamada AZURE_DEVOPS_EXT_PAT, conforme mostrado no exemplo a seguir.

Usar System.AccessToken depende de ter um PAT. Como uma alternativa mais segura, você pode usar a tarefa AzureCLI@2 para preencher uma conexão de serviço.

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

Se você tiver várias etapas que exigem autenticação, adicione a AZURE_DEVOPS_EXT_PAT variável de ambiente a cada etapa.

Para obter mais informações sobre o escopo do token de segurança usado pelo pipeline em execução, consulte Acessar repositórios, artefatos e outros recursos.

Para obter mais informações sobre autenticação usando um token de acesso pessoal (PAT), consulte Entrar com um token de acesso pessoal.

Entre na CLI do Azure DevOps com agentes hospedados no Windows e Linux

Os agentes Windows e Linux hospedados pela Microsoft são pré-configurados com a CLI do Azure e a extensão da CLI do Azure DevOps.

O exemplo a seguir mostra como entrar no Azure DevOps e executar alguns comandos. Este exemplo usa a imagem do agente hospedado pela ubuntu-latest Microsoft. Você pode substituí-lo por qualquer uma das outras imagens hospedadas no Windows ou Linux.

Este exemplo é autenticado com a CLI do Azure DevOps. Ele usa o token de segurança System.AccessToken usado pelo pipeline em execução.

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)

Instalar a extensão CLI do Azure DevOps com agentes hospedados no macOS

Os agentes hospedados pela Microsoft do macOS têm a CLI do Azure instalada, mas não a extensão da CLI do Azure DevOps. Para instalar a extensão da CLI do Azure DevOps, execute o seguinte comando em seu pipeline antes de fazer qualquer chamada à CLI do Azure DevOps.

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

Atualizar a versão da CLI do Azure do agente hospedado

Os agentes hospedados pela Microsoft normalmente implantam atualizações semanais no software nos ambientes virtuais. Para algumas ferramentas, a versão mais recente no momento da implantação é usada. Em outros casos, a ferramenta está vinculada a versões específicas.

  • Para verificar o software incluído e suas versões para agentes hospedados pela Microsoft, incluindo a versão instalada da CLI do Azure e a extensão da CLI do Azure DevOps, siga os links Software incluído na tabela Software .
  • Para verificar a versão atual da CLI do Azure, consulte Como instalar a CLI do Azure.

Você pode atualizar a CLI do Azure em suas imagens hospedadas executando os seguintes comandos em seu pipeline.

# 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'

Instalar condicionalmente a extensão da CLI do Azure DevOps

Se o pipeline for executado em várias imagens de máquina virtual hospedadas pela Microsoft, algumas das quais não têm a extensão CLI do Azure DevOps instalada, você poderá instalar condicionalmente.

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"
    mac13:
      imageName: "macos-13"
    windows2025:
      imageName: "windows-2025"
    windows2022:
      imageName: "windows-2022"
  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'

CLI do Azure DevOps com agentes auto-hospedados

Você pode usar os seguintes métodos para instalar ou atualizar a CLI do Azure DevOps em seu agente auto-hospedado.

Instalar manualmente a CLI do Azure e a extensão da CLI do Azure DevOps

Instalar a CLI do Azure e a extensão da CLI do Azure DevOps em seu agente auto-hospedado quando você provisiona a imagem da máquina virtual para o agente é mais rápido do que instalá-los cada vez que o pipeline é executado.

Para instalar a CLI do Azure em sua imagem de agente auto-hospedada, consulte Instalar a CLI do Azure. Existem instruções separadas para Windows, Linux e macOS.

Depois de instalar a CLI do Azure, instale a extensão da CLI do Azure DevOps.

Instalar a CLI do Azure e a extensão da CLI do Azure DevOps em seu pipeline

O exemplo a seguir de configuração da CLI do Azure e da extensão da CLI do Azure DevOps em um agente auto-hospedado usando um pipeline tem os seguintes pré-requisitos.

# 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'

Instale a extensão DevOps da CLI do Azure:

  • A CLI do Azure versão 2.10.1 ou superior está instalada.
  • Há uma versão do bash instalado no agente e no caminho. Uma instalação bash é necessária para usar a tarefa 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
# ...

O exemplo a seguir instala a CLI do Azure seguida pela extensão da CLI do Azure DevOps.

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
# ...

Atribuir os resultados de uma chamada da CLI do Azure DevOps a uma variável

Para armazenar os resultados de uma chamada da CLI do Azure DevOps para uma variável de pipeline, use a task.setvariable sintaxe descrita em Definir variáveis em scripts. O exemplo a seguir obtém a ID de um grupo de variáveis chamado Fabrikam-2023 e usa esse valor em uma etapa subsequente.

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'

Autenticar com uma conexão de serviço

Quando você usa uma conexão de serviço, a conexão de serviço fornece as credenciais necessárias para os comandos da CLI do Azure e da CLI do Azure DevOps na tarefa AzureCLI@2 sem exigir gerenciamento manual de credenciais no pipeline.

Note

Ao usar uma conexão de serviço para autenticação com AzureCLI@2, você precisa adicionar manualmente o principal de serviço à sua organização do Azure DevOps.

Este exemplo de código define um novo parâmetro, serviceConnection, com o nome de uma conexão de serviço existente. Esse parâmetro é referenciado na tarefa AzureCLI@2. A tarefa lista todos os projetos (az devops project list) e pools (az pipelines pool list).

trigger:
  - main

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

steps:
  - task: AzureCLI@2
    condition: succeededOrFailed()
    displayName: 'Azure CLI -> DevOps CLI'
    inputs:
      azureSubscription: '${{ parameters.serviceConnection }}'
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        Write-Host "Using logged-in Azure CLI session..."
        Write-Host "$($PSStyle.Formatting.FormatAccent)az devops configure$($PSStyle.Reset)"
        az devops configure --defaults organization=$(System.CollectionUri) project=$(System.TeamProject)
        az devops configure -l

        Write-Host "`nUse Azure DevOps CLI (az devops) to list projects in the organization '$(System.CollectionUri)'..."
        Write-Host "$($PSStyle.Formatting.FormatAccent)az devops project list$($PSStyle.Reset)"
        az devops project list --query "value[].{Name:name, Id:id}" `
                               -o table

        Write-Host "`nUse Azure DevOps CLI (az pipelines) to list pools in the organization '$(System.CollectionUri)'..."
        Write-Host "$($PSStyle.Formatting.FormatAccent)az pipelines pool list$($PSStyle.Reset)"
        az pipelines pool list --query "[].{Id:id, Name:name}" `
                               -o table
      failOnStandardError: true

Atribuir os resultados de uma chamada da CLI do Azure DevOps a uma variável

Para armazenar os resultados de uma chamada da CLI do Azure DevOps para uma variável de pipeline, use a task.setvariable sintaxe descrita em Definir variáveis em scripts. O exemplo a seguir obtém a ID de um grupo de variáveis chamado kubernetes e usa esse valor em uma etapa subsequente.

trigger:
  - main

variables:
- name: variableGroupId

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

steps:
  - task: AzureCLI@2
    condition: succeededOrFailed()
    displayName: 'Azure CLI -> DevOps CLI'
    inputs:
      azureSubscription: '${{ parameters.serviceConnection }}'
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        Write-Host "Using logged-in Azure CLI session..."
        Write-Host "$($PSStyle.Formatting.FormatAccent)az devops configure$($PSStyle.Reset)"
        az devops configure --defaults organization=$(System.CollectionUri) project=$(System.TeamProject)
        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@2
    condition: succeededOrFailed()
    displayName: 'Azure CLI -> DevOps CLI'
    inputs:
      azureSubscription: '${{ parameters.serviceConnection }}'
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        Write-Host "Using logged-in Azure CLI session..."
        az pipelines variable-group variable list --group-id '$(variableGroupId)'

Para obter mais exemplos de trabalho com variáveis, incluindo o trabalho com variáveis entre trabalhos e estágios, consulte Definir variáveis. Para obter exemplos da sintaxe de consulta usada no exemplo anterior, consulte Como consultar a saída do comando CLI do Azure usando uma consulta JMESPath.

Conteúdo relacionado