通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 PowerShell 脚本语言运行 Azure CLI 的注意事项

  • 项目

Azure CLI 是一种通过 Azure CLI 参考命令管理 Azure 资源的工具，该命令以 Bash 和 PowerShell 脚本语言运行。 但是，脚本语言之间的参数格式存在轻微的语法差异，这可能会导致意外结果。 本文旨在帮助你解决使用 PowerShell 脚本语言时的 Azure CLI 语法错误。

本文比较了使用以下脚本语言执行的 Azure CLI 命令的语法差异：

如果你不熟悉 CLI，则工具与脚本语言之间的差异可能会令人困惑。 如何选择正确的命令行工具 可提供很好的比较。

先决条件

本文旨在供你阅读和学习。 但是，如果要运行示例，请选择 Prepare your environments 选项卡以安装本文中使用的脚本语言。

重要

如果 Azure CLI 脚本生成错误， 请考虑你正在使用的脚本语言如何分析 Azure CLI 命令语法。

在 Azure CLI 参数中传递空格

在 Azure CLI 中，需要传递包含空间的参数值时，操作系统和脚本语言之间存在差异。 在此示例中，使用 az storage account list 并重命名包含空格的单词的输出列。

在此示例中，请注意带有嵌入双引号（）的单引号 （'...'） 包装器。"..." 此示例也适用于 Linux 中的 PowerShell。

az storage account list --query '[].{"SA Name":name, "Primary endpoint":primaryEndpoints.blob}' --output table

如果要添加筛选器，语法将更改。 请注意此示例如何将参数值包装 --query 在双引号 （"..."） 中，并使用反斜杠 （\） 转义字符。 此脚本不会在 PowerShell 中运行。

 az storage account list --query "[?creationTime >='2024-02-01'].{\"SA Name\":name,\"Primary endpoint\":primaryEndpoints.blob}" --output table

如果刚刚尝试以 PowerShell 脚本语言运行筛选器语法，则会收到错误消息 argument --query: invalid jmespath_type value: "[?creationTime >=..."。 但是，在 Linux 环境中的 Bash 中，输出如下所示：

SA Name           Primary Endpoint
-----------       -----------------
msdocssa00000000  https://msdocssa000000000.blob.core.windows.net/

在包含查询字符串的 URL 中传递参数

URL 中的问号指示 URL 的末尾和查询字符串的开头。 以下示例在 Learn 中 打开步骤 3 以使用 Azure CLI：

https://learn.microsoft.com/cli/azure/account?view=azure-cli-2020-09-01-hybrid。

所需的 ?view=azure-cli-2020-09-01-hybrid Azure CLI 引用内容版本的结果。

使用 PowerShell 脚本语言执行 Azure CLI 命令时，PowerShell 允许问号成为变量名称的一部分。 这可能会在 Azure CLI 参数值中创建混淆。

下面是“使用 Azure REST API”一文中的一个示例：

请注意 Bash 中如何 $containerRegistryName?api-version 连接在一起而不出错。

# Script for a Bash scripting language

# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
subscriptionId="00000000-0000-0000-0000-000000000000"
resourceGroup="msdocs-app-rg$randomIdentifier"
containerRegistryName="msdocscr$randomIdentifier"

# prior to this GET example, the resource group and container registry were created in the article.

az rest --method get --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview

传递包含与号的参数

如果需要在参数值中传递安和号，请注意 PowerShell 会解释与号（&） 符号。 可以使用参数看到这种情况：--debug

az "a&b" --debug

# output
'a' is misspelled or not recognized by the system.
'b' is not recognized as an internal or external command

但是，如果使用此相同的测试将标记添加到资源组，则标记值中的与值不会导致错误。

az group create --location eastus2 --name "msdocs-rg-test"
az group update --name "msdocs-rg-test" --tags "company name=Contoso & Sons"

# output
{
  "id": "/subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourceGroups/msdocs-rg-test",
  "location": "eastus2",
  "managedBy": null,
  "name": "msdocs-rg-test",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": {
    "company name": "Contoso & Sons"
  },
  "type": "Microsoft.Resources/resourceGroups"
}

如果有一个方案，其中参数值中的与值导致错误，下面是一些解决方案：

# When quoted by single quotes ('), double quotes (") are preserved by PowerShell and sent
# to Command Prompt, so that ampersand (&) is treated as a literal character
> az '"a&b"' --debug
Command arguments: ['a&b', '--debug']

# Escape double quotes (") with backticks (`) as required by PowerShell
> az "`"a&b`"" --debug
Command arguments: ['a&b', '--debug']

# Escape double quotes (") by repeating them
> az """a&b""" --debug
Command arguments: ['a&b', '--debug']

# With a whitespace in the argument, double quotes (") are preserved by PowerShell and
# sent to Command Prompt
> az "a&b " --debug
Command arguments: ['a&b ', '--debug']

# Use --% to stop PowerShell from parsing the argument
> az --% "a&b" --debug
Command arguments: ['a&b', '--debug']

传递包含 at （@） 符号的参数

PowerShell 有特殊字符，例如 PowerShell 中的 at （@） 符号，它是 PowerShell 中的一个 散点运算符 。 在特殊字符之前添加反引号 ` 以对其进行转义。 还可以将值括在单引号'或双"引号中。

以下三个示例将在 PowerShell 中工作：

  • parameterName '@parameters.json
  • parameterName “@parameters.json”
  • parameterName “@parameters.json”

