View a markdown version of this page

Amazon CLI 中的结构化错误输出 - Amazon Command Line Interface
配置错误格式错误输出格式完整示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

Amazon CLI 中的结构化错误输出

本主题介绍 Amazon Command Line Interface（Amazon CLI）的结构化错误输出格式。CLI 将错误写入到 stderr 并支持以下格式：

  • enhanced（默认）：内联显示带有其它详细信息的错误消息。用于便于阅读的调试。

  • json：输出采用 JSON 字符串的格式并具有所有错误字段。用于自动化和脚本编写。

  • yaml：输出采用 YAML 字符串的格式并具有所有错误字段。用于自动化和脚本编写。

  • 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".

示例：带有其它字段的不存在的 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: <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\"."
}

示例：不存在的 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 服务的错误形状中定义的建模错误成员。只有在服务的错误模型中定义的字段才包含在结构化错误输出中。