Porady dotyczące pomyślnego korzystania z interfejsu wiersza polecenia platformy Azure
W tym module nauczyłeś się, jak wybrać środowisko, zainstalować Azure CLI, interaktywnie wykonywać polecenia Azure CLI i tworzyć skrypt Bash. Przyjrzyjmy się naszemu uczeniu się o krok dalej i skoncentrujmy się na tym, jak pomyślnie korzystać z interfejsu wiersza polecenia platformy Azure . W tym materiale edukacyjnym dowiesz się, jak Azure CLI działa za kulisami oraz uzyskasz wskazówki dotyczące rozwiązywania problemów.
Wskazówka
Ten moduł jest kursem zaawansowanym, a ta lekcja zawiera szczegółowe informacje na temat interfejsu wiersza polecenia platformy Azure. Jeśli dopiero zaczynasz programować wiersz polecenia, skoncentruj się na pojęciach. Szczegóły stają się łatwiejsze do zrozumienia podczas zdobywania doświadczenia. Nie poddaj się!
Zrozumienie wywołań API Azure CLI
Wykonywanie za graficznym interfejsem użytkownika witryny Azure Portal i wierszem polecenia interfejsu wiersza polecenia platformy Azure to wywołania interfejsu API.
Wywołania APIAzure CLI można uwidocznić przy użyciu parametru --debug. Oto, co się stanie po utworzeniu nowej grupy zasobów:
az group create --location westus2 --name myResourceGroupName --debug
Oto dane wyjściowe terminalu z usługi Azure Cloud Shell z pominięciem niektórych wierszy w celu zwięzłości. Zwróć uwagę na następujące ważne dane wyjściowe:
- Argumenty poleceń: Jest to język skryptowy, a nie interfejs wiersza polecenia platformy Azure, który analizuje argumenty poleceń (parametry). Ta właściwość wyjściowa jest pierwszym miejscem do wyszukania, gdy polecenie powoduje wystąpienie błędu.
- azlogging: Ta ścieżka to miejsce, w którym jest przechowywany plik dziennika.
- Nagłówki żądań: Te nagłówki są wartościami parametrów przekazywanymi przez polecenie PUT .
-
Zawartość odpowiedzi: Ten wynik jest zwracany do konsoli bez pełnego
--debugrezultatu.
cli.knack.cli: Command arguments: ['group', 'create', '--location', 'westus2', '--name', 'myResourceGroupName', '--debug']
cli.knack.cli: __init__ debug log:
...
cli.knack.cli: Event: CommandInvoker.OnPreCommandTableCreate []
cli.azure.cli.core: Modules found from index for 'group': ['azure.cli.command_modules.resource']
cli.azure.cli.core: Loading command modules:
...
cli.azure.cli.core: Loaded 53 groups, 233 commands.
cli.azure.cli.core: Found a match in the command table.
cli.azure.cli.core: Raw command : group create
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/2025-10-08.21-47-27.group_create.5217.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/myResourceGroupName?api-version=2022-09-01'
cli.azure.cli.core.sdk.policies: Request method: 'PUT'
cli.azure.cli.core.sdk.policies: Request headers:
cli.azure.cli.core.sdk.policies: 'Content-Type': 'application/json'
cli.azure.cli.core.sdk.policies: 'Content-Length': '23'
cli.azure.cli.core.sdk.policies: 'Accept': 'application/json'
cli.azure.cli.core.sdk.policies: 'x-ms-client-request-id': 'c79caddc-ed78-11ef-8a83-00155dbc433c'
cli.azure.cli.core.sdk.policies: 'CommandName': 'group create'
cli.azure.cli.core.sdk.policies: 'ParameterSetName': '--location --name --debug'
...
cli.azure.cli.core.sdk.policies: Response content:
...
{
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroupName",
"location": "westus2",
"managedBy": null,
"name": "myResourceGroupName",
"properties": {
"provisioningState": "Succeeded"
},
"tags": null,
"type": "Microsoft.Resources/resourceGroups"
}
cli.knack.cli: Event: Cli.SuccessfulExecute []
cli.knack.cli: Event: Cli.PostExecute [<function AzCliLogging.deinit_cmd_metadata_logging at 0x7f98a6bc7820>]
az_command_data_logger: exit code: 0
...
Kluczowe wnioski z wyników debugowania
- Analizowanie poleceń:Język skryptów (a nie interfejs wiersza polecenia platformy Azure) analizuje argumenty. Najpierw zajrzyj tutaj, gdy rozwiążesz problemy.
-
Lokalizacja pliku dziennika: Znajdź szczegółowe dzienniki na ścieżce pokazanej w
azloggingdla analizy post-mortem. -
Szczegóły interfejsu API: Zobacz wykonywane rzeczywiste wywołanie interfejsu API REST , w tym metodę HTTP (
PUT,GETitp.). -
Kod zakończenia: Wartość
0wskazuje powodzenie; wartości inne niż zero wskazują błędy.
Niektóre polecenia interfejsu wiersza polecenia platformy Azure wykonują wiele akcji. Użyj --debug, aby zobaczyć każde polecenie, które wykonuje Azure CLI. Jeszcze bardziej przydatne, użyj polecenia --debug , aby rozwiązać problemy z przyczyną, dla których skrypt interfejsu wiersza polecenia platformy Azure generuje nieoczekiwane wyniki.
Rozwiązywanie problemów z opcją --debug
Ile razy deweloper pomyślał: "To zadanie powinno być tak proste! Dlaczego mój skrypt nie działa?" Gdy otrzymasz nieoczekiwane wyniki z poleceń interfejsu wiersza polecenia platformy Azure , --debug parametr jest Twoim przyjacielem! Przyjrzyjmy się przykładowi firmy z 100 kontami usługi Azure Storage. Musisz znaleźć te konta, na których jest włączony dostęp publiczny obiektu blob .
# Bash script - INCORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == `true`].id"
Jeśli wartość parametru nie jest poprawnie sformatowana dla języka skryptowego, który analizuje wartość, zostanie wyświetlony invalid jmespath_type value błąd:
cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == ].id', '--debug']
...
cli.azure.cli.core.azclierror: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'
az_command_data_logger: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'
Spójrz na wartość zmiennej Bash przekazywaną dla elementu allowBlobPublicAccess. W rzeczywistości, gdzie jest wartość? Dlaczego brakuje go?
Pamiętaj, że jest to środowisko (nazywane również "językiem skryptów"), które analizuje wartości zmiennych interfejsu wiersza polecenia platformy Azure . Każdy język skryptów, a nawet wersje tego samego języka skryptów, mogą generować różne wyniki. Oto prawidłowy sposób przekazywania wartości parametru boolean w Bash:
# Bash script - CORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == \`true\`].id" --debug
cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == `true`].id', '--debug']
...
[
"/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-rg-00000000/providers/Microsoft.Storage/storageAccounts/msdocssa00000000"
]
Wskazówka
Kluczową różnicą jest ucieczka backticks z \true", więc powłoka Bash nie interpretuje ich jako podstawiania poleceń.
Zrozum ważne pojęcie --debug, a będziesz na dobrej drodze do pomyślnego korzystania z Azure CLI w preferowanym przez siebie środowisku.
Różnice składni języka skryptowego
Jak właśnie skończyliśmy mówić o --debug, następnym krokiem jest zapoznanie się z tym, co powoduje większość błędów skryptów. Skrypt napisany w powłoce Bash musi zostać zmodyfikowany, aby pomyślnie uruchomić w programie PowerShell lub cmd.exe, jeśli skrypt zawiera jedną z następujących konstrukcji:
- Znaki kontynuacji wiersza
- Zmienne
- Losowe identyfikatory
- Cytaty
- Konstrukcje języka programowania
Oto kilka przykładów:
| Składnia | Bash | PowerShell | cmd.exe |
|---|---|---|---|
| Znaki kontynuacji wiersza | Ukośnik odwrotny (\) |
Apostrof odwrotny (`) |
Daszek (^) |
| Nazewnictwo zmiennych | variableName=varValue |
$variableName="varValue" |
set variableName=varValue |
| Liczba jako ciąg |
\50'' |
`50` |
`50` |
| Boolean jako łańcuch |
\prawda |
`false` |
'true' |
| Identyfikator losowy | let "randomIdentifier=$RANDOM*$RANDOM" |
$randomIdentifier = (New-Guid).ToString().Substring(0,8) |
set randomIdentifier=%RANDOM% |
| Pętla |
until, whilefor |
for, , foreach, while, , do-whiledo-until |
for |
| Zapisywanie w konsoli | echo |
Write-Host (preferowane) lub echo |
echo |
Typowe pułapki
Ta tabela przykładowa nie jest wyczerpująca. Ważne jest, aby zrozumieć, kiedy występuje błąd interfejsu wiersza polecenia platformy Azure , należy najpierw wziąć pod uwagę, że może wystąpić problem ze składnią środowiska. Przetestuj tę możliwość , kopiując i wklejając skrypt do innego języka skryptów, takiego jak usługa Azure Cloud Shell. Użyj --debug w obu środowiskach i zanotuj różnice we command arguments właściwości danych wyjściowych.
Ważne
Podczas kopiowania bloków kodu z artykułów firmy Microsoft należy pamiętać, że większość dokumentacji interfejsu wiersza polecenia platformy Azure w firmie Microsoft jest napisana dla powłoki Bash i przetestowana w usłudze Azure Cloud Shell.
Więcej sposobów uzyskiwania pomocy
Użyj polecenia az find
Zapoznaj się z krótkim przewodnikiem po poleceniach interfejsu wiersza polecenia platformy Azure , korzystając z następujących przykładów:
Znajdź najpopularniejsze polecenia związane ze słowem blob:
az find blob
Pokaż najbardziej popularne polecenia dla grupy poleceń interfejsu wiersza polecenia platformy Azure , takie jak az storage:
az find "az storage"
Pokaż najbardziej popularne parametry i polecenia podrzędne dla polecenia interfejsu wiersza polecenia platformy Azure :
az find "az storage account create"
Korzystanie z --help
Jeśli znasz już nazwę żądanego polecenia, --help argument dla tego polecenia pobiera bardziej szczegółowe informacje na temat polecenia i listę dostępnych podpolecenia dla grupy poleceń. Kontynuując pracę z naszymi przykładami usługi Azure Storage , poniżej przedstawiono sposób uzyskiwania listy podgrup i poleceń do zarządzania usługą blob konta magazynu:
az storage account blob-service-properties --help
Wskazówka
Aby uzyskać szczegółowe informacje o użyciu bez opuszczania terminalu, użyj --help z dowolnym poleceniem lub podpoleceniem.
Indeksy dokumentacji od A do Z
Aby znaleźć przykłady poleceń referencyjnych interfejsu wiersza polecenia platformy Azure , użyj jednego z kilku indeksów od A do Z:
Indeks odwołania: Udostępnia listę od A do Z wszystkich grup odwołań. Rozwiń lewy pasek nawigacyjny dla podgrup.
Lista artykułów koncepcyjnych Azure CLI: zawiera listę przewodników szybkiego startu od A do Z, poradników, samouczków i modułów szkoleniowych, które wyjaśniają, jak używać poleceń referencyjnych Azure CLI w rzeczywistych scenariuszach. Lista artykułów grupuje je według grupy poleceń Azure CLI, jak
az account,az acr, itp. Użyj Ctrl+F w systemie Windows (Cmd+F w systemie macOS), żeby szybko przejść do wybranej grupy poleceń.Przykładowe skrypty interfejsu wiersza polecenia platformy Azure: Indeks ma trzy karty:
- Lista według obszaru tematu: Znajdź przykłady dla usługi platformy Azure.
- Lista według grupy referencyjnej: Znajdź przykłady dla grupy poleceń referencyjnych.
- Repozytorium GitHub z przykładami Azure CLI: Znajdź przykłady w repozytorium GitHub przykładów Azure CLI.
Korzystanie z narzędzia Copilot
Zarówno Portal Azure, jak i przeglądarka Microsoft Edge oferują doświadczenia Copilot, które zwracają informacje na temat poleceń referencyjnych CLI Azure, przykładów i opublikowanych artykułów. Copilot udostępnia również linki do powiązanych pytań dotyczących rozwiązania Stack Overflow . Jeśli masz trudne zadanie, które należy wykonać z wieloma krokami skryptów, copilot jest pomocny w kompilowaniu wielu źródeł informacji w celu udzielenia odpowiedzi na pytanie.
Uwaga / Notatka
Narzędzie GitHub Copilot może również pomóc w pisaniu skryptów interfejsu wiersza polecenia platformy Azure bezpośrednio w edytorze kodu, zapewniając inteligentne uzupełnianie kodu i sugestie.