此示例在 PowerShell 中不起作用：

  • parameterName @parameters.json

下面是命令中的 az ad app create 另一个示例：请注意 PowerShell 脚本语言中所需的 JSON 文件名的双引号（"..."）。

# Script for a PowerShell scripting language

az ad app create --display-name myTestAppName `
    --is-fallback-public-client `
    --required-resource-accesses "@manifest.json"

传递包含 JSON 的参数

对于 JSON 字符串等复杂参数，最佳做法是使用 Azure CLI 的 @<file> 约定从文件加载，以绕过 shell 的解释。 有关 Bash、PowerShell 和 Cmd.exe 的 JSON 语法示例，请参阅 脚本语言之间的引用差异 - JSON 字符串。

传递包含 key：value 对的参数

某些 Azure CLI 参数值（如 Azure 资源标记）需要键：值对。 key如果你或value包含空格或特殊字符，Bash 和 PowerShell 语法并不总是相同的。

有关 Bash、PowerShell 和 Cmd 的语法示例，请参阅“创建标记”来练习在 Learn 中使用 Azure CLI 教程中的差异。 本教程步骤提供了以下键值对方案的示例：

  • 区
  • 空值
  • 特殊字符
  • variables

停止分析符号

PowerShell 3.0 中引入的停止分析符号（--%）指示 PowerShell 不要将输入解释为 PowerShell 命令或表达式。 遇到停止分析符号时，PowerShell 会将行中的剩余字符视为文本。

az --% vm create --name xxx

有关 PowerShell 中 Azure CLI 的错误的处理

可以在 PowerShell 中运行 Azure CLI 命令，如选择正确的 Azure 命令行工具中所述。 如果要这么做，请确保了解如何在 PowerShell 中处理 Azure CLI 错误。 具体而言，Azure CLI 不会创建供 PowerShell 捕获的异常。

一种替代方法是使用 $? 自动变量。 此变量包含最新命令的状态。 如果前面的命令失败，$? 的值为 $False。 有关详细信息，请参阅 about_Automatic_Variables。

下面的示例演示此自动变量如何在错误处理中发挥作用：

# Script for a PowerShell scripting language

az group create --name MyResourceGroup
if ($? -eq $false) {
    Write-Error "Error creating resource group."
}

az 命令失败，因为它缺少必需的 --location 参数。 条件语句发现 $? 为 false 并写入错误。

如果要使用 try 和 catch 关键字，可以使用 throw 来创建供 try 块捕获的异常：

# Script for a PowerShell scripting language

$ErrorActionPreference = "Stop"
try {
    az group create --name MyResourceGroup
    if ($? -eq $false) {
        throw 'Group create failed.'
    }
}
catch {
    Write-Error "Error creating the resource group."
}
$ErrorActionPreference = "Continue"

默认情况下，PowerShell 仅捕获终止错误。 此示例将 $ErrorActionPreference 全局变量设置为 Stop，以便 PowerShell 可以处理错误。

条件语句测试 $? 变量以确定上一个命令是否失败。 如果失败，throw 关键字会创建一个供捕获的异常。 catch 块可用于编写错误消息或处理错误。

该示例将 $ErrorActionPreference 恢复为其默认值。

有关 PowerShell 错误处理的详细信息，请参阅关于异常的各项须知内容。

在 PowerShell 中启用 Tab 自动补全

Tab 自动补全，也称为“Azure CLI 补全器”，提供输入自动补全功能，以提供提示、启用发现和加快条目输入速度。 可以通过按 Tab 键将命令名称、命令组名称、参数和某些参数值自动插入到命令行中。

Tab 自动补全在 Azure Cloud Shell 和大多数 Linux 发行版中默认启用。 从 Azure CLI 版本 2.49 开始，可以在 PowerShell 中为 Azure CLI 启用 Tab 自动补全。 执行以下步骤：

  1. 创建或编辑存储在变量 $PROFILE 中的配置文件。 最简单的方法是在 PowerShell 中运行 notepad $PROFILE。 有关详细信息，请参阅如何创建配置文件和配置文件和执行策略。

  2. 将以下代码添加到 PowerShell 配置文件：

    Register-ArgumentCompleter -Native -CommandName az -ScriptBlock {
    param($commandName, $wordToComplete, $cursorPosition)
    $completion_file = New-TemporaryFile
    $env:ARGCOMPLETE_USE_TEMPFILES = 1
    $env:_ARGCOMPLETE_STDOUT_FILENAME = $completion_file
    $env:COMP_LINE = $wordToComplete
    $env:COMP_POINT = $cursorPosition
    $env:_ARGCOMPLETE = 1
    $env:_ARGCOMPLETE_SUPPRESS_SPACE = 0
    $env:_ARGCOMPLETE_IFS = "`n"
    $env:_ARGCOMPLETE_SHELL = 'powershell'
    az 2>&1 | Out-Null
    Get-Content $completion_file | Sort-Object | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
    }
    Remove-Item $completion_file, Env:\_ARGCOMPLETE_STDOUT_FILENAME, Env:\ARGCOMPLETE_USE_TEMPFILES, Env:\COMP_LINE, Env:\COMP_POINT, Env:\_ARGCOMPLETE, Env:\_ARGCOMPLETE_SUPPRESS_SPACE, Env:\_ARGCOMPLETE_IFS, Env:\_ARGCOMPLETE_SHELL
}

  3. 若要显示菜单中的所有可用选项，请将 Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete 添加到 PowerShell 配置文件。

另请参阅