Azure CLI를 성공적으로 사용하기 위한 팁

  • 5분

이 모듈에서는 환경을 선택하고, Azure CLI를 설치하고, Azure CLI 명령을 대화형으로 실행하고, Bash 스크립트를 만드는 방법을 알아보았습니다. 한 단계 더 학습하고 Azure CLI 를 성공적으로 사용하는 방법에 집중해 보겠습니다. 이 단원에서는 명령줄 뒤에서 Azure CLI 가 작동하는 방식을 알아보고 문제 해결을 위한 팁을 제공합니다.

팁 (조언)

이 모듈은 고급 수준 과정이며, 이 단원에서는 Azure CLI를 자세히 살펴보게 됩니다. 명령줄 프로그래밍을 접하는 경우 개념에 집중합니다. 경험을 쌓으면 세부 정보를 더 쉽게 이해할 수 있습니다. 포기하지 마세요!

Azure CLI API 호출 이해

Azure Portal의 그래픽 사용자 인터페이스와 Azure CLI의 명령줄 뒤에서 실행하는 것은 API 호출입니다. 매개 변수를 사용하여 Azure CLI의API 호출 을 노출할 --debug 수 있습니다. 새 리소스 그룹을 만들 때 발생하는 작업은 다음과 같습니다.

az group create --location westus2 --name myResourceGroupName --debug

다음은 간단히 하기 위해 일부 줄이 생략된 Azure Cloud Shell 의 터미널 출력입니다. 이 중요한 출력은 다음과 같습니다.

  • 명령 인수: 명령 인수(매개 변수)를 구문 분석하는 것은 Azure CLI가 아닌 스크립팅 언어입니다. 이 출력 속성은 명령에서 오류가 발생할 때 가장 먼저 볼 수 있는 위치입니다.
  • azlogging: 이 경로는 로그 파일이 저장되는 위치입니다.
  • 요청 헤더: 이러한 헤더는 PUT 명령에서 전달하는 매개 변수 값입니다.
  • 응답 콘텐츠: 이 출력은 전체 --debug 출력 없이 콘솔에 반환됩니다.
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
...

디버그 출력의 주요 인사이트

  • 명령 구문 분석:스크립팅 언어 ( Azure CLI 아님)는 인수를 구문 분석합니다. 문제 해결 시 먼저 여기를 참조하세요.
  • 로그 파일 위치: 사후 분석을 위해 표시된 경로에서 azlogging 자세한 로그를 찾습니다.
  • API 세부 정보:HTTP 메서드(PUT등)를 포함하여 실제 GET 호출을 확인합니다.
  • 종료 코드: 값은 0 성공을 나타내고, 0이 아닌 값은 오류를 나타냅니다.

일부 Azure CLI 명령은 여러 작업을 수행합니다. --debug가 실행 중인 각 명령을 확인하는 데 사용합니다. 더욱 유용한 방법은 --debug 스크립트가 예기치 않은 결과를 생성하는 이유를 해결하는 데 사용합니다.

--debug로 문제 해결

개발자로서 몇 번이나 "이 작업은 정말 간단해야 하는데! 내 스크립트가 작동하지 않는 이유는 무엇인가요?" Azure CLI 명령에서 예기치 않은 결과를 받으면 매개 변수가 --debug 친구입니다. Azure Storage 계정이 100개인 회사의 예를 살펴보겠습니다. Blob 퍼블릭 액세스가 활성화된 계정을 찾아야 합니다.

# Bash script - INCORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == `true`].id"

매개 변수 값이 이를 구문 분석하는 스크립팅 언어에 맞게 올바른 형식으로 지정되지 않으면, 다음과 같은 오류 메시지를 받게 됩니다 invalid jmespath_type value.

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'

Bash가 전달하는 변수 값을 확인합니다allowBlobPublicAccess. 실제로 가치는 어디에 있나요? 누락된 이유는 무엇인가요?

환경("스크립팅 언어"라고도 함)은 Azure CLI 변수 값을 구문 분석합니다. 각 스크립팅 언어 와 동일한 스크립팅 언어의 버전도 서로 다른 결과를 생성할 수 있습니다. 부울 매개 변수 값을 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"
]

팁 (조언)

주요 차이점은 백틱을 \true``로 이스케이프하여 Bash가 이를 명령 대체로 해석하지 않도록 하는 것입니다.

중요한 개념을 --debug파악하고 선택한 환경에서 Azure CLI 를 성공적으로 사용하려고 합니다.

스크립팅 언어 구문 차이점

