Interfaccia della riga di comando di Azure DevOps in YAML della pipeline di Azure

Servizi di Azure DevOps

Se si vuole usare l'interfaccia della riga di comando di Azure DevOps con una pipeline YAML, è possibile usare l'esempio seguente per comprendere come è possibile usare YAML per installare l'interfaccia della riga di comando di Azure, aggiungere l'estensione Azure DevOps ed eseguire i comandi dell'interfaccia della riga di comando di Azure DevOps.

Nota

I passaggi descritti in questo articolo illustrano come eseguire l'autenticazione con Azure DevOps ed eseguire az devops comandi usando l'estensione dell'interfaccia della riga di comando di Azure DevOps. Se si vuole usare l'interfaccia della riga di comando di Azure per interagire con le risorse di Azure, usare l'attività AzureCLI.

Eseguire l'autenticazione con Azure DevOps

Alcuni comandi dell'interfaccia della riga di comando di Azure DevOps che non chiamano Azure DevOps, ad esempio az devops configure e az devops -h, non richiedono alcuna autenticazione, ma la maggior parte dei comandi interagisce con Azure DevOps e richiedono l'autenticazione. È possibile eseguire l'autenticazione usando il token di sicurezza System.AccessToken usato dalla pipeline in esecuzione assegnandolo a una variabile di ambiente denominata AZURE_DEVOPS_EXT_PAT, come illustrato nell'esempio seguente.

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

Se sono presenti più passaggi che richiedono l'autenticazione, aggiungere la AZURE_DEVOPS_EXT_PAT variabile di ambiente a ogni passaggio.

Per altre informazioni sull'ambito del token di sicurezza usato dalla pipeline in esecuzione, vedere Accedere a repository, artefatti e altre risorse.

Per altre informazioni sull'autenticazione tramite un token di accesso personale, vedere Accedere con un token di accesso personale (PAT).For more information about authentication using a personal access token, see Sign in with a personal access token (PAT).

Interfaccia della riga di comando di Azure DevOps con agenti ospitati in Windows e Linux

Gli agenti Windows e Linux ospitati da Microsoft sono preconfigurati con l'interfaccia della riga di comando di Azure e l'estensione dell'interfaccia della riga di comando di Azure DevOps.

L'esempio seguente illustra come accedere ad Azure DevOps ed eseguire alcuni comandi. Questo esempio usa l'immagine dell'agente ubuntu-latest ospitato da Microsoft, ma è possibile sostituirla con qualsiasi altra immagine ospitata in Windows o Linux.

Questo esempio esegue l'autenticazione con l'interfaccia della riga di comando di Azure DevOps usando il token di sicurezza System.AccessToken usato dalla pipeline in esecuzione.

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)

Interfaccia della riga di comando di Azure DevOps con agenti ospitati in macOS

Gli agenti ospitati da Microsoft macOS hanno installato l'interfaccia della riga di comando di Azure, ma non l'estensione dell'interfaccia della riga di comando di Azure DevOps. Per installare l'estensione dell'interfaccia della riga di comando di Azure DevOps, eseguire il comando seguente nella pipeline prima di effettuare chiamate all'interfaccia della riga di comando di Azure DevOps.

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

Versione dell'interfaccia della riga di comando di Azure dell'agente ospitato

Gli agenti ospitati da Microsoft distribuiscono in genere aggiornamenti settimanali al software negli ambienti virtuali. Per alcuni strumenti, viene usata la versione più recente al momento della distribuzione; per altri, lo strumento viene aggiunto a versioni specifiche.

  • Per controllare il software incluso e le relative versioni per gli agenti ospitati da Microsoft, inclusa la versione installata dell'interfaccia della riga di comando di Azure e l'estensione dell'interfaccia della riga di comando di Azure DevOps, seguire i collegamenti Software inclusi nella tabella Software.
  • Per controllare la versione corrente per l'interfaccia della riga di comando di Azure, vedere Come installare l'interfaccia della riga di comando di Azure.

