software.amazon.awscdk.services.lambda.destinations.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of lambda-destinations Show documentation
CDK Destinations Constructs for AWS Lambda
There is a newer version: 1.204.0
/**
 * 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
 * SNS topic
 * EventBridge event bus
 * 
 * 
 * Example with a SNS topic for successful invocations:
 * 

 * 
 * // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 * import software.amazon.awscdk.services.lambda.*;
 * import software.amazon.awscdk.services.lambda.destinations.*;
 * import software.amazon.awscdk.services.sns.*;
 * 
 * Topic myTopic = new Topic(this, "Topic");
 * 
 * Function myFn = new Function(this, "Fn", new FunctionProps()
 *         // other props
 *         .onSuccess(new SnsDestination(myTopic)));
 * 
 * 
 * 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:
 * 

 * 
 * // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 * import software.amazon.awscdk.services.lambda.*;
 * import software.amazon.awscdk.services.lambda.destinations.*;
 * 
 * Function destinationFn = new Function(this, "Destination", new FunctionProps());
 * 
 * Function sourceFn = new Function(this, "Source", new FunctionProps()
 *         // other props
 *         .onSuccess(new LambdaDestination(destinationFn, new LambdaDestinationOptions()
 *                 .responseOnly(true))));
 * 
 * 
 * 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;