通过

Azure管道 YAML 中的 Azure DevOps CLI

Azure DevOps Services

Note

此功能将本周和下一周推出。 如果尚未在 Azure DevOps 服务项目中看到该功能，请在几天后重新查看。

Azure DevOps CLI 允许从命令行管理Azure DevOps资源。 使用 AzureCLI@3 任务 在 YAML 管道中运行 CLI 命令，以在 CI/CD 工作流中自动执行常见的 DevOps 任务。 Microsoft托管的Windows和 Linux 代理已包括Azure CLI和 Azure DevOps CLI 扩展。

若要进行身份验证，请使用Azure DevOps服务连接由Microsoft Entra工作负荷联合身份验证提供支持。 建议使用此方法，因为它消除了凭据管理。 仅在服务连接不可用时使用个人访问令牌（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 的变量组的 ID，并在后续步骤中使用此值。

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

有关使用变量（包括跨作业和阶段处理变量）的更多示例，请参阅 “定义变量”。 有关上一示例中使用的查询语法示例，请参阅 如何使用 JMESPath 查询查询Azure CLI命令输出。

相关内容

  • Last updated on