Zagadnienia dotyczące uruchamiania interfejsu wiersza polecenia platformy Azure w środowisku programu PowerShell

  • Artykuł

Interfejs wiersza polecenia platformy Azure to narzędzie do zarządzania zasobami platformy Azure za pomocą poleceń referencyjnych interfejsu wiersza polecenia platformy Azure uruchamianych zarówno w środowisku powłoki Bash, jak i programu PowerShell. Istnieją jednak niewielkie różnice składni w formatowaniu parametrów między środowiskami, które mogą powodować nieoczekiwane wyniki. Celem tego artykułu jest pomoc w rozwiązywaniu problemów ze składnią interfejsu wiersza polecenia platformy Azure podczas pracy w środowisku programu PowerShell.

W tym artykule porównano różnice składni poleceń interfejsu wiersza polecenia platformy Azure wykonywane w następujących środowiskach:

  • Powłoka Bash działająca w systemie operacyjnym Linux przy użyciu usługi Azure Cloud Shell.
  • Program PowerShell uruchomiony w systemie operacyjnym Linux przy użyciu usługi Azure Cloud Shell.
  • Program Windows PowerShell uruchomiony w systemie Windows 11 przy użyciu terminalu programu PowerShell 5.
  • Program PowerShell uruchomiony w systemie Windows 11 przy użyciu terminalu programu PowerShell 7.

Jeśli dopiero zaczynasz korzystać z interfejsu wiersza polecenia, różnicowanie między narzędziem a środowiskiem może być mylące. Sposób wybierania odpowiedniego narzędzia wiersza polecenia zapewnia dobre porównanie.

Wymagania wstępne

Ten artykuł jest przeznaczony do czytania i nauki. Jeśli jednak chcesz uruchomić przykłady, wybierz kartę Prepare your environments , aby zainstalować środowiska używane w tym artykule.

Ważne

Jeśli masz skrypt interfejsu wiersza polecenia platformy Azure, który generuje błąd, rozważ, w jaki sposób środowisko, w którym pracujesz, analizuje składnię polecenia interfejsu wiersza polecenia platformy Azure.

Przekazywanie przestrzeni w parametrach interfejsu wiersza polecenia platformy Azure

W interfejsie wiersza polecenia platformy Azure, gdy musisz przekazać wartość parametru zawierającą spację, istnieją różnice między systemami operacyjnymi i środowiskami. W tym przykładzie użyj polecenia az storage account list i zmień nazwę kolumn wyjściowych na wyraz zawierający spację.

W tym przykładzie zwróć uwagę na otokę pojedynczego cudzysłowu ('...') z osadzonymi podwójnymi cudzysłowami ("..."). Ten przykład działa również w programie PowerShell w systemie Linux.

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

Jeśli chcesz dodać filtr, składnia ulegnie zmianie. Zwróć uwagę, że ten przykład opakowuje wartość parametru --query w cudzysłowach ("...") i używa znaku ucieczki ukośnika odwrotnego (\). Ten skrypt nie jest uruchamiany w programie PowerShell.

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

Jeśli właśnie podjęto próbę uruchomienia składni filtru w środowisku programu PowerShell, został wyświetlony komunikat argument --query: invalid jmespath_type value: "[?creationTime >=..."o błędzie . Jednak w powłoce Bash w środowisku systemu Linux dane wyjściowe są podobne do następujących:

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

Przekazywanie parametrów w adresie URL zawierającym ciąg zapytania

Znaki zapytania w adresach URL wskazują koniec adresu URL i początek ciągu zapytania. Oto przykład, który otwiera krok 3 w artykule Dowiedz się, jak używać interfejsu wiersza polecenia platformy Azure:

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

Wyniki ?view=azure-cli-2020-09-01-hybrid w żądanej wersji zawartości referencyjnej interfejsu wiersza polecenia platformy Azure.

Podczas wykonywania poleceń interfejsu wiersza polecenia platformy Azure w środowisku programu PowerShell program PowerShell umożliwia używanie znaków zapytania jako części nazwy zmiennej. Może to spowodować zamieszanie w wartościach parametrów interfejsu wiersza polecenia platformy Azure.

Oto przykład z artykułu Korzystanie z interfejsu API REST platformy Azure:

Zwróć uwagę, jak $containerRegistryName?api-version łączy się ze sobą bez błędu w powłoce Bash.

# Script for a Bash environment

# 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

Przekazywanie parametrów zawierających znak specjalny programu PowerShell

