Freigeben über

Azure DevOps CLI in Azure-Pipeline-YAML

Azure DevOps Services

Wenn Sie Azure DevOps CLI mit einer YAML-Pipeline verwenden möchten, können Sie die Azure DevOps-Erweiterung verwenden oder die AzureCLI-Aufgabe verwenden. Die von Microsoft gehosteten Windows- und Linux-Agenten sind mit Azure CLI und der Azure DevOps CLI-Erweiterung vorkonfiguriert. Die Azure DevOps CLI-Erweiterung führt Befehle aus az devops .

Sie können sich mit einem PAT authentifizieren oder die AzureCLI@2 Aufgabe mit einer Dienstverbindung verwenden. Die Verwendung einer Dienstverbindung ist die sicherere Option, da Sie keine Anmeldeinformationen manuell verwalten müssen.

Authentifizierung 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. Als sicherere Alternative können Sie die AzureCLI@2 Aufgabe verwenden, um eine Dienstverbindung aufzufüllen.

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

Anmeldung bei Azure DevOps CLI mit von Windows und Linux gehosteten Agenten

Die von Microsoft gehosteten Windows- und Linux-Agenten 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 ubuntu-latest Von Microsoft gehostete Agent-Image verwendet. Sie können sie durch eines der anderen von Windows oder Linux gehosteten Images ersetzen.

In diesem Beispiel wird die Authentifizierung mit dem Azure DevOps CLI durchgefü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 der Azure DevOps CLI-Erweiterung mit auf macOS gehosteten Agenten

Die von Microsoft gehosteten macOS-Agenten 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 Agents

Von Microsoft gehosteten Agenten stellen in der Regel 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 ihre Versionen für von Microsoft gehostete Agenten zu überprüfen, einschließlich der installierten Version der Azure CLI- und Azure DevOps CLI-Erweiterung, folgen Sie den Links Enthaltene Software in der Tabelle Software.
  • Informationen zum Überprüfen der aktuellen Version für Azure CLI finden Sie unter Installieren der Azure CLI.

Sie können die Azure CLI auf Ihren gehosteten Images 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 von 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"
    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'

Azure DevOps CLI mit selbstgehosteten Agenten

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

Manuelles Installieren der Azure CLI- und Azure DevOps CLI-Erweiterung

Das Installieren der Azure CLI- und Azure DevOps CLI-Erweiterung auf Ihrem selbst gehosteten Agenten, wenn Sie das Image des virtuellen Computers für den Agenten bereitstellen, ist schneller als dies jedes Mal zu tun, wenn die Pipeline ausgeführt wird.

Informationen zum Installieren von Azure CLI auf Ihrem selbst gehosteten Agenten-Image finden Sie unter Installieren der Azure CLI. Es gibt separate Anweisungen für Windows, Linux und macOS.

Nachdem Sie Azure CLI installiert haben, installieren Sie die Azure DevOps CLI-Erweiterung.

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

Für das folgende Beispiel für die Konfiguration der Azure CLI- und Azure DevOps CLI-Erweiterung für einen selbst gehosteten Agenten mit einer Pipeline gelten die folgenden Voraussetzungen.

# 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 die Azure CLI DevOps-Erweiterung:

  • Azure CLI Version 2.10.1 oder höher ist 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 wird Azure CLI installiert, gefolgt von der Azure DevOps CLI-Erweiterung.

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 in task.setvariable beschriebene -Syntax. 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 AzureCLI@2 Aufgabe bereit, ohne dass die manuelle Anmeldeinformationsverwaltung in der Pipeline erforderlich ist.

Hinweis

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

In diesem Codebeispiel wird ein neuer Parameter serviceConnectionmit dem Namen einer vorhandenen Dienstverbindung definiert. Auf diesen Parameter wird in der AzureCLI@2 Aufgabe verwiesen. Der Vorgang listet alle Projekte () und Pools () auf .The task lists all projects (az devops project list) and 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

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 in task.setvariable beschriebene -Syntax. 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 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)'

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 Abfragen der Azure CLI-Befehlsausgabe mithilfe einer JMESPath-Abfrage.

Verwandte Inhalte

  • Last updated on