Советы по эффективному использованию Azure CLI

Статья
03/01/2024

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

Дополнительные сведения о конкретных командах Azure CLI см. в справочном списке Azure CLI.

Форматирование вывода

С командами Azure CLI используются три распространенных формата выходных данных:

Формат json отображает информацию в виде строки JSON.
- Этот вариант предоставляет самую детализированную информацию.
- Этот формат используется по умолчанию, но можно использовать параметр --output для указания другого параметра.
- Измените глобальный формат по умолчанию на один из ваших личных предпочтений с помощью az config , az config set core.output=tableнапример.
- Формат JSON сохраняет двойные кавычки, что обычно делает его непригодным для целей сценариев.
Формат table представляет выходные данные в удобной для чтения таблице. Вы можете указать, какие значения нужно включить в таблицу, и с помощью запросов изменить их отображение, как показано здесь:
```
# command
az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table

# output
Name    Os
------  ------------
myVMname   UbuntuServer
```
Формат tsv возвращает значения, разделенные символами табуляции и новой строки, без дополнительного форматирования, ключей и других символов.
- Формат TSV полезен для краткого вывода и работы со скриптами.
- TSV полоскает двойные кавычки, которые сохраняет формат JSON.
- Чтобы указать формат TSV, используйте параметр --query.
```
export vm_ids=$(az vm list --show-details --resource-group myResourceGroup --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids
```

Подробнее об этих и других форматах см. в статье о форматах выходных данных для команд Azure CLI.

Передача значений в другую команду

Если значение используется несколько раз, назначьте его переменной. Переменные позволяют использовать эти значения по несколько раз или создавать обобщенные скрипты. В этом примере в переменную сохраняется идентификатор, полученный командой az vm list.

# assign the list of running VMs to a variable
running_vm_ids=$(az vm list --resource-group MyResourceGroup --show-details \
    --query "[?powerState=='VM running'].id" --output tsv)

# verify the value of the variable
echo $running_vm_ids

Если значение используется только один раз, лучше использовать вертикальную черту. (Piping передает выходные данные одной команды в качестве входных данных второй команде.)

az vm list --query "[?powerState=='VM running'].name" --output tsv | grep my_vm

Для списков с несколькими значениями вы можете использовать следующие параметры:

Если вам важно точнее настроить результат, используйте цикл for:

#!/usr/bin/env bash
for vmList in $(az vm list --resource-group MyResourceGroup --show-details --query "[?powerState=='VM running'].id"   --output tsv); do
    echo stopping $vmList
    az vm stop --ids $vmList
    if [ $? -ne 0 ]; then
        echo "Failed to stop $vmList"
        exit 1
    fi
    echo $vmList stopped
done

Также можно применить xargs и, при желании, флаг -P для параллельного выполнения операций для повышения производительности.
```
az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | xargs -I {} -P 10 az vm start --ids "{}"
```
Наконец, Azure CLI имеет встроенную поддержку параллельного выполнения для команд с несколькими --ids. Это дает результат, аналогичный применению xargs. @- используется для получения значений из канала:
```
az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | az vm start --ids @-
```

Дополнительные сведения об использовании конструкций Bash с Azure CLI, включая циклы, операторы case, if...then...else и обработку ошибок, см. статью Обучение работе с Bash с помощью Azure CLI.

Использование кавычек в параметрах

При работе с командами Azure CLI не забывайте, как правильно использовать кавычки и escape-символы в выбранной оболочке. Если вы поддерживаете сценарии, используемые в разных оболочках, понять, как они отличаются.

Bash. Заключение в кавычки
PowerShell. Сведения о правилах заключения в кавычки
Командная строка Windows. Руководство. Escape-символы, разделители и кавычки в командной строке Windows

Примечание.

Из-за известной проблемы в PowerShell применяется ряд дополнительных правил по использованию escape-символов. Дополнительные сведения см. в статье Проблемы с заключением в кавычки в PowerShell.

Чтобы избежать непредвиденных результатов, соблюдайте несколько рекомендаций:

Если вам нужно передать параметр, который содержит пробел, заключите его в кавычки.
В Bash и PowerShell правильно интерпретируются как одинарные, так и двойные кавычки. В командной строке Windows правильно интерпретируются только двойные кавычки. Одинарные кавычки обрабатываются как часть значения.
Если ваша команда будет выполняться только в Bash (или Zsh), используйте одинарные кавычки, чтобы сохранить содержимое внутри строки JSON. При предоставлении встроенных значений JSON необходимы одинарные кавычки. Например, такой код JSON считается допустимым в оболочке Bash: '{"key": "value"}'.
Если команда выполняется в командной строке Windows, необходимо использовать двойные кавычки. Если значение содержит двойные кавычки, их необходимо экранировать. Эквивалент приведенной выше строки JSON — это "{\"key\": \"value\"}".
В PowerShell, если значение является пустой строкой, используйте '""'.
В Bash или PowerShell, если значение является пустой строкой ''кавычки, используйте "''".
Используйте соглашение @<file> Azure CLI для загрузки данных из файла, чтобы обойти механизмы интерпретирования в оболочке.
```
az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json
```
Bash интерпретирует двойные кавычки в экспортируемых переменных. Если вас устраивает такое поведение, экранируйте переменную: "\$variable".
Некоторые команды Azure принимают список значений, разделенных пробелами.
- Если имя ключа или значение содержат пробелы, заключите в кавычки всю пару: "my key=my value". Например:
```
az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"
```
- Если параметр CLI утверждает, что принимает разделенный пробелами список, ожидается один из таких двух форматов:
  1. Список с разделителями-пробелами без кавычек: --parameterName firstValue secondValue.
  2. Список с разделителями-пробелами с кавычками: --parameterName "firstValue" "secondValue".
  Этот пример представляет собой строку с пробелом в ней. Это не разделенный пробелами список: --parameterName "firstValue secondValue"
