awslambdadestinations

package
v2.188.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 4, 2025 License: Apache-2.0 Imports: 11 Imported by: 0

README

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
  • S3 bucket

Example with a SNS topic for successful invocations:

// An sns topic for successful invocations of a lambda function
import sns "github.com/aws/aws-cdk-go/awscdk"


myTopic := sns.NewTopic(this, jsii.String("Topic"))

myFn := lambda.NewFunction(this, jsii.String("Fn"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_LATEST(),
	Handler: jsii.String("index.handler"),
	Code: lambda.Code_FromAsset(path.join(__dirname, jsii.String("lambda-handler"))),
	// sns topic for successful invocations
	OnSuccess: destinations.NewSnsDestination(myTopic),
})

Example with a SQS queue for unsuccessful invocations:

// An sqs queue for unsuccessful invocations of a lambda function
import sqs "github.com/aws/aws-cdk-go/awscdk"


deadLetterQueue := sqs.NewQueue(this, jsii.String("DeadLetterQueue"))

myFn := lambda.NewFunction(this, jsii.String("Fn"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_LATEST(),
	Handler: jsii.String("index.handler"),
	Code: lambda.Code_FromInline(jsii.String("// your code")),
	// sqs queue for unsuccessful invocations
	OnFailure: destinations.NewSqsDestination(deadLetterQueue),
})

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.
  • For S3 (S3Destination), the invocation record json is stored as a File in the destination bucket. The path of a destination payload file in the configured bucket is aws/lambda/async/<function-name>/YYYY/MM/DD/YYYY-MM-DDTHH.MM.SS-<Random UUID>.
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
var destinationFn function


