Lambda 非同期呼び出しのレコードのキャプチャ

Lambda 関数は、非同期呼び出しのレコードを以下のいずれかの AWS のサービスに送信できます。

Amazon SQS — 標準の SQS キュー。
Amazon SNS – 標準 SNS トピック。
AWS Lambda — Lambda 関数。
Amazon EventBridge － Amazon EventBridge イベントバス。

呼び出しレコードには、JSON 形式のリクエストとレスポンスに関する詳細が含まれます。処理に成功したイベント用とすべての処理試行に失敗したイベント用に別々の送信先を設定できます。または、破棄されたイベント用に標準 Amazon SQS キューまたは標準 Amazon SNS トピックをデッドレターキューとして設定することもできます。デッドレターキューの場合、Lambda はイベントのコンテンツのみを送信し、レスポンスの詳細は送信しません。

設定した送信先に Lambda がレコードを送信できない場合、Lambda は Amazon CloudWatch に DestinationDeliveryFailures メトリクスを送信します。これは、設定に Amazon SQS FIFO キューや Amazon SNS FIFO トピックなど、サポートされていない送信先タイプが含まれている場合に発生する可能性があります。また、配信エラーはアクセス許可エラーが原因で発生する可能性があります。Lambda 呼び出しメトリクスの詳細については、「呼び出しメトリクス」を参照してください。

注記

関数がトリガーされないようにするには、その関数の予約済同時実行数をゼロに設定します。非同期で呼び出された関数の予約された同時実行数をゼロに設定すると、Lambda は設定したデッドレターキューまたは障害発生時のイベント送信先に再試行なしで新しいイベントの送信を開始します。予約された同時実行数をゼロに設定している間に送信されたイベントを処理するには、デッドレターキューまたは障害発生時のイベント送信先からイベントを消費する必要があります。

非同期呼び出しの送信先の設定

非同期呼び出しのレコードを保持するには、関数に送信先を追加します。成功した呼び出しと失敗した呼び出しのいずれかを送信先に送るように選択できます。各関数に複数の送信先を設定できるため、成功したイベントと失敗したイベントの送信先を別々に設定できます。送信先に送られる各レコードは、呼び出しに関する詳細を含む JSON ドキュメントです。エラー処理の設定と同様に、関数、関数のバージョン、またはエイリアスに対して送信先を設定できます。

注記

また、Amazon Kinesis、Amazon DynamoDB、セルフマネージド Apache Kafka、および Amazon MSK の各タイプのイベントソースマッピングについて、失敗した呼び出しのレコードを保持することもできます。

以下の表は、非同期呼び出しレコードでサポートされている送信先の一覧です。Lambda が選択した送信先にレコードを正常に送信するには、関数の実行ロールにも関連するアクセス権限が含まれていることを確認してください。この表では、各送信先タイプで JSON 呼び出しレコードを受け取る方法についても説明しています。

送信先タイプ	必要なアクセス許可	宛先固有の JSON 形式
Amazon SQS キュー	sqs:SendMessage	Lambda は呼び出しレコードを `Message` として宛先に渡します。
Amazon SNS トピック	sns:Publish	Lambda は呼び出しレコードを `Message` として宛先に渡します。
Lambda 関数	InvokeFunction	Lambda は呼び出しレコードをペイロードとして関数に渡します。
EventBridge	events:PutEvents	Lambda は呼び出しレコードを PutEvents 呼び出しの `detail` として渡します。「`source`」イベントフィールドの値は「`lambda`」です。 `detail-type` イベントフィールドの値は、「Lambda 関数の呼び出し結果 - 成功」または「Lambda 関数の呼び出し結果 - 失敗」のいずれかです。「`resource`」イベントフィールドには、関数と宛先の Amazon リソースネーム (ARN) が含まれます。他のイベントフィールドについては、Amazon EventBridge イベントを参照してください。

次の例は、関数エラーが原因で 3 つの処理試行に失敗したイベントの呼び出しレコードを示しています。呼び出しレコードには、イベント、レスポンス、レコードが送信された理由に関する詳細が含まれます。