В PowerShell поддерживаются несколько специальных символов, например @. Чтобы выполнить команды Azure CLI в PowerShell, добавьте ` перед каждым специальным символом, чтобы экранировать его. Вы также можете целиком заключить значение в одинарные или двойные кавычки "/".
```
# The following three examples will work in PowerShell
--parameterName `@parameters.json
--parameterName '@parameters.json'
--parameterName "@parameters.json"

# This example will not work in PowerShell
--parameterName @parameters.json
```
Если вы используете в команде параметр --query, некоторые символы JMESPath нужно экранировать в оболочке.
- Bash
- PowerShell
- CMD
Следующие три команды в Bash корректны и эквивалентны:
```
az version --query '"azure-cli"'
az version --query \"azure-cli\"
az version --query "\"azure-cli\""
```
Ниже приведены два примера неправильных команд в Bash:
```
# Wrong, as the dash needs to be quoted in a JMESPath query
az version --query azure-cli
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

# Wrong, as the dash needs to be quoted in a JMESPath query, but quotes are interpreted by Bash
az version --query "azure-cli"
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'
```
Дополнительные примеры сравнений Bash, PowerShell и командной строки см. в статье Запрос выходных данных команды Azure CLI с помощью запроса JMESPath.
Эти пять команд работают правильно в PowerShell:
```
az version --query '\"azure-cli\"'
az version --query "\`"azure-cli\`""
az version --query "\""azure-cli\"""
az --% version --query "\"azure-cli\""
az --% version --query \"azure-cli\"
```
Дополнительные примеры сравнений Bash, PowerShell и командной строки см. в статье Запрос выходных данных команды Azure CLI с помощью запроса JMESPath.
Эти две команды работают правильно в командной строке Windows:
```
az version --query "\"azure-cli\""
az version --query \"azure-cli\"
```
Дополнительные примеры сравнений Bash, PowerShell и командной строки см. в статье Запрос выходных данных команды Azure CLI с помощью запроса JMESPath.

Лучший способ устранить проблему с кавычками — выполнить команду с флагом --debug. Этот флаг позволяет отобразить реальные полученные аргументы Azure CLI с использованием синтаксиса Python.

# Correct
$ az '{"key":"value"}' --debug
Command arguments: ['{"key":"value"}', '--debug']

# Correct
$ az "{\"key\":\"value\"}" --debug
Command arguments: ['{"key":"value"}', '--debug']

# Wrong, as quotes and spaces are interpreted by Bash
$ az {"key": "value"} --debug
Command arguments: ['{key:', 'value}', '--debug']

# Wrong, as quotes are interpreted by Bash
$ az {"key":"value"} --debug
Command arguments: ['{key:value}', '--debug']

Использование знаков дефиса в параметрах

Если значение параметра начинается с дефиса, Azure CLI пытается анализировать его как имя параметра. Чтобы проанализировать его как значение, используйте = для сцепления имения параметра со значением: --password="-VerySecret".

Асинхронные операции

Операции в Azure иногда занимают значительное время. Например, настройка виртуальной машины в центре обработки не может выполняться мгновенно. Перед выполнением следующих команд Azure CLI ожидает, пока завершится предыдущая. Поэтому многие команды предлагают параметр --no-wait, как показано ниже:

az group delete --name MyResourceGroup --no-wait

При удалении группы ресурсов все ресурсы, принадлежащие к ней, также удаляются. Удаление этих ресурсов может занять много времени. При выполнении команды с --no-wait параметром консоль принимает новые команды без прерывания удаления.

Многие команды поддерживают параметр wait, который приостанавливает работу консоли до выполнения определенного условия. В следующем примере команда az vm wait выполняется для параллельного создания нескольких независимых ресурсов:

az vm create --resource-group VMResources --name virtual-machine-01 --image centos --no-wait
az vm create --resource-group VMResources --name virtual-machine-02 --image centos --no-wait

subscription=$(az account show --query "id" -o tsv)
vm1_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-01"
vm2_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-02"
az vm wait --created --ids $vm1_id $vm2_id