Se viene rilasciata una versione più recente dell'interfaccia della riga di comando di Azure e le immagini ospitate non hanno ancora la versione più recente, è possibile aggiornare la versione dell'interfaccia della riga di comando di Azure alla versione più recente eseguendo i comandi seguenti nella 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'

Installare in modo condizionale l'estensione dell'interfaccia della riga di comando di Azure DevOps

Se si dispone di una pipeline in esecuzione in diverse immagini di macchine virtuali ospitate da Microsoft, alcune delle quali non hanno installato l'estensione dell'interfaccia della riga di comando di Azure DevOps, è possibile eseguire tale passaggio in modo condizionale, come illustrato nell'esempio seguente.

trigger:
- main

# Run on multiple Microsoft-hosted agent images
strategy:
  matrix:
    linux22:
      imageName: "ubuntu-22.04"
    linux20:
      imageName: "ubuntu-20.04"
    mac13:
      imageName: "macos-13"
    mac12:
      imageName: "macos-12"
    mac11:
      imageName: "macos-11"
    windows2019:
      imageName: "windows-2019"
    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'

Interfaccia della riga di comando di Azure DevOps con agenti self-hosted

Se l'agente self-hosted non è configurato con il software necessario per usare l'interfaccia della riga di comando di Azure DevOps o se si vuole assicurarsi di avere le versioni più recenti, è possibile installare il software necessario seguendo questa procedura.

Installare manualmente l'interfaccia della riga di comando di Azure e l'estensione dell'interfaccia della riga di comando di Azure DevOps

L'installazione dell'interfaccia della riga di comando di Azure e dell'estensione dell'interfaccia della riga di comando di Azure DevOps nell'agente self-hosted quando si effettua il provisioning dell'immagine della macchina virtuale per l'agente è molto più veloce rispetto all'installazione ogni volta che viene eseguita la pipeline.

  • Per installare l'interfaccia della riga di comando di Azure nell'immagine dell'agente self-hosted, vedere Installare l'interfaccia della riga di comando di Azure. Sono disponibili istruzioni separate per Windows, Linux e macOS.
  • Dopo aver installato l'interfaccia della riga di comando di Azure, installare l'estensione dell'interfaccia della riga di comando di Azure DevOps.

Installare l'interfaccia della riga di comando di Azure e l'estensione dell'interfaccia della riga di comando di Azure DevOps nella pipeline

L'esempio seguente di configurazione dell'interfaccia della riga di comando di Azure e dell'estensione dell'interfaccia della riga di comando di Azure DevOps in un agente self-hosted tramite una pipeline presenta i prerequisiti seguenti.

  • Installare l'interfaccia della riga di comando di Azure con Python

    # 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'
    
  • Installare l'estensione DevOps dell'interfaccia della riga di comando di Azure

    • È installata l'interfaccia della riga di comando di Azure versione 2.10.1 o successiva.
    • È disponibile una versione di bash installata nell'agente e nel percorso. Per usare l'attività bash è necessaria un'installazione 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
    # ...
    

L'esempio seguente installa l'interfaccia della riga di comando di Azure seguita dall'estensione dell'interfaccia della riga di comando di 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
# ...

Assegnare i risultati di una chiamata dell'interfaccia della riga di comando di Azure DevOps a una variabile

Per archiviare i risultati di una chiamata dell'interfaccia della riga di comando di Azure DevOps a una variabile della pipeline, usare la task.setvariable sintassi descritta in Impostare le variabili negli script. L'esempio seguente recupera l'ID di un gruppo di variabili denominato Fabrikam-2023 e quindi usa questo valore in un passaggio successivo.

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'

Per altri esempi di utilizzo delle variabili, tra cui l'uso di variabili tra processi e fasi, vedere Definire le variabili. Per esempi della sintassi di query usata nell'esempio precedente, vedere Come eseguire query sull'output dei comandi dell'interfaccia della riga di comando di Azure usando una query JMESPath.