Freigeben über

Azure DevOps CLI in Azure Pipeline YAML

Azure DevOps Services

Hinweis

Dieses Feature wird in dieser Woche und nächste Woche eingeführt. Wenn das Feature noch nicht in Ihrem Azure DevOps Services-Projekt angezeigt wird, schauen Sie in ein paar Tagen zurück.

mit Azure DevOps CLI können Sie Azure DevOps Ressourcen über die Befehlszeile verwalten. Führen Sie CLI-Befehle in einer YAML-Pipeline mit der AzureCLI@3 Aufgabe aus, um allgemeine DevOps-Aufgaben als Teil Ihres CI/CD-Workflows zu automatisieren. Microsoft gehostete Windows- und Linux-Agents umfassen bereits Azure CLI und die Azure DevOps CLI-Erweiterung.

Verwenden Sie für die Authentifizierung eine Azure DevOps Dienstverbindung, die von der Microsoft Entra Arbeitslast-Identitätsföderation unterstützt wird. Wir empfehlen diesen Ansatz, da dadurch die Verwaltung von Anmeldeinformationen beseitigt wird. Verwenden Sie ein persönliches Zugriffstoken (PERSONAL Access Token, PAT), nur wenn eine Dienstverbindung nicht verfügbar ist.

Authentifizieren mit Azure DevOps

Einige Azure DevOps CLI-Befehle wie az devops configure und az devops --help erfordern keine Authentifizierung. Sie stellen keine Verbindung mit Azure DevOps her. Die meisten Befehle interagieren mit Azure DevOps und erfordern eine Authentifizierung.

Sie können sich mithilfe des von der ausgeführten Pipeline verwendeten Sicherheitstokens System.AccessToken authentifizieren, indem Sie es einer Umgebungsvariable mit dem Namen AZURE_DEVOPS_EXT_PATzuweisen, wie im folgenden Beispiel gezeigt.

Die Verwendung System.AccessToken basiert auf der Verwendung eines PAT. Verwenden Sie als sicherere Alternative eine Dienstverbindung. Anleitungen zum Einrichten finden Sie unter Verwalten von Dienstverbindungen.

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

Wenn Sie über mehrere Schritte verfügen, die eine Authentifizierung erfordern, fügen Sie die AZURE_DEVOPS_EXT_PAT-Umgebungsvariable zu jedem Schritt hinzu.

Weitere Informationen zum Umfang des von der ausgeführten Pipeline verwendeten Sicherheitstokens finden Sie unter Zugriff auf Repositorys, Artefakte und andere Ressourcen.

Weitere Informationen zur Authentifizierung mithilfe eines persönlichen Zugriffstokens (PAT) finden Sie unter Anmelden mit einem persönlichen Zugriffstoken.

Melden Sie sich bei Azure DevOps CLI mit in Windows und Linux gehosteten Agents an

Die Microsoft gehosteten Windows und Linux-Agents sind mit Azure CLI und der Azure DevOps CLI-Erweiterung vorkonfiguriert.

Das folgende Beispiel zeigt, wie Sie sich bei Azure DevOps anmelden und einige Befehle ausführen. In diesem Beispiel wird das image "ubuntu-latest Microsoft-hosted agent" verwendet. Sie können es durch eines der anderen gehosteten Windows- oder Linux-Images ersetzen.

In diesem Beispiel wird die Authentifizierung mit Azure DevOps CLI ausgeführt. Es verwendet das Sicherheitstoken System.AccessToken, das von der ausgeführten Pipeline verwendet wird.

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)

Installieren Azure DevOps CLI-Erweiterung mit macOS gehosteten Agents

Die von macOS Microsoft gehosteten Agents haben Azure CLI installiert, aber nicht die Azure DevOps CLI-Erweiterung. Um die Azure DevOps CLI-Erweiterung zu installieren, führen Sie den folgenden Befehl in Ihrer Pipeline aus, bevor Sie Azure DevOps CLI-Aufrufe ausführen.

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

Upgrade der Azure CLI-Version des gehosteten Agenten

Die von Microsoft gehosteten Agents stellen typischerweise wöchentliche Updates für die Software in den virtuellen Umgebungen bereit. Bei einigen Tools wird die neueste Version zum Zeitpunkt der Bereitstellung verwendet. In anderen Fällen wird das Tool auf bestimmte Versionen festgelegt.

  • Um die enthaltene Software und deren Versionen für Microsoft gehostete Agents zu überprüfen, einschließlich der installierten Version von Azure CLI und Azure DevOps CLI-Erweiterung, folgen Sie der Tabelle Included Softwarelinks in der Tabelle Software.
  • Informationen zum Überprüfen der aktuellen Version für Azure CLI finden Sie unter Wie installieren Sie die Azure CLI.