Вы снова сможете использовать консоль, когда будут созданы оба идентификатора.

Работа за прокси-сервером

Если вы используете Azure CLI через прокси-сервер, использующий самозаверяющие сертификаты, библиотека запросов Python, используемая Azure CLI, может вызвать следующую ошибку: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Чтобы устранить такую ошибку, задайте для переменной среды REQUESTS_CA_BUNDLE путь к файлу пакета центра сертификации в формате PEM.

ОС	Пакет центра сертификации по умолчанию
Windows (32-разрядная версия)	`C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Windows (64-разрядная версия)	`C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Ubuntu/Debian Linux	`/opt/az/lib/python<version>/site-packages/certifi/cacert.pem`
CentOS/RHEL/SUSE Linux	`/usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem`
macOS	`/usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem`

Добавьте в этот файл сертификат прокси-сервера или скопируйте его содержимое в другой файл сертификата. Затем задайте для параметра REQUESTS_CA_BUNDLE новое расположение файла. Приведем пример:

<Original cacert.pem>

-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----

Некоторые прокси-серверы используют аутентификацию. Формат переменных среды HTTP_PROXY и HTTPS_PROXY должен предусматривать значения для аутентификации, например HTTPS_PROXY="https://username:password@proxy-server:port". Дополнительные сведения см. в статье Настройка прокси-серверов для библиотек Azure.

Параллельное выполнение

При одновременном выполнении команд Azure CLI на одном компьютере могут возникать конфликты записи, если несколько команд Azure CLI записываются в один кэш маркеров MSAL.

Чтобы избежать потенциальных сбоев, можно изолировать папку конфигурации Azure CLI для каждого сценария, задав переменную AZURE_CONFIG_DIR среды для каждого скрипта в отдельный каталог. Команды Azure CLI в этом сценарии сохраняют конфигурацию и кэш маркеров в настроенном расположении вместо папки по умолчанию ~/.azure .

export AZURE_CONFIG_DIR=/my/config/dir

$env:AZURE_CONFIG_DIR='D:\my\config\dir'

set AZURE_CONFIG_DIR=D:\my\config\dir

Универсальные параметры обновления

Группы команд Azure CLI часто включают команду обновления (update). Например, для Виртуальных машин Azure поддерживается команда az vm update. Большинство команд обновления принимают три общих параметра: --add, --set и --remove.

Параметры --set и --add принимают список пар "ключ — значение", разделенных пробелами: key1=value1 key2=value2. Просмотреть доступные для изменения свойства можно с помощью команды az vm show.

az vm show --resource-group VMResources --name virtual-machine-01

Чтобы упростить команду, можно использовать строку JSON. Например, для подключения нового диска данных к виртуальной машине используйте такое значение:

az vm update --resource-group VMResources --name virtual-machine-01 \
--add storageProfile.dataDisks "{\"createOption\": \"Attach\", \"managedDisk\":
   {\"id\":
   \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/yg/providers/Microsoft.Compute/disks/yg-disk\"},
   \"lun\": 1}"

Универсальные команды ресурсов (az resource)

Нужная вам служба может не иметь поддержки Azure CLI. Для работы с такими ресурсами можно использовать группу команд az resource.

Если вам достаточно команд для создания или обновления, используйте az deployment group create. Готовые примеры можно изучить в шаблонах быстрого запуска Azure.

Команды REST API (az rest)

Если вам недостаточно универсальных параметров обновления и команд az resource, вы можете использовать az rest для вызова REST API. Эта команда автоматически выполняет аутентификацию с использованием учетных данных пользователя, вошедшего в систему, и устанавливает заголовок Content-Type: application/json. Дополнительные сведения см. в справочнике по REST API в Azure.

Этот пример работает с API Microsoft Graph. Чтобы обновить URI перенаправления для ресурса Application (Приложение), вызовите REST API обновления приложений, как показано в этом коде:

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

При использовании --uri-parameters запросов в виде OData убедитесь, что он будет экранироваться в разных средах: в Bash, escape $$ как \$ и в PowerShell, escape $ как `$

Примеры скриптов

Ниже приведены примеры использования переменных и циклического перебора списков при работе с Виртуальными машинами Azure. Подробные сведения об использовании конструкций Bash с Azure CLI, включая циклы, операторы case, if...then...else и обработку ошибок, см. статью Обучение работе с Bash с помощью Azure CLI.

Используйте эти скрипты для сохранения идентификаторов в переменных:

Bash
PowerShell

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
   `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    SET "vm_ids=%%F %vm_ids%"  :: construct the id list
)
az vm stop --ids %vm_ids% :: CLI stops all VMs in parallel

$vm_ids=(az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids # CLI stops all VMs in parallel

Используйте эти скрипты для циклического перебора списков:

Bash
PowerShell

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
    `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    ECHO Stopping %%F
    az vm stop --ids %%F
)

$vm_ids=(az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv)
foreach ($vm_id in $vm_ids) {
    Write-Output "Stopping $vm_id"
    az vm stop --ids $vm_id
}