Porady dotyczące pomyślnego korzystania z interfejsu wiersza polecenia platformy Azure

Artykuł
03/01/2024

Interfejs wiersza polecenia platformy Azure to narzędzie wiersza polecenia, które umożliwia konfigurowanie zasobów platformy Azure i zarządzanie nimi z wielu środowisk powłoki. Po wybraniu preferowanego środowiska powłoki i zainstalowaniu interfejsu wiersza polecenia platformy Azure skorzystaj z tego artykułu, aby dowiedzieć się, jak uniknąć typowych pułapek i pomyślnie użyć interfejsu wiersza polecenia platformy Azure.

Aby dowiedzieć się więcej o konkretnych poleceniach interfejsu wiersza polecenia platformy Azure, zobacz listę dokumentacji interfejsu wiersza polecenia platformy Azure.

Formatowanie danych wyjściowych

Trzy typowe formaty danych wyjściowych są używane z poleceniami interfejsu wiersza polecenia platformy Azure:

Format json przedstawia informacje jako ciąg JSON.
- Plik JSON zapewnia najbardziej kompleksowe informacje.
- Ten format jest domyślny, ale można użyć parametru --output , aby określić inną opcję.
- Zmień domyślny format globalny na jedną z osobistych preferencji, używając polecenia az config , takiego jak az config set core.output=table.
- Format JSON zachowuje podwójne cudzysłowy, co zwykle nie nadaje się do celów skryptowych.

Format table przedstawia dane wyjściowe jako tabelę czytelną. Możesz określić, które wartości są wyświetlane w tabeli, i użyć zapytań, aby dostosować dane wyjściowe, jak pokazano poniżej:

# command
az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table

# output
Name    Os
------  ------------
myVMname   UbuntuServer

