AWS CLI の構造化エラー出力

このトピックでは、AWS Command Line Interface (AWS CLI) の構造化エラー出力の形式について説明します。CLI は stderr にエラーを書き込み、次の形式をサポートします。

エラー形式の設定

エラー形式は、次のいずれかの方法を使用して設定できます。

エラー出力形式

以降のセクションでは、各型式について説明します。

拡張形式 (デフォルト)

拡張形式では、エラーメッセージとシンプルな値の追加の詳細がインラインで表示されます。複雑な構造の場合、形式は 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

完全な例

次の例は、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 サービスのエラーシェイプで定義され、モデル化されたエラーメンバーです。構造化エラー出力には、サービスのエラーモデルで定義されたフィールドのみが含まれます。