sourceFn := lambda.NewFunction(this, jsii.String("Source"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_LATEST(),
	Handler: jsii.String("index.handler"),
	Code: lambda.Code_FromAsset(path.join(__dirname, jsii.String("lambda-handler"))),
	// auto-extract on success
	OnSuccess: destinations.NewLambdaDestination(destinationFn, &LambdaDestinationOptions{
		ResponseOnly: jsii.Boolean(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.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewEventBridgeDestination_Override 

func NewEventBridgeDestination_Override(e EventBridgeDestination, eventBus awsevents.IEventBus)

Default: - use the default event bus.

func NewLambdaDestination_Override 

func NewLambdaDestination_Override(l LambdaDestination, fn awslambda.IFunction, options *LambdaDestinationOptions)

func NewS3Destination_Override added in v2.168.0 

func NewS3Destination_Override(s S3Destination, bucket awss3.IBucket)

func NewSnsDestination_Override 

func NewSnsDestination_Override(s SnsDestination, topic awssns.ITopic)

func NewSqsDestination_Override 

func NewSqsDestination_Override(s SqsDestination, queue awssqs.IQueue)

Types

type EventBridgeDestination 

type EventBridgeDestination interface {
	awslambda.IDestination
	// Returns a destination configuration.
	Bind(_scope constructs.Construct, fn awslambda.IFunction, _options *awslambda.DestinationOptions) *awslambda.DestinationConfig
}

Use an Event Bridge event bus as a Lambda destination.

If no event bus is specified, the default event bus is used.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"

var eventBus eventBus

eventBridgeDestination := awscdk.Aws_lambda_destinations.NewEventBridgeDestination(eventBus)

func NewEventBridgeDestination 

func NewEventBridgeDestination(eventBus awsevents.IEventBus) EventBridgeDestination

Default: - use the default event bus.

type LambdaDestination 

type LambdaDestination interface {
	awslambda.IDestination
	// Returns a destination configuration.
	Bind(scope constructs.Construct, fn awslambda.IFunction, options *awslambda.DestinationOptions) *awslambda.DestinationConfig
}

Use a Lambda function as a Lambda destination.

Example: 

// Auto-extract response payload with a lambda destination
var destinationFn function

sourceFn := lambda.NewFunction(this, jsii.String("Source"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_LATEST(),
	Handler: jsii.String("index.handler"),
	Code: lambda.Code_FromAsset(path.join(__dirname, jsii.String("lambda-handler"))),
	// auto-extract on success
	OnSuccess: destinations.NewLambdaDestination(destinationFn, &LambdaDestinationOptions{
		ResponseOnly: jsii.Boolean(true),
	}),
})

func NewLambdaDestination 

func NewLambdaDestination(fn awslambda.IFunction, options *LambdaDestinationOptions) LambdaDestination

type LambdaDestinationOptions 

type LambdaDestinationOptions struct {
	// Whether the destination function receives only the `responsePayload` of the source function.
	//
	// When set to `true` and used as `onSuccess` destination, the destination
	// function will be invoked with the payload returned by the source function.
	//
	// When set to `true` and used as `onFailure` destination, the destination
	// function will be invoked with the error object returned by source function.
	//
	// See the README of this module to see a full explanation of this option.
	// Default: false The destination function receives the full invocation record.
	//
	ResponseOnly *bool `field:"optional" json:"responseOnly" yaml:"responseOnly"`
}

Options for a Lambda destination.

Example: 

// Auto-extract response payload with a lambda destination
var destinationFn function

sourceFn := lambda.NewFunction(this, jsii.String("Source"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_LATEST(),
	Handler: jsii.String("index.handler"),
	Code: lambda.Code_FromAsset(path.join(__dirname, jsii.String("lambda-handler"))),
	// auto-extract on success
	OnSuccess: destinations.NewLambdaDestination(destinationFn, &LambdaDestinationOptions{
		ResponseOnly: jsii.Boolean(true),
	}),
})

type S3Destination added in v2.168.0 

type S3Destination interface {
	awslambda.IDestination
	// Returns a destination configuration.
	Bind(_scope constructs.Construct, fn awslambda.IFunction, _options *awslambda.DestinationOptions) *awslambda.DestinationConfig
}

Use a S3 bucket as a Lambda destination.

Example: 

// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"

var bucket bucket

s3Destination := awscdk.Aws_lambda_destinations.NewS3Destination(bucket)

func NewS3Destination added in v2.168.0 

func NewS3Destination(bucket awss3.IBucket) S3Destination

type SnsDestination 

type SnsDestination interface {
	awslambda.IDestination
	// Returns a destination configuration.
	Bind(_scope constructs.Construct, fn awslambda.IFunction, _options *awslambda.DestinationOptions) *awslambda.DestinationConfig
}

Use a SNS topic as a Lambda destination.

Example: 

// An sns topic for successful invocations of a lambda function
import sns "github.com/aws/aws-cdk-go/awscdk"

myTopic := sns.NewTopic(this, jsii.String("Topic"))

myFn := lambda.NewFunction(this, jsii.String("Fn"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_LATEST(),
	Handler: jsii.String("index.handler"),
	Code: lambda.Code_FromAsset(path.join(__dirname, jsii.String("lambda-handler"))),
	// sns topic for successful invocations
	OnSuccess: destinations.NewSnsDestination(myTopic),
})

func NewSnsDestination 

func NewSnsDestination(topic awssns.ITopic) SnsDestination

type SqsDestination 

type SqsDestination interface {
	awslambda.IDestination
	// Returns a destination configuration.
	Bind(_scope constructs.Construct, fn awslambda.IFunction, _options *awslambda.DestinationOptions) *awslambda.DestinationConfig
}

Use a SQS queue as a Lambda destination.

Example: 

// An sqs queue for unsuccessful invocations of a lambda function
import sqs "github.com/aws/aws-cdk-go/awscdk"

deadLetterQueue := sqs.NewQueue(this, jsii.String("DeadLetterQueue"))

myFn := lambda.NewFunction(this, jsii.String("Fn"), &FunctionProps{
	Runtime: lambda.Runtime_NODEJS_LATEST(),
	Handler: jsii.String("index.handler"),
	Code: lambda.Code_FromInline(jsii.String("// your code")),
	// sqs queue for unsuccessful invocations
	OnFailure: destinations.NewSqsDestination(deadLetterQueue),
})

func NewSqsDestination 

func NewSqsDestination(queue awssqs.IQueue) SqsDestination

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.