Format tsv zwraca wartości rozdzielane tabulatorami i rozdzielane nowym wierszem bez dodatkowego formatowania, kluczy lub innych symboli.
- Format TSV jest przydatny do zwięzłych celów wyjściowych i skryptowych.
- TSV paski podwójnego cudzysłowu, które format JSON zachowuje.
- Aby określić format TSV, użyj parametru --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
```

Aby uzyskać więcej informacji na temat tych i innych formatów, zobacz Formaty danych wyjściowych dla poleceń interfejsu wiersza polecenia platformy Azure.

Przekazywanie wartości do innego polecenia

Jeśli wartość jest używana więcej niż raz, przypisz ją do zmiennej. Zmienne umożliwiają używanie wartości więcej niż raz lub tworzenie bardziej ogólnych skryptów. Ten przykład przypisuje identyfikator znaleziony przez polecenie az vm list do zmiennej.

# 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

Jeśli wartość jest używana tylko raz, rozważ potokowanie. (Potok przekazuje dane wyjściowe jednego polecenia jako dane wejściowe do drugiego polecenia).

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

W przypadku list wielowartych należy wziąć pod uwagę następujące opcje:

Jeśli potrzebujesz więcej kontrolek w wyniku, użyj pętli "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

Alternatywnie użyj xargs flagi -P i rozważ użycie flagi do równoległego uruchamiania operacji w celu zwiększenia wydajności:

az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | xargs -I {} -P 10 az vm start --ids "{}"

Na koniec interfejs wiersza polecenia platformy Azure ma wbudowaną obsługę przetwarzania poleceń z wieloma --ids równoległymi w celu osiągnięcia tego samego efektu xargs. @- służy do pobierania wartości z potoku:
```
az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | az vm start --ids @-
```

Aby uzyskać więcej informacji na temat używania konstrukcji powłoki Bash z interfejsem wiersza polecenia platformy Azure, w tym pętli, instrukcji case, if.. Następnie.. inne i obsługa błędów, zobacz Learn to use Bash with the Azure CLI (Dowiedz się, jak używać powłoki Bash z interfejsem wiersza polecenia platformy Azure).

Używanie cudzysłowów w parametrach

Podczas pracy z poleceniami interfejsu wiersza polecenia platformy Azure należy pamiętać o tym, jak powłoka używa znaków cudzysłowu i znaków ucieczki. Jeśli obsługujesz skrypty używane w różnych powłokach, dowiedz się, jak się różnią.

Bash. Cytując
Program PowerShell. Informacje o regułach cytowania
Wiersz polecenia systemu Windows. Instrukcje: znaki ucieczki, ograniczniki i cudzysłowy w wierszu polecenia systemu Windows

Uwaga

Ze względu na znany problem w programie PowerShell obowiązują pewne dodatkowe reguły ucieczki. Aby uzyskać więcej informacji, zobacz Cytowanie problemów z programem PowerShell.

Aby uniknąć nieprzewidzianych wyników, poniżej przedstawiono kilka sugestii:

Jeśli podasz parametr zawierający biały znak, zawiń go w cudzysłów.
W powłoce Bash lub PowerShell zarówno pojedyncze, jak i podwójne cudzysłowy są prawidłowo interpretowane. W wierszu polecenia systemu Windows tylko cudzysłowy są poprawnie interpretowane — pojedyncze cudzysłowy są traktowane jako część wartości.
Jeśli polecenie będzie uruchamiane tylko w powłoce Bash (lub Zsh), użyj pojedynczych cudzysłowów, aby zachować zawartość wewnątrz ciągu JSON. Pojedyncze cudzysłowy są niezbędne podczas podawania wbudowanych wartości JSON. Na przykład ten kod JSON jest poprawny w powłoce Bash: '{"key": "value"}'.
Jeśli polecenie jest uruchamiane w wierszu polecenia systemu Windows, należy użyć podwójnych cudzysłowów. Jeśli wartość zawiera cudzysłowy podwójne, należy ją ująć w znaki ucieczki. Odpowiednik powyższego ciągu JSON to "{\"key\": \"value\"}"
W programie PowerShell, jeśli wartość jest pustym ciągiem, użyj polecenia '""'.
W powłoce Bash lub programie PowerShell, jeśli wartość jest ciągiem ''pustych cudzysłowów, użyj polecenia "''".
Użyj konwencji interfejsu wiersza polecenia platformy @<file> Azure, aby załadować plik i pominąć mechanizmy interpretacji powłoki.
```
az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json
```
Powłoka Bash ocenia cudzysłowy podwójne w wyeksportowanych zmiennych. Jeśli to zachowanie nie jest potrzebne, należy użyć zmiennej ucieczki: "\$variable".
Niektóre polecenia interfejsu wiersza polecenia platformy Azure przyjmują listę wartości rozdzielonych spacjami.
- Jeśli nazwa lub wartość klucza zawiera spacje, opakuj całą parę: "my key=my value". Na przykład:
```
az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"
```
- Gdy parametr interfejsu wiersza polecenia stwierdza, że akceptuje listę rozdzielaną spacją, oczekuje się jednego z dwóch formatów:
  1. Lista rozdzielona spacjami bez cudzysłów --parameterName firstValue secondValue
  2. Lista rozdzielona spacjami --parameterName "firstValue" "secondValue"
  Ten przykład jest ciągiem z spacją w nim. Nie jest to lista rozdzielona spacjami: --parameterName "firstValue secondValue"
Istnieją znaki specjalne programu PowerShell, takie jak : @. Aby uruchomić interfejs wiersza polecenia platformy Azure w programie PowerShell, dodaj ` przed znakiem specjalnym, aby go uniknąć. Można również ująć wartość w cudzysłów pojedynczych lub podwójnych "/".
```
# 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
```
Jeśli używasz parametru --query z poleceniem, niektóre znaki JMESPath muszą zostać uniknięte w powłoce.
Te trzy polecenia są poprawne i równoważne w powłoce Bash:
```
az version --query '"azure-cli"'
az version --query \"azure-cli\"
az version --query "\"azure-cli\""
```
Oto dwa przykłady nieprawidłowych poleceń w powłoce 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'
```
Aby uzyskać więcej przykładowych porównań między powłoką Bash, programem PowerShell i programem Cmd, zobacz Zapytanie o dane wyjściowe polecenia interfejsu wiersza polecenia platformy Azure
Te pięć poleceń działa poprawnie w programie 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\"
```
Aby uzyskać więcej przykładowych porównań między powłoką Bash, programem PowerShell i programem Cmd, zobacz Zapytanie o dane wyjściowe polecenia interfejsu wiersza polecenia platformy Azure
Te dwa polecenia działają poprawnie w wierszu polecenia systemu Windows:
```
az version --query "\"azure-cli\""
az version --query \"azure-cli\"
```
Aby uzyskać więcej przykładowych porównań między powłoką Bash, programem PowerShell i programem Cmd, zobacz Zapytanie o dane wyjściowe polecenia interfejsu wiersza polecenia platformy Azure

