# Amazon CLI 中的结构化错误输出
本主题介绍 Amazon Command Line Interface（Amazon 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".
```
**示例：带有其它字段的不存在的 Lambda 函数**
```
aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the GetFunction operation: Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345
Additional error details:
Type: User
```
“其它错误详细信息”部分仅显示在服务的错误形状模型中定义的字段。不显示错误响应中的未建模字段。
**示例：复杂的错误字段**
```
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\"."
}
```
**示例：不存在的 Lambda 函数**
```
{
"Code": "ResourceNotFoundException",
"Message": "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345",
"Type": "User"
}
```
### YAML 格式
YAML 格式提供包含所有错误字段的结构化表示形式。
**示例：缺少区域配置**
```
Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".
```
**示例：不存在的 Lambda 函数**
```
Code: ResourceNotFoundException
Message: "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345"
Type: User
```
### 文本格式
文本格式使用与成功命令输出相同的格式化程序。
**示例：不存在的 Lambda 函数**
```
ResourceNotFoundException Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 User
```
### 表格式
表格式使用与成功命令输出相同的格式化程序。
**示例：不存在的 Lambda 函数**
```
------------------------------------------------------------------------------------------------------------------------------------|
| error |
+----------------------------+--------------------------------------------------------------------------------------------------+------+
| Code | Message | Type |
+----------------------------+--------------------------------------------------------------------------------------------------+------+
| ResourceNotFoundException | Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 | User |
+----------------------------+--------------------------------------------------------------------------------------------------+------+
```
### 旧版格式
旧版格式提供原始错误格式，而不包含结构化详细信息。此格式不包括 CLI 异常的“An error occurred (ErrorCode)”前缀。
**示例：缺少区域配置**
```
aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".
```
**示例：不存在的 Lambda 函数**
```
An error occurred (ResourceNotFoundException) when calling the GetFunction operation: Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345
```
**注意**
现在，错误始终包含 CLI 异常的 `aws: [ERROR]:` 前缀。早期版本并不总是包含此前缀。
无论所配置的错误格式如何，以下异常都始终使用旧版格式：
`UnknownArgumentError`：显示使用信息。
键盘中断 (`KeyboardInterrupt`)
## 完整示例
以下示例显示采用 JSON 错误格式的命令：
```
$ aws lambda get-function \
--function-name nonexistent-function-12345 \
--cli-error-format json
```
输出 (stderr)：
```
{
"Code": "ResourceNotFoundException",
"Message": "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345",
"Type": "User"
}
```
`Type` 字段是在 Lambda 服务的错误形状中定义的建模错误成员。只有在服务的错误模型中定义的字段才包含在结构化错误输出中。