Поделиться через

Рекомендации по запуску Azure CLI на языке сценариев PowerShell

  • Статья

Azure CLI — это средство для управления ресурсами Azure с помощью ссылочных команд Azure CLI, которые выполняются как на языке сценариев Bash, так и в PowerShell. Однако существуют незначительные различия синтаксиса в форматировании параметров между языками сценариев, которые могут привести к непредвиденным результатам. Цель этой статьи — устранить синтаксические ошибки Azure CLI при работе на языке сценариев PowerShell.

В этой статье сравниваются синтаксические различия команд Azure CLI, выполняемых на следующих языках сценариев:

Если вы не знакомы с ИНТЕРФЕЙСом командной строки, различия между средством и языком сценариев могут быть запутанными. Практическое руководство по выбору правильного средства командной строки обеспечивает хорошее сравнение.

Необходимые компоненты

Эта статья предназначена для чтения и изучения. Однако если вы хотите запустить примеры, выберите Prepare your environments вкладку, чтобы установить языки сценариев, используемые в этой статье.

Внимание

Если у вас есть скрипт Azure CLI, который создает ошибку, рассмотрите способ анализа синтаксиса команды Azure CLI.

Сквозные пробелы в параметрах Azure CLI

В Azure CLI, если необходимо передать значение параметра, содержащее пробел, существуют различия между операционными системами и языками сценариев. В этом примере используйте az storage account list и переименуйте выходные столбцы с словом, содержащим пробел.

В этом примере обратите внимание на одну кавычку ('...') с внедренными двойными кавычками ("..."). Этот пример также работает в PowerShell в Linux.

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

Если вы хотите добавить фильтр, синтаксис изменится. Обратите внимание, как этот пример упаковывает --query значение параметра в двойные кавычки ("...") и использует символ escape-косой черты (\). Этот скрипт не выполняется в 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-адреса и начало строки запроса. Ниже приведен пример, который открывает шаг 3 в Learn, чтобы использовать 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.

При выполнении команд Azure CLI на языке сценариев PowerShell PowerShell позволяет PowerShell задавать вопросительные знаки в составе имени переменной. Это может привести к путанице в значениях параметров Azure CLI.

Ниже приведен пример из статьи об использовании REST API Azure:

Обратите внимание, как $containerRegistryName?api-version объединение объединяется без ошибок в Bash.

# 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, такие как символ at (@), который является оператором сплетирования в PowerShell. Добавьте обратную черту ` перед специальным символом, чтобы экранировать его. Можно также заключить значение в одинарные (') или двойные" () кавычки.

Следующие три примера будут работать в PowerShell:

  • параметрName '@parameters.json
  • параметрName "@parameters.json"
  • параметрName "@parameters.json"

Этот пример не будет работать в PowerShell:

  • parameterName @parameters.json

Ниже приведен еще один пример в команде az ad app create : обратите внимание на двойные кавычки ("...") вокруг имени JSON-файла, необходимого на языке скриптов PowerShell.

# 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> для загрузки из файла для обхода интерпретации оболочки. Примеры синтаксиса JSON для Bash, PowerShell и Cmd.exe см. в статье о различиях между языками сценариев — строками JSON.

Передача параметров, содержащих пары key:value

Для некоторых значений параметров Azure CLI, таких как теги ресурсов Azure, требуются пары key:value. Если или key value содержит пробел или специальный символ, синтаксис Bash и PowerShell не всегда одинаковы.

Примеры синтаксиса для Bash, PowerShell и Cmd см. в статье "Создание тегов для практического применения различий в кавыках" в руководстве по Azure CLI . На этом шаге руководства приведены примеры для следующих сценариев пар "ключ:значение":

  • Пространства
  • пустые значения
  • специальные символы
  • переменные

Символ остановки синтаксического анализа

Символ остановки синтаксического анализа (--%), представленный в PowerShell 3.0, направляет PowerShell, чтобы воздержаться от интерпретации входных данных в виде команд или выражений PowerShell. При обнаружении символа остановки синтаксического анализа PowerShell обрабатывает оставшиеся символы в строке как литерал.

az --% vm create --name xxx

Обработка ошибок для Azure CLI в PowerShell

Команды Azure CLI можно выполнять в PowerShell, как описано в разделе Выбор подходящего средства командной строки 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

Завершение вкладки, также известное как "Завершенные azure CLI", обеспечивает завершение входных данных для предоставления подсказок, включения обнаружения и ускорения ввода. Имена команд, имена групп команд, параметры и определенные значения параметров можно автоматически вставить в командную строку, нажав клавишу TAB .

Завершение вкладок по умолчанию в Azure Cloud Shell и в большинстве дистрибутивов Linux. Начиная с Azure CLI версии 2.49 можно включить завершение вкладки для Azure CLI в PowerShell. Выполните следующие действия:

  1. Создайте или измените профиль, хранящийся в переменной $PROFILE. Самый простой способ — запустить notepad $PROFILE в PowerShell. Дополнительные сведения см. в разделах How to create your profile (Как создать свой профиль) и Profiles and execution policy (Профили и политика выполнения).

  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.

См. также