Najlepszym sposobem rozwiązania problemu z cudzysłów jest uruchomienie polecenia z flagą --debug . Ta flaga wyświetla rzeczywiste argumenty odebrane przez interfejs wiersza polecenia platformy Azure w składni języka 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']

Używanie znaków łącznika w parametrach

Jeśli wartość parametru zaczyna się od łącznika, interfejs wiersza polecenia platformy Azure próbuje przeanalizować go jako nazwę parametru. Aby przeanalizować ją jako wartość, użyj polecenia = , aby połączyć nazwę parametru i wartość: --password="-VerySecret".

Operacje asynchroniczne

Operacje na platformie Azure mogą zająć zauważalny czas. Na przykład konfigurowanie maszyny wirtualnej w centrum danych nie jest natychmiastowe. Interfejs wiersza polecenia platformy Azure czeka, aż polecenie zakończy akceptować inne polecenia. W związku z tym wiele poleceń oferuje --no-wait parametr, jak pokazano poniżej:

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

Usunięcie grupy zasobów spowoduje również usunięcie wszystkich zasobów, które do niej należą. Usunięcie tych zasobów może zająć dużo czasu. Po uruchomieniu polecenia z parametrem --no-wait konsola akceptuje nowe polecenia bez przerywania usuwania.

Wiele poleceń oferuje opcję oczekiwania, wstrzymując konsolę do momentu spełnienia pewnego warunku. W poniższym przykładzie użyto polecenia az vm wait , aby obsługiwać równoległe tworzenie niezależnych zasobów:

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

Po utworzeniu obu identyfikatorów można ponownie użyć konsoli.

Praca za serwerem proxy

Jeśli używasz interfejsu wiersza polecenia platformy Azure za pośrednictwem serwera proxy korzystającego z certyfikatów z podpisem własnym, biblioteka żądań języka Python używana przez interfejs wiersza polecenia platformy Azure może spowodować następujący błąd: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Aby rozwiązać ten błąd, ustaw zmienną środowiskową REQUESTS_CA_BUNDLE na ścieżkę pliku certyfikatu pakietu urzędu certyfikacji w formacie PEM.

