다음을 통해 공유

PowerShell 스크립팅 언어로 Azure CLI를 실행하기 위한 고려 사항

Azure CLI는 Bash 및 PowerShell 스크립팅 언어로 실행되는 Azure CLI 참조 명령을 통해 Azure 리소스를 관리하는 도구입니다. 그러나 스크립팅 언어 간에 매개 변수 서식에 약간의 구문 차이가 있어 예기치 않은 결과가 발생할 수 있습니다. 이 문서의 목적은 PowerShell 스크립팅 언어로 작업할 때 Azure CLI 구문 오류를 해결하는 데 도움이 되는 것입니다.

이 문서에서는 다음 스크립팅 언어로 실행되는 Azure CLI 명령의 구문 차이점을 비교합니다.

  • Azure Cloud Shell을 사용하여 Linux 운영 체제에서 실행되는 Bash입니다.
  • Azure Cloud Shell을 사용하여 Linux 운영 체제에서 실행되는 PowerShell입니다.
  • PowerShell 5 터미널을 사용하여 Windows 11에서 실행되는 Windows PowerShell입니다.
  • PowerShell 7 터미널을 사용하여 Windows 11에서 실행되는 PowerShell입니다.

CLI를 접하는 경우 도구 와 스크립팅 언어 를 구분하는 것이 혼란스러울 수 있습니다. 올바른 명령줄 도구를 선택하는 방법은 좋은 비교를 제공합니다.

필수 조건

이 문서는 읽고 배우기 위한 것입니다. 그러나 예제를 실행하려면 탭을 선택하여 Prepare your environments 이 문서에 사용된 스크립팅 언어를 설치합니다.

중요합니다

오류를 생성하는 Azure CLI 스크립트가 있는 경우 작업 중인 스크립팅 언어가 Azure CLI 명령 구문을 구문 분석하는 방법을 고려합니다.

Azure CLI 매개 변수에 공백을 전달하기

Azure CLI에서 공백이 포함된 매개 변수 값을 전달해야 하는 경우, 운영 체제와 스크립팅 언어에 따라 따옴표 처리 방식이 다릅니다. 이 예제에서는 az storage account list 를 사용하고 공백이 포함된 단어를 사용하여 출력 열의 이름을 바꿉니다.

이 예제에서는 작은따옴표('...') 래퍼에 포함된 큰따옴표("...")에 주목합니다. 이 예제는 Linux의 PowerShell에서도 작동합니다.

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

필터를 추가하려면 구문이 변경됩니다. 이 예제에서는 매개변수 값을 --query 큰따옴표("...")로 래핑하고 백슬래시(\) 이스케이프 문자를 사용하는 방법을 보십시오. 이 스크립트는 PowerShell에서 실행되지 않습니다.

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

PowerShell 스크립팅 언어로 필터 구문을 실행하려고 하면 오류 메시지가 표시됩니다 argument --query: invalid jmespath_type value: "[?creationTime >=...". 그러나 Linux 환경 내의 Bash에서 출력은 다음과 유사합니다.

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

쿼리 문자열을 포함하는 URL에 매개 변수 전달

URL의 물음표는 URL의 끝과 쿼리 문자열의 시작을 나타냅니다. 다음은 Azure CLI를 사용하기 위해 Learn의 3단계를 여는 예제입니다.

/cli/azure/account?view=azure-cli-2020-09-01-hybrid;

?view=azure-cli-2020-09-01-hybrid 원하는 버전의 Azure CLI 참조 콘텐츠의 결과입니다.

PowerShell 스크립팅 언어로 Azure CLI 명령을 실행하면 PowerShell에서 물음표가 변수 이름의 일부가 될 수 있습니다. 이렇게 하면 Azure CLI 매개 변수 값에 혼동이 발생할 수 있습니다.

다음은 Azure REST API 사용 문서의 예입니다.

Bash에서 오류 없이 어떻게 연결되는지 $containerRegistryName?api-version 확인합니다.

# 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

앰퍼샌드 기호를 포함하는 매개 변수 전달

매개 변수 값에 앰퍼샌드를 전달해야 하는 시나리오가 있는 경우 앰퍼샌드(&) 기호는 PowerShell에서 해석됩니다. 매개 변수를 사용하여 이 작업을 확인할 수 있습니다.--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

그러나 이 동일한 테스트를 사용하여 리소스 그룹에 태그를 추가하는 경우 태그 값의 앰퍼샌드에서 오류가 발생하지 않습니다.

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

매개 변수 값의 앰퍼샌드에서 오류가 발생하는 시나리오가 있는 경우 몇 가지 해결 방법은 다음과 같습니다.

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

at(@) 기호를 포함하는 매개 변수 전달

