# AWS CLI의 구조화된 오류 출력
<a name="cli-usage-error-format"></a>

이 주제에서는 AWS Command Line Interface(AWS CLI)의 구조화된 오류 출력 형식에 대해 설명합니다. CLI는 stderr에 오류를 기록하며 다음 형식을 지원합니다.
+ **[`enhanced`](#cli-error-format-enhanced)**(기본값) - 추가 세부 정보가 인라인으로 표시된 오류 메시지입니다. 사람이 읽을 수 있는 디버깅을 위해 사용합니다.
+ **[`json`](#cli-error-format-json)** - 출력은 모든 오류 필드를 포함하며 [JSON](https://json.org/) 문자열 형식입니다. 자동화 및 스크립팅을 위해 사용합니다.
+ **[`yaml`](#cli-error-format-yaml)** - 출력은 모든 오류 필드를 포함하며 [JSON](https://yaml.org/) 문자열입니다. 자동화 및 스크립팅을 위해 사용합니다.
+ **[`text`](#cli-error-format-text)** - 텍스트 포맷터를 사용하여 오류를 표시합니다. 빠른 시각적 검토를 위해 사용합니다.
+ **[`table`](#cli-error-format-table)** - 테이블 포맷터를 사용하여 오류를 표시합니다. 빠른 시각적 검토를 위해 사용합니다.
+ **[`legacy`](#cli-error-format-legacy)** - 구조화된 세부 정보가 없는 원래 오류 형식입니다. 이전 버전과의 호환성을 위해 사용합니다.

## 오류 형식 구성
<a name="cli-error-format-configuring"></a>

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

명령줄 플래그  

```
$ aws <command> --cli-error-format json
```

구성 파일(`~/.aws/config`)  

```
[default]
cli_error_format = json
```

환경 변수  

```
$ export AWS_CLI_ERROR_FORMAT=yaml
```

## 오류 출력 형식
<a name="cli-error-output-formats"></a>

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

### 향상된 형식(기본값)
<a name="cli-error-format-enhanced"></a>

향상된 형식은 단순한 값에 대한 추가 세부 정보를 인라인으로 포함하여 오류 메시지를 표시합니다. 복잡한 구조의 경우 이 형식은 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 형식
<a name="cli-error-format-json"></a>

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 형식
<a name="cli-error-format-yaml"></a>

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

### 날짜 형식
<a name="cli-error-format-text"></a>

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

**예: 존재하지 않는 S3 버킷**

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

### 테이블 형식
<a name="cli-error-format-table"></a>

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

**예: 존재하지 않는 S3 버킷**

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

### 레거시 형식
<a name="cli-error-format-legacy"></a>

레거시 형식은 구조화된 세부 정보 없이 원래 오류 형식을 제공합니다. 이 형식에는 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`)

## 전체 예제
<a name="cli-error-format-example"></a>

다음 예제에서는 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 서비스에서 반환하는 모델링된 오류 멤버입니다.