# AWS CLI 中的结构化错误输出
本主题介绍 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)**：输出采用 [YAML](https://yaml.org/) 字符串的格式并具有所有错误字段。用于自动化和脚本编写。
+ **[`text`](#cli-error-format-text)**：使用文本格式化程序格式化错误。用于快速可视化扫描。
+ **[`table`](#cli-error-format-table)**：使用表格式化程序格式化错误。用于快速可视化扫描。
+ **[`legacy`](#cli-error-format-legacy)**：没有结构化详细信息的原始错误格式。用于保持向后兼容性。
## 配置错误格式
您可以使用以下任何方法配置错误格式：
命令行标志
```
$ aws --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:
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 异常的“An error occurred (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 服务返回的建模错误成员。