Delen via

Azure DevOps CLI in Azure Pipeline YAML

Azure DevOps Services

Note

Deze functie wordt deze week en volgende uitgerold. Als u de functie nog niet ziet in uw Azure DevOps Services-project, controleert u over een paar dagen opnieuw.

Azure DevOps CLI laat u Azure DevOps-middelen vanaf de opdrachtregel beheren. Voer CLI-opdrachten uit in een YAML-pijplijn met de AzureCLI@3 taak om algemene DevOps-taken te automatiseren als onderdeel van uw CI/CD-werkstroom. Door Microsoft gehoste Windows- en Linux-agents bevatten al Azure CLI en de Azure DevOps CLI-extensie.

Gebruik voor verificatie een Azure DevOps-serviceverbinding ondersteund door Microsoft Entra werkbelasting-identiteitsfederatie. We raden deze methode aan omdat het referentiebeheer wordt geëlimineerd. Gebruik alleen een persoonlijk toegangstoken (PAT) als er geen serviceverbinding beschikbaar is.

Verifiëren met Azure DevOps

Voor sommige Azure DevOps CLI-opdrachten, zoals az devops configure en az devops --help, is geen verificatie vereist. Ze maken geen verbinding met Azure DevOps. De meeste opdrachten communiceren met Azure DevOps en vereisen wel verificatie.

U kunt verifiëren met behulp van het beveiligingstoken System.AccessToken dat wordt gebruikt door de actieve pijplijn, door deze toe te wijzen aan een omgevingsvariabele met de naam AZURE_DEVOPS_EXT_PAT, zoals wordt weergegeven in het volgende voorbeeld.

Het gebruik van System.AccessToken is afhankelijk van het beschikken over een PAT. Gebruik een serviceverbinding als veiliger alternatief. Zie Serviceverbindingen beheren voor hulp bij het instellen.

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

Als u meerdere stappen hebt waarvoor verificatie is vereist, voegt u de AZURE_DEVOPS_EXT_PAT omgevingsvariabele toe aan elke stap.

Zie Toegang tot opslagplaatsen, artefacten en andere resources voor meer informatie over de reikwijdte van het beveiligingstoken dat wordt gebruikt door de uitgevoerde pijplijn.

Zie Aanmelden met een persoonlijk toegangstoken voor meer informatie over verificatie met een persoonlijk toegangstoken (PAT).

Aanmelden bij Azure DevOps CLI met Windows en door Linux gehoste agents

De Microsoft gehoste Windows- en Linux-agents zijn vooraf geconfigureerd met Azure CLI en de Azure DevOps CLI-extensie.

In het volgende voorbeeld ziet u hoe u zich aanmeldt bij Azure DevOps en een paar opdrachten uitvoert. In dit voorbeeld wordt het door Microsoft gehoste agent-image gebruikt. U kunt deze vervangen door een van de andere Windows of door Linux gehoste installatiekopieën.

In dit voorbeeld wordt geverifieerd met Azure DevOps CLI. Het maakt gebruik van het beveiligingstoken System.AccessToken dat wordt gebruikt door de lopende pijplijn.

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 CLI-extensie installeren met door macOS gehoste agents

De Microsoft-gehoste macOS-agents hebben de Azure CLI geïnstalleerd, maar niet de Azure DevOps CLI-extensie. Als u de Azure DevOps CLI-extensie wilt installeren, voert u de volgende opdracht uit in uw pijplijn voordat u Azure DevOps CLI-aanroepen uitvoert.

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

Upgraden van gehoste agent Azure CLI-versie

Microsoft-gehoste agents brengen doorgaans wekelijkse updates aan op de software in de virtuele omgevingen. Voor sommige hulpprogramma's wordt de nieuwste versie op het moment van de implementatie gebruikt. In andere gevallen wordt het hulpprogramma vastgemaakt aan specifieke versies.

  • Volg de Included Software koppelingen in de tabel om de opgenomen software en de bijbehorende versies te controleren op Microsoft gehoste agents, inclusief de geïnstalleerde versie van Azure CLI en Azure DevOps CLI-extensie.
  • Zie Het installeren van de Azure CLI als u de huidige versie voor Azure CLI wilt controleren.

