Azure Pipeline YAML 中的 Azure DevOps CLI

Azure DevOps 服務

Note

這項功能將於本週和下週陸續推出。 如果你還沒在 Azure DevOps Services 專案看到這個功能，幾天後再回來看看。

Azure DevOps CLI 讓你可以從命令列管理 Azure DevOps 資源。 在 YAML 管線中執行 CLI 指令，搭配 AzureCLI@3 任務 ，自動化常見的 DevOps 任務，作為你的 CI/CD 工作流程的一部分。 Microsoft 託管的 Windows 和 Linux 代理程式已經包含 Azure CLI 和 Azure DevOps CLI 擴充功能。

為了驗證，請使用 Azure DevOps service connection，並由 Microsoft Entra 工作負載身份聯盟（workload identity federation）支援。 我們推薦這種做法，因為它省去了資格管理的麻煩。 只有在無法使用服務連線時才使用個人存取權杖（PAT）。

使用 Azure DevOps 進行驗證

有些 Azure DevOps CLI 指令，例如 az devops configure 和 az devops --help，不需要任何認證。 它們不會連接到 Azure DevOps。 大多數指令都會與 Azure DevOps 互動，並且確實需要驗證。

您可以使用執行管線所使用的 System.AccessToken 安全性令牌進行驗證，方法是將它指派給名為 AZURE_DEVOPS_EXT_PAT的環境變數，如下列範例所示。

使用 System.AccessToken 依賴具有 PAT。 作為更安全的替代方案，使用服務連線。 關於設定指引，請參見 「管理服務連線」。

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

如果您有多個需要驗證的步驟，請將 AZURE_DEVOPS_EXT_PAT 環境變數新增至每個步驟。

如需執行中管線所使用之安全性令牌範圍的詳細資訊，請參閱 存取存放庫、成品和其他資源。

如需使用個人存取令牌進行驗證的詳細資訊（PAT），請參閱 使用個人存取令牌登入。

使用 Windows 和 Linux 托管代理登錄到 Azure DevOps CLI

Microsoft 託管的 Windows 與 Linux 代理程式已預先配置 Azure CLI 及 Azure DevOps CLI 擴充套件。

以下範例展示了如何登入 Azure DevOps 並執行幾個指令。 此範例使用 ubuntu-latest Microsoft 託管代理映像檔。 你可以用其他 Windows 或 Linux 託管映像檔替換。

此範例使用 Azure DevOps CLI 進行認證。 它會使用由執行中的管線採用的安全性令牌 System.AccessToken。

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)

在 macOS 托管代理中安裝 Azure DevOps CLI 擴展。

macOS 的 Microsoft 託管代理程式安裝了 Azure CLI，但沒有安裝 Azure DevOps CLI 擴充功能。 要安裝 Azure DevOps CLI 擴充功能，請在管線中執行以下指令，在進行任何 Azure DevOps CLI 呼叫之前。

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

升級託管代理的 Azure CLI 版本

Microsoft託管代理通常每週部署更新至虛擬環境中的軟體。 對於某些工具，會使用部署時的最新版本。 在其他情況下，此工具會固定於特定版本。

  • 要檢查由 Microsoft 託管的代理所附的軟體及其版本，包括已安裝的 Azure CLI 版本和 Azure DevOps CLI 擴充功能，請按照 Software 表格中的 Included Software 連結。
  • 要查詢目前Azure CLI版本，請參考如何安裝Azure CLI。

你可以在管線中執行以下指令，升級你所託管映像的 Azure CLI。

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

有條件地安裝 Azure DevOps CLI 擴充功能

如果你的管線在多個 Microsoft 主機映像檔上運行，其中有些尚未安裝 Azure DevOps CLI 擴充功能，你可以有條件地安裝。

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 與自託管代理程式

你可以使用以下方法在自架代理中安裝或升級 Azure DevOps CLI。

手動安裝 Azure CLI 和 Azure DevOps CLI 擴充功能

在配置虛擬機映像以用於自架代理時安裝 Azure CLI 和 Azure DevOps CLI 擴充功能，比在每次執行管線時再安裝要快。

要在自架代理映像檔安裝Azure CLI，請參見 安裝 Azure CLI。 Windows、Linux 以及 macOS 有獨立的說明。

安裝 Azure CLI 後，安裝 Azure DevOps CLI 擴充功能。

喺你嘅管道安裝 Azure CLI 同 Azure DevOps CLI 擴展

以下範例是利用管線在自架代理上配置 Azure CLI 與 Azure DevOps CLI 擴充，具備以下先決條件。

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

安裝 Azure CLI DevOps 擴充功能：

  • 安裝Azure CLI版本為 2.10.1 或更高版本。
  • 在代理程式上和路徑中已安裝了一個版本的bash。 需要安裝Bash才能使用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
# ...

以下範例安裝 Azure CLI，然後安裝 Azure DevOps CLI 擴展。

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

將 Azure DevOps CLI 呼叫的結果賦值給一個變數

若要儲存Azure DevOps CLI 呼叫到管線變數的結果，請使用 task.setvariable中描述的 語法。 下列範例會取得名為 Fabrikam-2023 的變數群組識別碼，並在後續步驟中使用此值。

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'

使用服務連線進行驗證

當你使用服務連線時，該服務連線會提供必要的憑證，用於AzureCLI@3任務中Azure CLI和Azure DevOps CLI 指令，無需在流程中手動管理憑證。

Note

當你使用服務連線進行 AzureCLI@3 認證時，你需要手動將服務主體加入你的Azure DevOps組織。

關於無需 PAT 的指引及服務連接最佳實務，請參見「管理服務連接」。

此程式代碼範例會定義具有現有服務連線名稱的新參數 serviceConnection。 工作中 AzureCLI@3 會參考該參數。 腳本使用無秘密連線呼叫 REST 端點，然後列出專案與池。

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

將 Azure DevOps CLI 呼叫的結果賦值給一個變數

若要儲存Azure DevOps CLI 呼叫到管線變數的結果，請使用 task.setvariable中描述的 語法。 下列範例會取得名為 kubernetes 的變數群組 ID，並在後續步驟中使用此值。

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

如需使用變數的更多範例，包括跨作業和階段使用變數，請參閱 定義變數。 關於前一個範例中使用的查詢語法範例，請參見 Azure CLI如何使用 JMESPath query查詢指令輸出。

相關內容

  • Last updated on