Istnieją znaki specjalne programu PowerShell, takie jak symbol At (@). Aby uruchomić interfejs wiersza polecenia platformy Azure w programie PowerShell, dodaj backtick ` przed znakiem specjalnym, aby go uniknąć. Wartość można również ująć w cudzysłowy pojedyncze (') lub podwójne (").

Następujące trzy przykłady będą działać w programie PowerShell:

  • nazwa_parametru '@parameters.json
  • nazwa parametru "@parameters.json"
  • parameterName "@parameters.json"

Ten przykład nie będzie działać w programie PowerShell:

  • Parametername @parameters.json

Przekazywanie parametrów zawierających kod JSON

W przypadku złożonych argumentów, takich jak ciąg JSON, najlepszym rozwiązaniem jest użycie konwencji interfejsu wiersza polecenia @<file> platformy Azure do załadowania z pliku w celu obejścia interpretacji powłoki. Należy pamiętać, że symbol At (@) jest operatorem platania w programie PowerShell, więc powinien być cytowany.

Istnieją dobre przykłady w pliku az ad app create , które zawierają zarówno zawartość pliku JSON, jak i przykłady poleceń. Oto fragment kodu:

# Script for a Bash environment

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

Przekazywanie parametrów zawierających pary key:value

Niektóre wartości parametrów interfejsu wiersza polecenia platformy Azure, takie jak tagi zasobów platformy Azure, wymagają par key:value. Jeśli element key lub value zawiera spację lub znak specjalny, składnia powłoki Bash i programu PowerShell nie zawsze są takie same.

Zobacz Tworzenie tagów , aby przećwiczyć cytowanie różnic w samouczku Learn, aby użyć interfejsu wiersza polecenia platformy Azure. Ten krok samouczka zawiera przykłady scenariuszy powłoki Bash, programu PowerShell i narzędzia Cmd dla następujących scenariuszy par key:value:

  • Spacje
  • puste wartości
  • znaki specjalne
  • zmienne

Obsługa błędów interfejsu wiersza polecenia platformy Azure w programie PowerShell

Polecenia interfejsu wiersza polecenia platformy Azure można uruchamiać w programie PowerShell, zgodnie z opisem w artykule Wybieranie odpowiedniego narzędzia wiersza polecenia platformy Azure. Jeśli to zrobisz, upewnij się, że rozumiesz obsługę błędów interfejsu wiersza polecenia platformy Azure w programie PowerShell. W szczególności interfejs wiersza polecenia platformy Azure nie tworzy wyjątków dla programu PowerShell w celu przechwycenia.

Alternatywą jest użycie zmiennej automatycznej $? . Ta zmienna zawiera stan ostatniego polecenia. Jeśli poprzednie polecenie zakończy się niepowodzeniem, $? ma wartość $False. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.

W poniższym przykładzie pokazano, jak ta zmienna automatyczna może działać w celu obsługi błędów:

# Script for a PowerShell environment

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

Polecenie az kończy się niepowodzeniem, ponieważ brakuje wymaganego --location parametru. Instrukcja warunkowa znajduje wartość $? false i zapisuje błąd.

Jeśli chcesz użyć try słów kluczowych i catch , możesz użyć throw polecenia , aby utworzyć wyjątek dla try bloku w celu przechwycenia:

# Script for a PowerShell environment

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

Domyślnie program PowerShell przechwytuje tylko błędy zakończenia. W tym przykładzie ustawiono zmienną $ErrorActionPreference globalną tak Stop , aby program PowerShell mógł obsłużyć błąd.

Instrukcja warunkowa sprawdza zmienną, $? aby sprawdzić, czy poprzednie polecenie nie powiodło się. Jeśli tak, throw słowo kluczowe tworzy wyjątek do przechwycenia. Blok catch może służyć do pisania komunikatu o błędzie lub obsługi błędu.

Przykład przywraca $ErrorActionPreference wartość domyślną.

Aby uzyskać więcej informacji na temat obsługi błędów programu PowerShell, zobacz Wszystko, co chciałeś wiedzieć o wyjątkach.

Włączanie uzupełniania kart w programie PowerShell

Uzupełnianie karty, nazywane również "kompletnymi elementami interfejsu wiersza polecenia platformy Azure", zapewnia uzupełnianie danych wejściowych w celu zapewnienia wskazówek, włączania odnajdywania i przyspieszania wprowadzania danych wejściowych. Nazwy poleceń, nazwy grup poleceń, parametry i niektóre wartości parametrów można automatycznie wstawić do wiersza polecenia, naciskając klawisz Tab .

Uzupełnianie kart jest domyślnie włączone w usłudze Azure Cloud Shell i w większości dystrybucji systemu Linux. Począwszy od interfejsu wiersza polecenia platformy Azure w wersji 2.49, możesz włączyć uzupełnianie kart dla interfejsu wiersza polecenia platformy Azure w programie PowerShell. Wykonaj te kroki:

  1. Utwórz lub edytuj profil przechowywany w zmiennej $PROFILE. Najprostszym sposobem jest uruchomienie notepad $PROFILE w programie PowerShell. Aby uzyskać więcej informacji, zobacz Jak utworzyć profil i profile i zasady wykonywania.

  2. Dodaj następujący kod do profilu programu 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. Aby wyświetlić wszystkie dostępne opcje w menu, dodaj Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete go do profilu programu PowerShell.

Zobacz też