AWS CLI の構造化エラー出力 - AWS Command Line Interface
エラー形式の設定エラー出力形式完全な例

AWS CLI の構造化エラー出力

このトピックでは、AWS Command Line Interface (AWS 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 サービスによって返されるモデル化されたエラーメンバーです。