System operacyjny	Domyślny pakiet urzędu certyfikacji
Windows 32-bitowy	`C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Windows 64-bitowy	`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`

Dołącz certyfikat serwera proxy do pliku certyfikatu pakietu urzędu certyfikacji lub skopiuj zawartość do innego pliku certyfikatu. Następnie ustaw REQUESTS_CA_BUNDLE nową lokalizację pliku. Oto przykład:

<Original cacert.pem>

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

Niektóre serwery proxy wymagają uwierzytelniania. Format HTTP_PROXY zmiennych środowiskowych lub HTTPS_PROXY powinien zawierać uwierzytelnianie, takie jak HTTPS_PROXY="https://username:password@proxy-server:port". Aby uzyskać szczegółowe informacje, zobacz How to configure proxyies for the Azure libraries (Jak skonfigurować serwery proxy dla bibliotek platformy Azure).

Współbieżne wykonywanie

Jeśli uruchamiasz polecenia interfejsu wiersza polecenia platformy Azure jednocześnie na tej samej maszynie, konflikty zapisu mogą wystąpić, jeśli wiele poleceń interfejsu wiersza polecenia platformy Azure zapisuje w tej samej pamięci podręcznej tokenów biblioteki MSAL.

Aby uniknąć potencjalnych awarii, możesz odizolować folder konfiguracji interfejsu wiersza polecenia platformy Azure dla każdego skryptu, ustawiając zmienną środowiskową AZURE_CONFIG_DIR dla każdego skryptu na oddzielny katalog. Polecenia interfejsu wiersza polecenia platformy Azure w tym skrypcie zapisują konfigurację i pamięć podręczną tokenów do skonfigurowanej lokalizacji zamiast folderu domyślnego ~/.azure .

export AZURE_CONFIG_DIR=/my/config/dir

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

set AZURE_CONFIG_DIR=D:\my\config\dir

Ogólne parametry aktualizacji

Grupy poleceń interfejsu wiersza polecenia platformy Azure często zawierają polecenie aktualizacji. Na przykład usługa Azure Virtual Machines zawiera polecenie az vm update . Większość poleceń aktualizacji oferuje trzy ogólne parametry: --add, --seti --remove.

Parametry --set i --add przyjmują listę par klucz-wartość rozdzielona spacją: key1=value1 key2=value2. Aby zobaczyć, jakie właściwości można zaktualizować, użyj polecenia show, takiego jak az vm show.

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

Aby uprościć polecenie, rozważ użycie ciągu JSON. Aby na przykład dołączyć nowy dysk danych do maszyny wirtualnej, użyj następującej wartości:

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}"

Ogólne polecenia zasobów (az resource)

Usługa, z którą chcesz pracować, może nie obsługiwać interfejsu wiersza polecenia platformy Azure. Polecenia az resource umożliwiają pracę z tymi zasobami.

Jeśli potrzebujesz tylko poleceń tworzenia lub aktualizowania, użyj polecenia az deployment group create. Aby zapoznać się z przykładami roboczymi, zobacz Szablony szybkiego startu platformy Azure.

Polecenia interfejsu API REST (az rest)

Jeśli ogólne parametry aktualizacji i az resource nie spełniają Twoich potrzeb, możesz wywołać interfejs API REST za pomocą polecenia az rest . Polecenie automatycznie uwierzytelnia się przy użyciu poświadczeń logowania i ustawia nagłówek Content-Type: application/json. Aby uzyskać więcej informacji, zobacz Dokumentacja interfejsu API REST platformy Azure.

Ten przykład działa z interfejsem API programu Microsoft Graph. Aby zaktualizować identyfikatory URI przekierowania dla aplikacji, wywołaj interfejs API REST aktualizacji aplikacji, jak w tym kodzie:

# 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"]}}'

W przypadku używania --uri-parameters w przypadku żądań w postaci protokołu OData upewnij się, że w różnych środowiskach ucieczka $ : w Bashelemecie , ucieczka $ jako \$ i w PowerShellelemecie ucieczka $ jako `$

Przykłady skryptów

Poniżej przedstawiono przykłady używania zmiennych i pętli na liście podczas pracy z usługą Azure Virtual Machines. Aby uzyskać szczegółowe przykłady dotyczące używania konstrukcji powłoki Bash z interfejsem wiersza polecenia platformy Azure, w tym pętli, instrukcji case, if.. Następnie.. inne i obsługa błędów, zobacz Learn to use Bash with the Azure CLI (Dowiedz się, jak używać powłoki Bash z interfejsem wiersza polecenia platformy Azure).

Użyj tych skryptów, aby zapisać identyfikatory w zmiennych:

Bash
Program 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

Użyj tych skryptów, aby wykonać pętlę na liście:

Bash
Program 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
}