software.amazon.awscdk.services.lambda.destinations.package-info Maven / Gradle / Ivy
Show all versions of lambda-destinations Show documentation
/**
* Amazon Lambda Destinations Library
*
* ---
*
* 
*
*
*
*
*
* This library provides constructs for adding destinations to a Lambda function.
* Destinations can be added by specifying the onFailure or onSuccess props when creating a function or alias.
*
*
Destinations
*
* The following destinations are supported
*
*
* - Lambda function
* - SQS queue - Only standard SQS queues are supported for failure destinations, FIFO queues are not supported.
* - SNS topic
* - EventBridge event bus
*
*
* Example with a SNS topic for successful invocations:
*
*
* // An sns topic for successful invocations of a lambda function
* import software.amazon.awscdk.services.sns.*;
*
*
* Topic myTopic = new Topic(this, "Topic");
*
* Function myFn = Function.Builder.create(this, "Fn")
* .runtime(Runtime.NODEJS_14_X)
* .handler("index.handler")
* .code(Code.fromAsset(join(__dirname, "lambda-handler")))
* // sns topic for successful invocations
* .onSuccess(new SnsDestination(myTopic))
* .build();
*
*
* Example with a SQS queue for unsuccessful invocations:
*
*
* // An sqs queue for unsuccessful invocations of a lambda function
* import software.amazon.awscdk.services.sqs.*;
*
*
* Queue deadLetterQueue = new Queue(this, "DeadLetterQueue");
*
* Function myFn = Function.Builder.create(this, "Fn")
* .runtime(Runtime.NODEJS_14_X)
* .handler("index.handler")
* .code(Code.fromInline("// your code"))
* // sqs queue for unsuccessful invocations
* .onFailure(new SqsDestination(deadLetterQueue))
* .build();
*
*
* See also Configuring Destinations for Asynchronous Invocation.
*
*
Invocation record
*
* When a lambda function is configured with a destination, an invocation record is created by the Lambda service
* when the lambda function completes. The invocation record contains the details of the function, its context, and
* the request and response payloads.
*
* The following example shows the format of the invocation record for a successful invocation:
*
*
* {
* "version": "1.0",
* "timestamp": "2019-11-24T23:08:25.651Z",
* "requestContext": {
* "requestId": "c2a6f2ae-7dbb-4d22-8782-d0485c9877e2",
* "functionArn": "arn:aws:lambda:sa-east-1:123456789123:function:event-destinations:$LATEST",
* "condition": "Success",
* "approximateInvokeCount": 1
* },
* "requestPayload": {
* "Success": true
* },
* "responseContext": {
* "statusCode": 200,
* "executedVersion": "$LATEST"
* },
* "responsePayload": "<data returned by the function here>"
* }
*
*
* In case of failure, the record contains the reason and error object:
*
*
* {
* "version": "1.0",
* "timestamp": "2019-11-24T21:52:47.333Z",
* "requestContext": {
* "requestId": "8ea123e4-1db7-4aca-ad10-d9ca1234c1fd",
* "functionArn": "arn:aws:lambda:sa-east-1:123456678912:function:event-destinations:$LATEST",
* "condition": "RetriesExhausted",
* "approximateInvokeCount": 3
* },
* "requestPayload": {
* "Success": false
* },
* "responseContext": {
* "statusCode": 200,
* "executedVersion": "$LATEST",
* "functionError": "Handled"
* },
* "responsePayload": {
* "errorMessage": "Failure from event, Success = false, I am failing!",
* "errorType": "Error",
* "stackTrace": [ "exports.handler (/var/task/index.js:18:18)" ]
* }
* }
*
*
*
Destination-specific JSON format
*
*
* - For SNS/SQS (
SnsDestionation/SqsDestination), the invocation record JSON is passed as the Message to the destination.
* - For Lambda (
LambdaDestination), the invocation record JSON is passed as the payload to the function.
* - For EventBridge (
EventBridgeDestination), the invocation record JSON is passed as the detail in the PutEvents call.
* The value for the event field source is lambda, and the value for the event field detail-type
* is either 'Lambda Function Invocation Result - Success' or 'Lambda Function Invocation Result – Failure',
* depending on whether the lambda function invocation succeeded or failed. The event field resource
* contains the function and destination ARNs. See AWS Events
* for the different event fields.
*
*
*
Auto-extract response payload with lambda destination
*
* The responseOnly option of LambdaDestination allows to auto-extract the response payload from the
* invocation record:
*
*
* // Auto-extract response payload with a lambda destination
* Function destinationFn;
*
*
* Function sourceFn = Function.Builder.create(this, "Source")
* .runtime(Runtime.NODEJS_14_X)
* .handler("index.handler")
* .code(Code.fromAsset(join(__dirname, "lambda-handler")))
* // auto-extract on success
* .onSuccess(LambdaDestination.Builder.create(destinationFn)
* .responseOnly(true)
* .build())
* .build();
*
*
* In the above example, destinationFn will be invoked with the payload returned by sourceFn
* (responsePayload in the invocation record, not the full record).
*
* When used with onFailure, the destination function is invoked with the error object returned
* by the source function.
*
* Using the responseOnly option allows to easily chain asynchronous Lambda functions without
* having to deal with data extraction in the runtime code.
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable)
package software.amazon.awscdk.services.lambda.destinations;