U kunt de Azure CLI bijwerken op uw gehoste installatiekopieën door de volgende opdrachten uit te voeren in uw pijplijn.

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

De AZURE DEVOPS CLI-extensie voorwaardelijk installeren

Als uw pijplijn wordt uitgevoerd op verschillende installatiekopieën van Microsoft virtuele machines, waarvan sommige niet de Azure DevOps CLI-extensie hebben geïnstalleerd, kunt u voorwaardelijk installeren.

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 met zelf-hostende agents

U kunt de volgende methoden gebruiken om de Azure DevOps CLI te installeren of bij te werken in uw zelf-hostende agent.

Handmatig Azure CLI en Azure DevOps CLI-extensie installeren

Het installeren van de Azure CLI en de Azure DevOps CLI-extensie op uw zelfgehoste agent wanneer u de virtuele machine-image voor de agent configureert, is sneller dan het installeren ervan elke keer dat de pijplijn wordt uitgevoerd.

Zie Install the Azure CLI als u Azure CLI wilt installeren op de installatiekopie van uw zelf-hostende agent. Er zijn afzonderlijke instructies voor Windows, Linux en macOS.

Nadat u Azure CLI hebt geïnstalleerd, installeert u de Azure DevOps CLI-extensie.

Installeer Azure CLI en Azure DevOps CLI-extensie in uw pijplijn

Het volgende voorbeeld van het configureren van Azure CLI en Azure DevOps CLI-extensie op een zelf-hostende agent met behulp van een pijplijn heeft de volgende vereisten.

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

Installeer Azure CLI DevOps-extensie:

  • Azure CLI versie 2.10.1 of hoger is geïnstalleerd.
  • Er is een versie van bash geïnstalleerd op de agent en in het pad. Er is een bash-installatie vereist voor het gebruik van de bash-taak.
# 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
# ...

In het volgende voorbeeld wordt Azure CLI geïnstalleerd, gevolgd door de Azure DevOps CLI-extensie.

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

De resultaten van een Azure DevOps CLI-aanroep toewijzen aan een variabele

Als u de resultaten van een Azure DevOps CLI-aanroep naar een pijplijnvariabele wilt opslaan, gebruikt u de syntaxis task.setvariable beschreven in Variabelen instellen in scripts. In het volgende voorbeeld wordt de id opgehaald van een variabelegroep met de naam Fabrikam-2023 en wordt deze waarde in een volgende stap gebruikt.

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'

Verifiëren met een serviceverbinding

Wanneer u een serviceverbinding gebruikt, biedt de serviceverbinding de benodigde referenties voor Azure CLI en Azure DevOps CLI-opdrachten in de AzureCLI@3 taak zonder dat handmatig referentiebeheer in de pijplijn is vereist.

Note

Wanneer u een serviceverbinding gebruikt voor verificatie met AzureCLI@3, moet u handmatig de service-principal toevoegen aan uw Azure DevOps-organisatie.

Zie Serviceverbindingen beheren voor richtlijnen zonder PAT en best practices voor serviceverbindingen.

In dit codevoorbeeld wordt een nieuwe parameter gedefinieerd, serviceConnectionmet de naam van een bestaande serviceverbinding. Naar deze parameter wordt verwezen in de AzureCLI@3 taak. Het script maakt gebruik van een geheimloze verbinding om een REST-eindpunt aan te roepen en geeft vervolgens projecten en pools weer.

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

De resultaten van een Azure DevOps CLI-aanroep toewijzen aan een variabele

Als u de resultaten van een Azure DevOps CLI-aanroep naar een pijplijnvariabele wilt opslaan, gebruikt u de syntaxis task.setvariable beschreven in Variabelen instellen in scripts. In het volgende voorbeeld wordt de id opgehaald van een variabelegroep met de naam kubernetes en wordt deze waarde gebruikt in een volgende stap.

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

Zie Variabelen definiëren voor meer voorbeelden van het werken met variabelen, waaronder het werken met variabelen tussen taken en fasen. Zie voor voorbeelden van de querysyntaxis die in het vorige voorbeeld wordt gebruikt Hoe u de uitvoer van Azure CLI-opdrachten kunt opvragen met een JMESPath-query.

Verwante inhoud

  • Last updated on