{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

次のステップでは、Lambda コンソールを使用して関数の送信先を設定する方法について説明します。

非同期呼び出しレコードの送信先の設定

Lambda コンソールの [関数ページ] を開きます。
関数を選択します。
[機能の概要 ] で、[送信先を追加 ] を選択します。
[Source (送信元)] で、[Asynchronous invocation (非同期呼び出し)] を選択します。
[条件] で、以下のオプションから選択します。
- [On failure] (失敗時) －イベントがすべての処理試行に失敗した場合、または最大有効期間を超えた場合に、レコードを送信します。
- [On success] (正常) －関数が非同期呼び出しを正常に処理したときに、レコードを送信します。
[送信先タイプ] で、呼び出しレコードを受信するリソースのタイプを選択します。
[送信先] で、リソースを選択します。
[Save] を選択します。

呼び出しが条件に一致すると、Lambda は呼び出しに関する詳細を含む JSON ドキュメントを送信先に送ります。

宛先固有の JSON 形式

Amazon SQS と Amazon SNS (「SnsDestination」と「SqsDestination」) の場合、呼び出しレコードは「Message」として送信先に渡されます。
Lambda 「LambdaDestination」の場合、呼び出しレコードはペイロードとして関数に渡されます。
EventBridge 「EventBridgeDestination」の場合、呼び出しレコードは PutEvents の呼び出しで「detail」として渡されます。「source」イベントフィールドの値は「lambda」です。「detail-type」イベントフィールドの値は、Lambda 関数の呼び出し結果 - 成功または Lambda 関数の呼び出し結果 - 失敗のいずれかです。「resource」イベントフィールドには、関数と宛先の Amazon リソースネーム (ARN) が含まれます。他のイベントフィールドについては、Amazon EventBridge イベントを参照してください。

次の例は、関数エラーが原因で 3 つの処理試行に失敗したイベントの呼び出しレコードを示しています。

例呼び出しレコード


{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

呼び出しレコードには、イベント、レスポンス、レコードが送信された理由に関する詳細が含まれます。

送信先へのリクエストのトレース

AWS X-Ray を使用すると、各リクエストがキューに入れられ、Lambda 関数によって処理され、送信先サービスに渡される過程の接続されたビューを確認できます。関数または関数を呼び出すサービスの X-Ray トレーシングを有効にすると、Lambda は X-Ray ヘッダーをリクエストに追加し、ヘッダーを送信先サービスに渡します。アップストリームサービスからのトレースは、ダウンストリーム Lambda 関数および宛先サービスからのトレースに自動的にリンクされ、アプリケーション全体のエンドツーエンドビューを作成します。トレースの詳細については、「AWS X-Ray を使用した Lambda 関数呼び出しの視覚化」を参照してください。

デッドレターキュー

障害発生時の送信先に代わる方法として、配信不能キューを使用して関数を設定し、破棄されたイベントを保存してさらに処理できます。配信不能キューは、イベントがすべての処理試行に失敗した場合や処理されずに期限切れになった場合に使用されるという点で、障害発生時の送信先と同じように動作します。ただし、配信不能キューは関数のバージョン固有の設定の一部であるため、バージョンを公開するとロックされます。また、障害発生時の送信先は、追加のターゲットをサポートし、関数のレスポンスに関する詳細を呼び出しレコードに含めます。

デッドレターキュー内のイベントを再処理するには、デッドレターキューを Lambda 関数のイベントソースとして設定します。または、イベントを手動で取得することもできます。

デッドレターキューには標準 Amazon SQS キューまたは標準 Amazon SNS トピックを選択できます。FIFO キューと Amazon SNS FIFO トピックはサポートされていません。キューまたはトピックがない場合は、新規に作成します。ユースケースに一致するターゲットタイプを選択します。

Amazon SQS キュー－キューは、失敗したイベントが取得されるまでそれらを保持します。Lambda 関数や CloudWatch アラームなどの単一のエンティティが失敗したイベントを処理することが予想される場合は、Amazon SQS 標準キューを選択します。詳細については、「Amazon SQS での Lambda の使用」を参照してください。

Amazon SQS コンソールで、キューを作成します。
Amazon SNS トピック－トピックは、失敗したイベントを 1 つまたは複数の送信先に中継します。複数のエンティティが失敗したイベントに対して動作することが予想される場合は、Amazon SNS 標準トピックを選択します。例えば、E メールアドレス、Lambda 関数、および/または HTTP エンドポイントにイベントを送信するようにトピックを設定できます。詳細については、Amazon SNS 通知を使用した Lambda 関数の呼び出しを参照してください。

Amazon SNS コンソールでトピックを作成します。

キューまたはトピックにイベントを送信するには、関数に追加のアクセス権限が必要です。関数の実行ロールに必要なアクセス権限と持つポリシーを追加します。

Amazon SQS － sqs:SendMessage
Amazon SNS － sns:Publish

ターゲットキューまたはトピックがカスタマー管理のキーで暗号化されている場合、その実行ロールはキーのリソースベースのポリシーのユーザーでもある必要があります。

ターゲットを作成し、関数の実行ロールを更新した後、デッドレターキューを関数に追加します。同じターゲットにイベントを送信するように複数の関数を設定できます。

デッドレターキューを設定するには

Lambda コンソールの [関数ページ] を開きます。
関数を選択します。
[設定]、[Asynchronous invocation (非同期呼び出し)] の順に選択します。
[Asynchronous invocation (非同期呼び出し)] で、[Edit (編集)] を選択します。
[DLQ resource] (DLQ リソース) を [Amazon SQS] または [Amazon SNS] に設定します。
ターゲットとなるキューまたはトピックを選択します。
[Save] を選択します。

AWS CLI を使用してデッドレターキューを設定するには、update-function-configuration コマンドを使用します。


aws lambda update-function-configuration --function-name my-function \
--dead-letter-config TargetArn=arn:aws:sns:us-east-2:123456789012:my-topic

Lambda は、イベントをそのまま属性の追加情報と共にデッドレターキューに送信します。この情報を使用して、関数が返したエラーを特定するか、イベントをログまたは AWS X-Ray トレースと関連付けることができます。

デッドレターキューメッセージの属性

RequestID (文字列) －呼び出しリクエストの ID。リクエスト ID は関数ログに表示されます。また、X-Ray SDK を使用して、トレース内の属性のリクエスト ID を記録することもできます。その後、X-Ray コンソールで、リクエスト ID によってトレースを検索できます。
ErrorCode (数値) － HTTP ステータスコード。
ErrorMessage (文字列) －エラーメッセージの最初の 1 KB。

Lambda がデッドレターキューにメッセージを送信できない場合、イベントは削除され、DeadLetterErrors メトリクスが発行されます。このような状況は、アクセス権限がない、またはメッセージの合計サイズがターゲットとなるキューやトピックの制限を超えてしまった場合に発生します。例えば、本文のサイズが 256 KB に近い Amazon SNS 通知が、エラーとなる関数をトリガーしたとします。その場合、Amazon SNS によって追加されたイベントデータと Lambda によって追加された属性の組み合わせによって、メッセージがデッドレターキューで許可されている最大サイズを超過することがあります。

Amazon SQS をイベントソースとして使用する場合、Amazon SQS キューでは Lambda 関数ではなくデッドレターキューを設定します。詳細については、「Amazon SQS での Lambda の使用」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

非同期呼び出しの設定

イベント出典マッピング