Sie können die Azure CLI für Ihre gehosteten Bilder aktualisieren, indem Sie die folgenden Befehle in Ihrer Pipeline ausführen.

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

Bedingtes Installieren der Azure DevOps CLI-Erweiterung

Wenn Ihre Pipeline auf mehreren Microsoft gehosteten Images virtueller Computer ausgeführt wird, von denen einige die Azure DevOps CLI-Erweiterung nicht installiert haben, können Sie bedingt installieren.

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 mit selbst gehosteten Agents

Sie können die folgenden Methoden verwenden, um die Azure DevOps CLI in Ihrem selbst gehosteten Agent zu installieren oder zu aktualisieren.

Manuelle Installation von Azure CLI und Azure DevOps CLI-Erweiterung

Das Installieren der Azure CLI und der Azure DevOps CLI-Erweiterung auf Ihrem selbstgehosteten Agenten, wenn Sie das Image des virtuellen Computers für den Agenten bereitstellen, erfolgt schneller als bei jedem Ausführen der Pipeline.

Informationen zum Installieren von Azure CLI auf Ihrem selbst gehosteten Agentimage finden Sie unter Installieren sie den Azure CLI. Es gibt separate Anweisungen für Windows, Linux und macOS.

Installieren Sie nach der Installation Azure CLI die Azure DevOps CLI-Erweiterung.

Installieren Azure CLI und Azure DevOps CLI-Erweiterung in Ihrer Pipeline

Im folgenden Beispiel für die Konfiguration von Azure CLI und Azure DevOps CLI-Erweiterung für einen selbst gehosteten Agent mit einer Pipeline sind die folgenden Voraussetzungen erfüllt.

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

Installieren sie Azure CLI DevOps-Erweiterung:

  • Azure CLI Version 2.10.1 oder höher wird installiert.
  • Auf dem Agenten und im Pfad ist eine Version von bash installiert. Für die Verwendung der Bash-Aufgabe ist eine Bash-Installation erforderlich.
# 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
# ...

Im folgenden Beispiel werden Azure CLI gefolgt von der Azure DevOps CLI-Erweiterung installiert.

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

Zuweisen der Ergebnisse eines Azure DevOps CLI-Aufrufs zu einer Variablen

Um die Ergebnisse eines Azure DevOps CLI-Aufrufs an eine Pipelinevariable zu speichern, verwenden Sie die syntax task.setvariable, die in Setvariablen in Skripts beschrieben ist. Im folgenden Beispiel wird die ID einer Variablengruppe namens Fabrikam-2023 abgerufen und dieser Wert in einem nachfolgenden Schritt verwendet.

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'

Authentifizieren mit einer Dienstverbindung

Wenn Sie eine Dienstverbindung verwenden, stellt die Dienstverbindung die erforderlichen Anmeldeinformationen für Azure CLI und Azure DevOps CLI-Befehle in der aufgabe AzureCLI@3 bereit, ohne dass die manuelle Anmeldeinformationsverwaltung in der Pipeline erforderlich ist.

Hinweis

Wenn Sie eine Dienstverbindung für die Authentifizierung mit AzureCLI@3 verwenden, müssen Sie manuell den Dienstprinzipal zu Ihrer Azure DevOps Organisation hinzufügen.

Informationen zu PAT-kostenlosen Anleitungen und bewährten Methoden für die Dienstverbindung finden Sie unter "Verwalten von Dienstverbindungen".

In diesem Codebeispiel wird ein neuer Parameter serviceConnectionmit dem Namen einer vorhandenen Dienstverbindung definiert. Auf diesen Parameter wird in der AzureCLI@3 Aufgabe verwiesen. Das Skript verwendet eine verbindungslose Verbindung, um einen REST-Endpunkt aufzurufen, und listet dann Projekte und Pools auf.

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

Zuweisen der Ergebnisse eines Azure DevOps CLI-Aufrufs zu einer Variablen

Um die Ergebnisse eines Azure DevOps CLI-Aufrufs an eine Pipelinevariable zu speichern, verwenden Sie die syntax task.setvariable, die in Setvariablen in Skripts beschrieben ist. Im folgenden Beispiel wird die ID einer Variablengruppe namens Kubernetes abgerufen und dieser Wert in einem nachfolgenden Schritt verwendet.

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

Weitere Beispiele für das Arbeiten mit Variablen, einschließlich der Arbeit mit Variablen über Aufträge und Phasen hinweg, finden Sie unter Definieren von Variablen. Beispiele für die abfragesyntax, die im vorherigen Beispiel verwendet wird, finden Sie unter How to query Azure CLI command output using a JMESPath query.

Verwandte Inhalte

  • Last updated on