PowerShell의 스플래팅 연산자인 @() 기호와 같은 특별한 문자가 있습니다. 특수 문자 앞에 백틱 ` 을 추가하여 이스케이프합니다. 값을 작은따옴표(') 또는 큰따옴표(")로 묶을 수도 있습니다.

다음 세 가지 예제는 PowerShell에서 작동합니다.

  • 매개변수 이름 '@parameters.json
  • parameterName '@parameters.json'
  • parameterName "@parameters.json"

이 예제는 PowerShell에서 작동하지 않습니다.

  • 매개변수이름 @parameters.json

명령의 또 다른 예 az ad app create 는 다음과 같습니다. PowerShell 스크립팅 언어에 필요한 JSON 파일 이름 주위에 큰따옴표("...")를 확인합니다.

# Script for a PowerShell scripting language

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

JSON을 포함하는 매개 변수 전달

JSON 문자열과 같은 복잡한 인수의 경우 Azure CLI의 @<file> 규칙을 사용하여 파일에서 로드하여 셸의 해석을 우회하는 것이 가장 좋습니다. Bash, PowerShell 및 Cmd.exe대한 JSON 구문 예제는 스크립팅 언어 간의 따옴표 차이인 JSON 문자열을 참조하세요.

키:값 쌍을 포함하는 매개 변수 전달

Azure 리소스 태그와 같은 일부 Azure CLI 매개 변수 값에는 키:값 쌍이 필요합니다. key 공백 또는 value 특수 문자가 있거나 포함된 경우 Bash 및 PowerShell 구문이 항상 동일하지는 않습니다.

Bash, PowerShell 및 Cmd에 대한 구문 예제를 보려면 Azure CLI 사용법 배우기 자습서의 차이점을 인용하는 연습을 위해 태그 만들기를 참조하세요. 이 자습서 단계에서는 다음 키:값 쌍 시나리오에 대한 예제를 제공합니다.

  • 공간
  • 빈 값
  • 특수 문자
  • 변수

분석 금지 기호

PowerShell 3.0에서 도입된 중지 구문 분석 기호(--%)는 PowerShell이 PowerShell 명령 또는 식으로 입력을 해석하지 않도록 지시합니다. 중지 구문 분석 기호가 발견되면 PowerShell은 줄의 나머지 문자를 리터럴로 처리합니다.

az --% vm create --name xxx

PowerShell에서 Azure CLI에 대한 오류 처리

올바른 Azure 명령 줄 도구 선택에서 설명한 대로 PowerShell에서 Azure CLI 명령을 실행할 수 있습니다. 이 경우 PowerShell에서 Azure CLI 오류 처리를 이해해야 합니다. 특히 Azure CLI는 PowerShell에서 잡을 수 있도록 예외를 만들지 않습니다.

대안은 자동 변수를 사용하는 것입니다 $? . 이 변수는 가장 최근 명령의 상태를 포함합니다. 이전 명령이 실패하면 $?는 $False 값이 됩니다. 자세한 내용은 및의 about_Automatic_Variables를 참조하세요.

다음 예제에서는 이 자동 변수가 오류 처리에 어떻게 작동할 수 있는지 보여줍니다.

# Script for a PowerShell scripting language

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

az 필수 --location 매개 변수가 없어 명령이 실패합니다. 조건문은 $?가 false임을 발견하고 오류를 기록합니다.

키워드 try 및 catch을 사용하려면, throw를 이용하여 try 블록에서 처리할 예외를 만들 수 있습니다.

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

기본적으로 PowerShell은 종료 오류만 포착합니다. 전역 변수를 $ErrorActionPreference으로 설정하여 PowerShell이 Stop 오류를 처리할 수 있게 하는 예제입니다.

조건문은 변수를 $? 테스트하여 이전 명령이 실패했는지 확인합니다. 이 경우, throw 키워드로 잡을 예외를 만듭니다. 블록을 catch 사용하여 오류 메시지를 작성하거나 오류를 처리할 수 있습니다.

이 예제에서는 기본값으로 복원합니다 $ErrorActionPreference .

PowerShell 오류 처리에 대한 자세한 내용은 예외에 대해 알고 싶은 모든 항목을 참조하세요.

PowerShell에서 탭 완성 기능 활성화

"Azure CLI 완료자"라고도 하는 탭 자동 완성은 입력에 대한 완성을 제공하여 힌트를 제시하고 탐색을 용이하게 하며 입력 속도를 높입니다. 명령 이름, 명령 그룹 이름, 매개 변수 및 특정 매개 변수 값은 Tab 키를 눌러 명령줄에 자동으로 삽입될 수 있습니다.

탭 완성은 Azure Cloud Shell 및 대부분의 Linux 배포판에서 기본적으로 사용하도록 설정됩니다. Azure CLI 버전 2.49부터 PowerShell에서 Azure CLI에 대한 탭 완성을 사용하도록 설정할 수 있습니다. 아래 단계를 수행하세요.

  1. 변수 $PROFILE에 저장된 프로필을 만들거나 편집합니다. 가장 간단한 방법은 PowerShell에서 실행하는 notepad $PROFILE 것입니다. 자세한 내용은 프로필을 만드는 방법 및 프로필 및 실행 정책을 참조하세요.

  2. 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. 메뉴에서 사용 가능한 모든 옵션을 표시하려면 PowerShell 프로필에 추가 Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete 합니다.

참고하십시오