AWS CLI의 구조화된 오류 출력 - AWS Command Line Interface
오류 형식 구성오류 출력 형식전체 예제

AWS CLI의 구조화된 오류 출력

이 주제에서는 AWS Command Line Interface(AWS CLI)의 구조화된 오류 출력 형식에 대해 설명합니다. CLI는 stderr에 오류를 기록하며 다음 형식을 지원합니다.

  • enhanced(기본값) - 추가 세부 정보가 인라인으로 표시된 오류 메시지입니다. 사람이 읽을 수 있는 디버깅을 위해 사용합니다.

  • json - 출력은 모든 오류 필드를 포함하며 JSON 문자열 형식입니다. 자동화 및 스크립팅을 위해 사용합니다.

  • yaml - 출력은 모든 오류 필드를 포함하며 JSON 문자열입니다. 자동화 및 스크립팅을 위해 사용합니다.

  • text - 텍스트 포맷터를 사용하여 오류를 표시합니다. 빠른 시각적 검토를 위해 사용합니다.

  • table - 테이블 포맷터를 사용하여 오류를 표시합니다. 빠른 시각적 검토를 위해 사용합니다.

  • legacy - 구조화된 세부 정보가 없는 원래 오류 형식입니다. 이전 버전과의 호환성을 위해 사용합니다.

오류 형식 구성

다음 방법 중 하나를 사용하여 오류 형식을 구성할 수 있습니다.

명령줄 플래그
$ aws <command> --cli-error-format json
구성 파일(~/.aws/config)
[default]
cli_error_format = json
환경 변수
$ export AWS_CLI_ERROR_FORMAT=yaml

오류 출력 형식

다음 섹션에서 각 형식에 대해 설명합니다.

향상된 형식(기본값)

향상된 형식은 단순한 값에 대한 추가 세부 정보를 인라인으로 포함하여 오류 메시지를 표시합니다. 복잡한 구조의 경우 이 형식은 JSON 또는 YAML을 사용하라는 힌트를 제공합니다.

예: 리전 구성 누락

aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".

예: 존재하지 않는 S3 버킷에 추가 필드가 포함되어 있음


aws: [ERROR]: An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist

Additional error details:
BucketName: amzn-s3-demo-bucket

예: 복잡한 오류 필드


An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

Additional error details:
CancellationReasons: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

JSON 형식

JSON 형식은 모든 오류 필드가 포함된 구조화된 표현을 제공합니다.

예: 리전 구성 누락

{
    "Code": "NoRegion",
    "Message": "You must specify a region. You can also configure your region by running \"aws configure\"."
}

예: 존재하지 않는 S3 버킷

{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}

YAML 형식

YAML 형식은 모든 오류 필드가 포함된 구조화된 표현을 제공합니다.

예: 리전 구성 누락

Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".

예: 존재하지 않는 S3 버킷

Code: NoSuchBucket
Message: The specified bucket does not exist
BucketName: amzn-s3-demo-bucket

날짜 형식

텍스트 형식은 성공적인 명령 출력과 동일한 포맷터를 사용합니다.

예: 존재하지 않는 S3 버킷

amzn-s3-demo-bucket  NoSuchBucket    The specified bucket does not exist

테이블 형식

테이블 형식은 성공적인 명령 출력과 동일한 포맷터를 사용합니다.

예: 존재하지 않는 S3 버킷

-------------------------------------------------------------------------------------|
|                                       error                                        |
+---------------------------+---------------+----------------------------------------+
|        BucketName         |     Code      |                Message                 |
+---------------------------+---------------+----------------------------------------+
|  amzn-s3-demo-bucket      |  NoSuchBucket |  The specified bucket does not exist   |
+---------------------------+---------------+----------------------------------------+

레거시 형식

레거시 형식은 구조화된 세부 정보 없이 원래 오류 형식을 제공합니다. 이 형식에는 CLI 예외에 대한 "오류 발생(ErrorCode):" 접두사가 포함되지 않습니다.

예: 리전 구성 누락

aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".

예: 존재하지 않는 S3 버킷

An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
참고

이제 오류에 CLI 예외의 aws: [ERROR]: 접두사가 일관되게 포함됩니다. 이전 버전에서는 경우에 따라 이 접두사가 포함되지 않았습니다.

다음 예외는 구성된 오류 형식에 관계없이 항상 레거시 형식을 사용합니다.

  • UnknownArgumentError - 사용 정보를 표시합니다.

  • 키보드 인터럽트(KeyboardInterrupt)

전체 예제

다음 예제에서는 JSON 오류 형식을 사용한 명령을 보여줍니다.

$ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt \
    --cli-error-format json

출력(stderr):

{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}

BucketName 필드는 Amazon S3 서비스에서 반환하는 모델링된 오류 멤버입니다.