Compartir a través de

CLI de Azure DevOps en YAML de Azure Pipeline

Azure DevOps Services

Si quiere usar la CLI de Azure DevOps con una canalización de YAML, puede usar la extensión de Azure DevOps o usar la tarea AzureCLI. Los agentes de Windows y Linux hospedados por Microsoft están preconfigurados con la CLI de Azure y la extensión de la CLI de Azure DevOps. La extensión de la CLI de Azure DevOps ejecuta az devops comandos.

Puede autenticarse con un PAT o puede usar la tarea AzureCLI@2 con una conexión de servicio. El uso de una conexión de servicio es la opción más segura porque no es necesario administrar manualmente las credenciales.

Autenticación con Azure DevOps

Algunos comandos de la CLI de Azure DevOps, como az devops configure y az devops --help, no requieren ninguna autenticación. No se conectan a Azure DevOps. La mayoría de los comandos interactúan con Azure DevOps y requieren autenticación.

Puede autenticarse mediante el token de seguridad System.AccessToken que usa la canalización de ejecución; para ello, asígnelo a una variable de entorno denominada AZURE_DEVOPS_EXT_PAT, como se muestra en el ejemplo siguiente.

El uso de System.AccessToken se basa en tener un PAT. Como alternativa más segura, puede usar la tarea AzureCLI@2 para rellenar una conexión de servicio.

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

Si tiene varios pasos que requieren autenticación, añada la variable de entorno AZURE_DEVOPS_EXT_PAT a cada paso.

Para obtener más información sobre el ámbito del token de seguridad que usa la canalización de ejecución, consulte Acceso a repositorios, artefactos y otros recursos.

Para obtener más información sobre la autenticación mediante un token de acceso personal (PAT), consulte Inicio de sesión con un token de acceso personal.

Inicio de sesión en la CLI de Azure DevOps con agentes hospedados en Windows y Linux

Los agentes de Windows y Linux hospedados por Microsoft están preconfigurados con la CLI de Azure y la extensión de la CLI de Azure DevOps.

En el ejemplo siguiente se muestra cómo iniciar sesión en Azure DevOps y ejecutar algunos comandos. En este ejemplo se usa la imagen del ubuntu-latest agente hospedado por Microsoft. Puede reemplazarlo por cualquiera de las demás imágenes hospedadas de Windows o Linux.

En este ejemplo se autentica con la CLI de Azure DevOps. Usa el token de seguridad System.AccessToken usado por la canalización en ejecución.

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)

Instalación de la extensión de la CLI de Azure DevOps con agentes hospedados en macOS

Los agentes hospedados por Microsoft para macOS tienen instalada la CLI de Azure, pero no la extensión de la CLI de Azure DevOps. Para instalar la extensión de la CLI de Azure DevOps, ejecute el siguiente comando en la canalización antes de realizar llamadas a la CLI de Azure DevOps.

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

Actualización de la versión de la CLI de Azure del agente hospedado

Normalmente, los agentes hospedados por Microsoft implementan actualizaciones semanales en el software en los entornos virtuales. Para algunas herramientas, se usa la versión más reciente en el momento de la implementación. En otros casos, la herramienta está anclada a versiones específicas.

  • Para comprobar el software incluido y sus versiones para agentes hospedados por Microsoft, incluida la versión instalada de la CLI de Azure y la extensión de la CLI de Azure DevOps, siga los vínculos Software incluido en la tabla Software.
  • Para comprobar la versión actual de la CLI de Azure, consulte Instalación de la CLI de Azure.

Puede actualizar la CLI de Azure en las imágenes hospedadas mediante la ejecución de los siguientes comandos en la canalización.

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

Instalación condicional de la extensión de la CLI de Azure DevOps

Si la canalización se ejecuta en varias imágenes de máquinas virtuales hospedadas por Microsoft, algunas de las cuales no tienen instalada la extensión de la CLI de Azure DevOps, puede instalarla de forma condicional.

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 de Azure DevOps con agentes autohospedados

Puede usar los métodos siguientes para instalar o actualizar la CLI de Azure DevOps en el agente autohospedado.

Instalación manual de la CLI de Azure y la extensión de la CLI de Azure DevOps

La instalación de la CLI de Azure y la extensión de la CLI de Azure DevOps en el agente autohospedado al aprovisionar la imagen de máquina virtual para el agente es más rápido que realizar la instalación cada vez que se ejecuta la canalización.

Para instalar la CLI de Azure en la imagen del agente autohospedado, consulte Instalación de la CLI de Azure. Hay instrucciones independientes para Windows, Linux y macOS.

Después de instalar la CLI de Azure, instale la extensión de la CLI de Azure DevOps.

Instalación de la CLI de Azure y la extensión de la CLI de Azure DevOps en la canalización

El ejemplo siguiente de configuración de la CLI de Azure y la extensión de la CLI de Azure DevOps en un agente autohospedado mediante una canalización tiene los siguientes requisitos previos.

# 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 la extensión de DevOps de la CLI de Azure:

  • Está instalada la versión 2.10.1 o posterior de la CLI de Azure.
  • Hay una versión de bash instalada en el agente y en la ruta de acceso. Se requiere una instalación de Bash para usar la tarea 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
# ...

En el ejemplo siguiente se instala la CLI de Azure seguida de la extensión de la CLI de 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
# ...

Asignación de los resultados de una llamada de la CLI de Azure DevOps a una variable

Para almacenar los resultados de una llamada de la CLI de Azure DevOps a una variable de canalización, use la sintaxis task.setvariable que se describe en Establecer variables en scripts. En el ejemplo siguiente se obtiene el identificador de un grupo de variables denominado Fabrikam-2023 y se usa este valor en un paso posterior.

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'

Autentícate con una conexión de servicio

Cuando se usa una conexión de servicio, la conexión de servicio proporciona las credenciales necesarias para los comandos de la CLI de Azure y la CLI de Azure DevOps en la tarea AzureCLI@2 sin necesidad de administración manual de credenciales en la canalización.

Note

Al usar una conexión de servicio para la autenticación con AzureCLI@2, debe agregar manualmente la entidad de servicio a la organización de Azure DevOps.

Este ejemplo de código define un nuevo parámetro, serviceConnection, con el nombre de una conexión de servicio existente. Se hace referencia a ese parámetro en la AzureCLI@2 tarea. La tarea enumera todos los proyectos (az devops project list) y grupos (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

Asignación de los resultados de una llamada de la CLI de Azure DevOps a una variable

Para almacenar los resultados de una llamada de la CLI de Azure DevOps a una variable de canalización, use la sintaxis task.setvariable que se describe en Establecer variables en scripts. En el ejemplo siguiente se obtiene el identificador de un grupo de variables denominado kubernetes y se usa este valor en un paso posterior.

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 obtener más ejemplos sobre cómo trabajar con variables, incluido el trabajo con variables en trabajos y fases, consulte Definir variables. Para ver ejemplos de la sintaxis de consulta que se ha utilizado en el ejemplo anterior, consulte Cómo consultar la salida de un comando de la CLI de Azure mediante una consulta JMESPath.

Contenido relacionado

  • Last updated on