방금 얘기를 --debug마쳤으므로 다음 단계는 대부분의 스크립팅 오류의 원인을 파악하는 것입니다. Bash로 작성된 스크립트는 PowerShell 또는 cmd.exe에서 포함된 특정 구문이 있는 경우 성공적으로 실행되도록 수정해야 합니다.

  • 줄 연속 문자
  • 변수
  • 임의 식별자
  • 견적
  • 프로그래밍 언어 구문

다음은 몇 가지 예입니다.

문법 Bash PowerShell cmd.exe
줄 이음 문자 백슬래시(\) 백틱(`) Caret(^)
변수 이름 지정 variableName=varValue $variableName="varValue" set variableName=varValue
문자열로 번호 매기기 \50'' `50` `50`
문자열로서의 부울 \true`` `false` 'true'
임의 ID let "randomIdentifier=$RANDOM*$RANDOM" $randomIdentifier = (New-Guid).ToString().Substring(0,8) set randomIdentifier=%RANDOM%
반복 until, whilefor for, foreach, while, do-whiledo-until for
콘솔에 쓰기 echo Write-Host (기본 설정) 또는 echo echo

공통 문제

이 예제 테이블은 모두 포함되지 않습니다. Azure CLI 오류를 수신할 때 이해해야 할 중요한 사항은 먼저 사용자 환경에 구문 문제가 있을 수 있음을 고려하는 것입니다. 스크립트를 복사하여 Azure Cloud Shell과 같은 다른 스크립팅 언어에 붙여넣어 가능성을 테스트해보세요. 두 환경에서 --debug을 사용하고 출력의 command arguments 속성 차이점을 확인합니다.

중요합니다

Microsoft 문서에서 코드 블록을 복사하는 경우 Microsoft의 대부분의 Azure CLI 설명서는 Bash용으로 작성되고 Azure Cloud Shell에서 테스트됩니다.

더 많은 도움을 받는 방법

az find 명령을 사용하십시오

다음 예제를 수행하여 Azure CLI 명령을 빠르게 둘러보세요.

Blob 단어와 관련된 가장 인기 있는 명령을 찾습니다.

az find blob

다음과 같이 az storage 명령 그룹에 가장 많이 사용되는 명령을 표시합니다.

az find "az storage"

Azure CLI 명령에 가장 많이 사용되는 매개 변수 및 하위 명령을 표시합니다.

az find "az storage account create"

--help 사용

원하는 명령의 이름을 이미 알고 있는 경우, 해당 명령의 --help 인수를 사용하면 명령에 대한 자세한 정보가 표시되고, 명령 그룹의 사용 가능한 부명령 목록이 표시됩니다. Azure Storage 예제를 계속 진행하면서 스토리지 계정의 Blob Service를 관리하기 위한 하위 그룹 및 명령 목록을 가져오는 방법은 다음과 같습니다.

az storage account blob-service-properties --help

팁 (조언)

터미널을 나가지 않고 명령이나 하위 명령과 함께 사용하여 --help 자세한 사용 정보를 가져옵니다.

A-Z 설명서 인덱스

Azure CLI 참조 명령에 대한 예제를 찾으려면 여러 A-Z 인덱스 중 하나를 사용합니다.

  • 참조 인덱스: 모든 참조 그룹의 A-Z 목록을 제공합니다. 하위 그룹에 대한 왼쪽 탐색 모음을 확장합니다.

  • Azure CLI 개념 문서 목록: 실제 시나리오에서 Azure CLI 참조 명령을 사용하는 방법을 설명하는 빠른 시작, 방법 가이드, 자습서 및 학습 모듈의 A-Z 목록을 제공합니다. 이 문서에서는 Azure CLI 명령 그룹 az account별로 문서를 그룹화한 다음 az acr, Windows에서 Ctrl+F (macOS의 Cmd+F )를 사용하여 원하는 명령 그룹으로 빠르게 이동합니다.

  • Azure CLI 샘플 스크립트: 인덱스에는 세 개의 탭이 있습니다.

코필로트 사용

Azure Portal과 Microsoft Edge는 모두 Azure CLI 참조 명령, 샘플 및 게시된 문서에 대한 정보를 반환하는 Copilot 환경을 제공합니다. Copilot은 관련 Stack Overflow 질문에 대한 링크도 제공합니다. 여러 스크립팅 단계를 수행하는 데 어려운 작업이 있는 경우 Copilot 는 질문에 대답하기 위해 여러 정보 원본을 컴파일하는 데 유용합니다.

비고

또한 GitHub Copilot 를 사용하면 코드 편집기에서 직접 Azure CLI 스크립트를 작성하여 지능형 코드 완성 및 제안을 제공할 수 있습니다.