Udostępnij za pośrednictwem

Zagadnienia dotyczące uruchamiania interfejsu wiersza polecenia platformy Azure w języku skryptowym 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 języku skryptów powłoki Bash, jak i programu PowerShell. Istnieją jednak niewielkie różnice składni w formatowaniu parametrów między językami skryptowymi, 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 języku skryptowym programu PowerShell.

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

  • 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 językiem skryptów 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ć języki skryptów 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 język skryptów, 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 językami skryptów. 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 po prostu podjęto próbę uruchomienia składni filtru w języku skryptowym 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/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.

Po wykonaniu poleceń interfejsu wiersza polecenia platformy Azure w języku skryptowym 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 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

Przekazywanie parametrów zawierających symbol ampersand

Jeśli masz scenariusz, w którym musisz przekazać znak ampersand w wartości parametru, pamiętaj, że symbol ampersand (&) jest interpretowany przez program PowerShell. Można to zobaczyć przy użyciu parametru --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

Jeśli jednak użyjesz tego samego testu, aby dodać tag do grupy zasobów, znak ampersand w wartości tagu nie powoduje błędu.

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

Jeśli masz scenariusz, w którym ampersand w wartości parametru powoduje błąd, oto kilka rozwiązań:

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

Przekazywanie parametrów zawierających symbol at (@)

Istnieją znaki specjalne programu PowerShell, takie jak symbol at (@), który jest operatorem rozplatania 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:

  • nazwa parametru @parameters.json

Oto kolejny przykład polecenia az ad app create : Zwróć uwagę na podwójne cudzysłowy ("...") wokół nazwy pliku JSON potrzebnego w języku skryptowym programu PowerShell.

# Script for a PowerShell scripting language

az ad app create --display-name myTestAppName `
    --is-fallback-public-client `
    --required-resource-accesses "@manifest.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. Przykłady składni JSON dla powłoki Bash, programu PowerShell i Cmd.exe można znaleźć w temacie Quoting differences between scripting languages - JSON strings (Cytowanie różnic między językami skryptów — ciągi 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.

Przykłady składni dla powłoki Bash, programu PowerShell i narzędzia Cmd można znaleźć w temacie Create tags to practice quoting differences in the Learn to use the Azure CLI tutorial (Tworzenie tagów w celu przećwiczenie różnic w samouczku Learn to use the Azure CLI ). Ten krok samouczka zawiera przykłady następujących scenariuszy par klucz:wartość:

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

Symbol zatrzymania analizowania

Symbol zatrzymania analizowania (--%), wprowadzony w programie PowerShell 3.0, nakazuje programowi PowerShell powstrzymanie się od interpretowania danych wejściowych jako poleceń lub wyrażeń programu PowerShell. W przypadku napotkania symbolu zatrzymania analizowania program PowerShell traktuje pozostałe znaki w wierszu jako literał.

az --% vm create --name xxx

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 scripting language

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

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 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ż