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

本文档仅适用于 Amazon CLI 版本 1。

我们已宣布即将终止对 Amazon CLI 版本 1 的支持。建议您迁移到 Amazon CLI 版本 2。有关日期、其它详细信息以及如何迁移的信息，请参阅公告。有关 Amazon CLI 版本 2 的相关文档，请参阅版本 2 用户指南。

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

示例：带有其它字段的 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 异常的“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 服务返回的建模错误成员。