Azure CLI 문제 해결
오류 범주
Azure CLI에서 반환되는 대부분의 오류는 다음 범주 중 하나에 속합니다.
| 오류 범주 | 일반 오류 원인 |
|---|---|
| 인식할 수 없는 인수 | 매개 변수의 철자가 잘못되었거나 존재하지 않습니다. |
| 필수 인수 누락 | 필수 매개 변수가 지정되지 않았거나 두 개의 "매개 변수 쌍" 중 하나만 지정됩니다. 매개 변수의 철자가 잘못되었을 수도 있습니다. |
| 상호 배타적 인수 | 둘 이상의 매개 변수를 함께 지정할 수 없습니다. |
| 잘못된 인수 값 | 매개 변수 값 이 잘못되었습니다. 이 오류는 따옴표, 이스케이프 문자 또는 간격으로 인해 발생하는 경우가 많습니다. |
| 잘못된 요청 | HTTP 상태 코드 400은 이 오류를 반환합니다. 누락된 공백, 누락된 매개 변수 대시 또는 추가 또는 누락된 작은따옴표 또는 큰따옴표를 확인합니다. 이 오류는 매개 변수 값에 허용되는 값이 없는 경우에도 발생합니다. |
| 리소스를 찾을 수 없음 | 매개 변수 값에서 참조되는 Azure 리소스를 찾을 수 없습니다. |
| 인증 | Microsoft Entra 인증에 실패했습니다. |
--debug 매개 변수
각 Azure CLI 참조 명령에 대해 Azure CLI가 실행되는 것을 확인하는 가장 좋은 방법 중 하나는 매개 변수를 --debug 사용하는 것입니다. 다음은 실패한 명령과 성공한 명령 모두에 대한 예 --debug 입니다.
# Error example: Create a resource group, but omit the quotes around the resource group name.
az group create --location eastus2 --name msdocs-rg-test --debug
다음은 디버그 출력의 부분입니다. 로그 위치 및 인식할 수 없는 인수를 확인합니다.
cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-name', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.azclierror: unrecognized arguments: msdocs-rg-test
...
위에 제공된 오류 --debug 출력을 성공적인 실행과 비교합니다.
# Correct example: Because the resource group name contains special characters, enclose it in quotes
az group create --location eastus2 --name "msdocs-rg-test" --debug
다음은 디버그 출력의 부분입니다. 로그 위치, API 호출 및 런타임을 확인합니다.
cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-n', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/msdocs-rg-test?api-version=YYYY-MM-DD'
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': 'ba7ee6f4-2dcc-11ef-81ce-00155dadc5c8'
cli.azure.cli.core.sdk.policies: 'CommandName': 'group create'
cli.azure.cli.core.sdk.policies: 'ParameterSetName': '-l -n --debug'
cli.azure.cli.core.sdk.policies: 'User-Agent': 'AZURECLI/2.61.0 (RPM) azsdk-python-core/1.28.0 Python/3.9.19 (Linux-5.10.102.2-microsoft-standard-x86_64-with-glibc2.35) cloud-shell/1.0'
cli.azure.cli.core.sdk.policies: 'Authorization': '*****'
cli.azure.cli.core.sdk.policies: Request body:
cli.azure.cli.core.sdk.policies: {"location": "eastus2"}
urllib3.connectionpool: Starting new HTTPS connection (1): management.azure.com:443
urllib3.connectionpool: https://management.azure.com:443 "PUT /subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourcegroups/msdocs-rg-test?api-version=2022-09-01 HTTP/1.1" 201 226
cli.azure.cli.core.sdk.policies: Response status: 201
...
cli.azure.cli.core.sdk.policies: 'Date': 'Tue, 18 Jun 2024 23:44:41 GMT'
cli.azure.cli.core.sdk.policies: Response content:
cli.azure.cli.core.sdk.policies: {"id":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-rg-test","name":"msdocs-rg-test","type":"Microsoft.Resources/resourceGroups","location":"eastus2","properties":{"provisioningState":"Succeeded"}}
...
cli.__main__: Command ran in 1.829 seconds (init: 0.111, invoke: 1.718)
JSON 서식 지정에 --debug 대한 예제는 스크립팅 언어 간 따옴표 차이인 JSON 문자열을 참조 하세요.
일반적인 구문 오류
Azure CLI는 Bash, PowerShell 및 Windows Cmd 모두에서 실행할 수 있지만 스크립팅 언어 간에는 구문 차이가 있습니다. 작은따옴표, 큰따옴표 및 이스케이프 문자를 포함하는 Azure CLI 스크립트는 일반적으로 언어 간에 복사할 때 수정해야 합니다. 이 과제는 매개 변수 값, 특히 매개 변수에 할당된 --query 값에서 가장 자주 표시됩니다. 다음은 몇 가지 일반적인 오류 메시지입니다.
"잘못된 요청 ... {something}이(가) 잘못되었습니다."는 공백, 작은따옴표 또는 큰따옴표 또는 따옴표 부족으로 인해 발생할 수 있습니다.
추가 공간 또는 견적이 있을 때 "예기치 않은 토큰..."이 표시됩니다.
"잘못된 jmespath_type 값" 오류는 매개 변수의 잘못된 따옴표로 인해
--query발생하는 경우가 많습니다.연결 또는 누락된 이스케이프 문자로 인해 문자열의 형식이 제대로 지정되지 않은 경우 "변수 참조가 유효하지 않습니다."가 수신됩니다.
"인식할 수 없는 인수"는 종종 잘못된 줄 연속 문자 또는 철자가 잘못된 매개 변수 이름으로 인해 발생합니다.
줄 연속 문자가 누락된 경우 "단항 연산자 뒤의 식 누락"이 표시됩니다.
구문 오류를 설명하고 작업 예제를 제공하는 데만 사용되는 몇 가지 Azure CLI 문서가 있습니다.
- 스크립팅 언어 간의 차이점 인용
- Bash, PowerShell 및 Cmd 자습서의 구문 차이점
- JMESPath 쿼리를 사용하여 Azure CLI 명령 출력을 쿼리하는 방법에서 많은
--query매개 변수 예제 찾기 - Bash 스크립팅 언어로 Azure CLI를 사용하는 방법
- PowerShell 스크립팅 언어로 Azure CLI를 실행하기 위한 고려 사항
팁
명령 오류를 해결할 수 없는 경우 다른 스크립팅 언어를 사용해 보세요. 대부분의 Azure CLI 설명서는 Bash 스크립팅 언어를 사용하여 ACS(Azure Cloud Shell)에서 작성 및 테스트됩니다. ACS Bash에서 실행할 문서 예제를 가져올 수 있지만 Windows PowerShell에서 실행되지 않는 경우 작은따옴표와 큰따옴표 및 이스케이프 문자 사용을 검토합니다.
오류: 잘못된 값이거나 존재하지 않음
이러한 오류는 잘못된 형식을 포함하는 변수 값을 사용하려고 할 때 종종 발생합니다. Azure CLI의 기본 출력은 JSON이므로 Azure 리소스의 ID를 변수에 저장하려는 경우 지정 --output tsv해야 합니다. 예를 들어 다음과 같습니다.
# Get a subscription that contains a name or phrase
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id")
echo $subscriptionID
# output as JSON
[ "00000000-0000-0000-0000-000000000000" ]
# Try to set your subscription to the new ID
az account set --subscription $subscriptionID
# error output
The subscription of '"00000000-0000-0000-0000-000000000000"' doesn't exist in cloud 'AzureCloud'.
이제 출력 형식을 tsv 사용합니다.
# Get the active subscription
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id" --output tsv)
echo $subscriptionID
# output as TSV
00000000-0000-0000-0000-000000000000
# Successfully set your subscription to the new ID
az account set --subscription $subscriptionID
오류: 인수가 필요하거나 필요합니다.
Azure CLI 명령에 필수 매개 변수 가 없거나 Azure CLI에서 참조 명령을 잘못 구문 분석하는 입력 오류가 발생하는 경우 이 오류가 발생합니다. 스크립트로 작업할 때 하나 이상의 조건이 true인 경우에도 이 오류가 발생합니다.
- 줄 연속 문자가 없거나 잘못되었습니다.
- PowerShell 스크립팅 언어로 작업할 때 줄 연속 문자의 오른쪽에 후행 공백이 있습니다. 현재는 Azure CLI 명령에서 스플래팅 이 지원되지 않습니다.
- 변수 이름에는 대시(-)와 같은 특수 문자가 포함됩니다.
오류: 리소스를 찾을 수 없음
Azure CLI가 매개 변수 값에 전달된 리소스 이름 또는 ID를 찾을 수 없는 경우 일반적으로 다음 이유 중 하나로 인해 발생합니다.
- 리소스 이름 또는 ID의 철자가 잘못되었습니다.
- 리소스 이름은 특수 문자를 포함하며 작은따옴표 또는 큰따옴표로 묶지 않습니다.
- 변수에 전달되는 값에는 보이지 않는 선행 또는 후행 공백이 있습니다.
- 리소스가 있지만 다른 구독에 있습니다.
오류: 문자열을 JSON으로 구문 분석하지 못했습니다.
Bash, Linux의 PowerShell 및 Windows의 PowerShell 간에는 따옴표로 묶인 차이점이 있습니다. 또한 PowerShell 버전이 서로 다른 결과를 생성할 수 있습니다. JSON 문자열과 같은 복잡한 매개 변수의 경우 Azure CLI의 @<file> 규칙을 사용하여 셸의 해석을 우회하는 것이 가장 좋습니다. 자세한 내용은 다음 문서 중 하나를 참조하세요.
Bash, PowerShell 및 Cmd.exe 대한 JSON 구문 예제는 스크립팅 언어 간 차이점 인용 - JSON 문자열 자습서를 참조하세요.
오류: InvalidTemplateDeployment
해당 리소스를 제공하지 않는 위치에 Azure 리소스를 만들려고 하면 "다음 SKU가 용량 제한에 실패했습니다. myDesiredSkuName"은 현재 위치 'mySpecifiedLocation'에서 사용할 수 없습니다."라는 메시지와 유사한 오류가 표시됩니다.
다음은 위치에 만들 수 없는 VM에 대한 전체 오류 예제입니다 westus .
{"error":{"code":"InvalidTemplateDeployment","message":"The template deployment 'vm_deploy_<32 character ID>'
is not valid according to the validation procedure. The tracking id is '<36 character ID>'.
See inner errors for details.","details":[{"code":"SkuNotAvailable","message":"The requested VM size for resource
'Following SKUs have failed for Capacity Restrictions: Standard_DS1_v2' is currently not available
in location 'westus'. Please try another size or deploy to a different location
or different zone. See https://aka.ms/azureskunotavailable for details."}]}}
솔루션은 요청된 Azure 리소스의 속성을 변경하거나 다른 위치를 시도하는 것입니다.
오류: 구독을 찾을 수 없음
구독 이름 또는 ID를 잘못 입력하지 않은 경우 이 오류는 리소스 공급자가 활성 구독에 등록되지 않은 경우에 발생합니다. 예를 들어 실행 az storage account create하려는 경우 공급자를 Microsoft.Storage 등록해야 합니다. 리소스 공급자를 등록하려면 Azure 리소스 공급자 및 유형을 참조 하세요.
오류: 잘못된 핸드셰이크... 인증서 확인 실패
이 오류를 해결하는 방법에 대한 자세한 내용은 프록시 뒤에서 작업을 참조하세요.
프록시 뒤에서 작업
자체 서명된 인증서를 사용하는 프록시 서버에서 Azure CLI를 사용하는 경우 Azure CLI에서 사용하는 Python 요청 라이브러리 로 인해 다음 오류가 SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",)발생할 수 있습니다. 이 오류를 해결하려면 환경 변수 REQUESTS_CA_BUNDLE을 PEM 형식의 CA 번들 인증서 파일 경로로 설정합니다.
| OS | 기본 인증 기관 번들 |
|---|---|
| Windows 32비트 | C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem |
| Windows 64비트 | C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem |
| Ubuntu/Debian Linux | /opt/az/lib/python<version>/site-packages/certifi/cacert.pem |
| CentOS Stream/RHEL/SUSE Linux | /usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem |
| macOS | /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem |
프록시 서버의 인증서를 CA 번들 인증서 파일에 추가하거나 콘텐츠를 다른 인증서 파일에 복사합니다. 그런 다음, REQUESTS_CA_BUNDLE을 새 파일 위치로 설정합니다. 예를 들어 다음과 같습니다.
<Original cacert.pem>
-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----
일부 프록시에는 인증이 필요합니다. HTTP_PROXY 또는 HTTPS_PROXY 환경 변수의 형식은 HTTPS_PROXY="https://username:password@proxy-server:port"와 같은 인증을 포함해야 합니다. 자세한 내용은 Python용 Azure SDK에 대한 프록시를 구성하는 방법을 참조 하세요.
서비스 주체
서비스 주체 문제 해결에 대한 자세한 내용은 서비스 주체 작업 자습서의 정리 및 문제 해결을 참조하세요.
기타 문제
이 문서에 나열되지 않은 Azure CLI에 제품 문제가 발생하는 경우 GitHub에 문제를 제출합니다.
참고 항목
Azure CLI