This documentation is for the developer preview release of the AWS CDK. Do not use this version of the AWS CDK in production. Subsequent releases of the AWS CDK will likely include breaking changes.

@aws-cdk/aws-lambda-event-sources

AWS Lambda Event Sources

This module includes classes that allow using various AWS services as event sources for AWS Lambda via the high-level lambda.addEventSource(source) API.

NOTE: In most cases, it is also possible to use the resource APIs to invoke an AWS Lambda function. This library provides a uniform API for all Lambda event sources regardless of the underlying mechanism they use.

SQS

Amazon Simple Queue Service (Amazon SQS) allows you to build asynchronous workflows. For more information about Amazon SQS, see Amazon Simple Queue Service. You can configure AWS Lambda to poll for these messages as they arrive and then pass the event to a Lambda function invocation. To view a sample event, see Amazon SQS Event.

To set up Amazon Simple Queue Service as an event source for AWS Lambda, you first create or update an Amazon SQS queue and select custom values for the queue parameters. The following parameters will impact Amazon SQS’s polling behavior:

  • visibilityTimeoutSec: May impact the period between retries.
  • receiveMessageWaitTimeSec: Will determine long poll duration. The default value is 20 seconds.
import { SqsEventSource } from '@aws-cdk/aws-lambda-event-sources';

const queue = new sqs.Queue(this, 'MyQueue', {
  visibilityTimeoutSec: 30      // default,
  receiveMessageWaitTimeSec: 20 // default
});

lambda.addEventSource(new SqsEventSource(queue, {
  batchSize: 10 // default
});

S3

You can write Lambda functions to process S3 bucket events, such as the object-created or object-deleted events. For example, when a user uploads a photo to a bucket, you might want Amazon S3 to invoke your Lambda function so that it reads the image and creates a thumbnail for the photo.

You can use the bucket notification configuration feature in Amazon S3 to configure the event source mapping, identifying the bucket events that you want Amazon S3 to publish and which Lambda function to invoke.

import { S3EventSource } from '@aws-cdk/aws-lambda-event-sources';

const bucket = new s3.Bucket(...);

lambda.addEventSource(new S3EventSource(bucket, {
  events: [ s3.EventType.ObjectCreated, s3.EventType.ObjectDeleted ],
  filters: [ { prefix: 'subdir/' } ] // optional
}));

SNS

You can write Lambda functions to process Amazon Simple Notification Service notifications. When a message is published to an Amazon SNS topic, the service can invoke your Lambda function by passing the message payload as a parameter. Your Lambda function code can then process the event, for example publish the message to other Amazon SNS topics, or send the message to other AWS services.

This also enables you to trigger a Lambda function in response to Amazon CloudWatch alarms and other AWS services that use Amazon SNS.

For an example event, see Appendix: Message and JSON Formats and Amazon SNS Sample Event. For an example use case, see Using AWS Lambda with Amazon SNS from Different Accounts.

import { SnsEventSource } from '@aws-cdk/aws-lambda-event-sources';

const topic = new sns.Topic(...);

lambda.addEventSource(new SnsEventSource(topic));

When a user calls the SNS Publish API on a topic that your Lambda function is subscribed to, Amazon SNS will call Lambda to invoke your function asynchronously. Lambda will then return a delivery status. If there was an error calling Lambda, Amazon SNS will retry invoking the Lambda function up to three times. After three tries, if Amazon SNS still could not successfully invoke the Lambda function, then Amazon SNS will send a delivery status failure message to CloudWatch.

DynamoDB Streams

You can write Lambda functions to process change events from a DynamoDB Table. An event is emitted to a DynamoDB stream (if configured) whenever a write (Put, Delete, Update) operation is performed against the table. See Using AWS Lambda with Amazon DynamoDB for more information.

To process events with a Lambda function, first create or update a DynamoDB table and enable a streamSpecification configuration. Then, create a DynamoEventSource and add it to your Lambda function. The following parameters will impact Amazon DynamoDB’s polling behavior:

  • batchSize: Determines how many records are buffered before invoking your lambnda function - could impact your function’s memory usage (if too high) and ability to keep up with incoming data velocity (if too low).
  • startingPosition: Will determine where to being consumption, either at the most recent (‘LATEST’) record or the oldest record (‘TRIM_HORIZON’). ‘TRIM_HORIZON’ will ensure you process all available data, while ‘LATEST’ will ignore all reocrds that arrived prior to attaching the event source.
import dynamodb = require('@aws-cdk/aws-dynamodb');
import lambda = require('@aws-cdk/aws-lambda');
import { DynamoEventSource } from '@aws-cdk/aws-lambda-event-sources';

const table = new dynamodb.Table(..., {
  partitionKey: ...,
  streamSpecification: dynamodb.StreamViewType.NewImage // make sure stream is configured
});

const function = new lambda.Function(...);
function.addEventSource(new DynamoEventSource(table, {
  startingPosition: lambda.StartingPosition.TrimHorizon
}));

Kinesis

You can write Lambda functions to process streaming data in Amazon Kinesis Streams. For more information about Amazon SQS, see Amazon Kinesis Service. To view a sample event, see Amazon SQS Event.

To set up Amazon Kinesis as an event source for AWS Lambda, you first create or update an Amazon Kinesis stream and select custom values for the event source parameters. The following parameters will impact Amazon Kinesis’s polling behavior:

  • batchSize: Determines how many records are buffered before invoking your lambnda function - could impact your function’s memory usage (if too high) and ability to keep up with incoming data velocity (if too low).
  • startingPosition: Will determine where to being consumption, either at the most recent (‘LATEST’) record or the oldest record (‘TRIM_HORIZON’). ‘TRIM_HORIZON’ will ensure you process all available data, while ‘LATEST’ will ignore all reocrds that arrived prior to attaching the event source.
import lambda = require('@aws-cdk/aws-lambda');
import kinesis = require('@aws-cdk/aws-kinesis');
import { KinesisEventSource } from '@aws-cdk/aws-lambda-event-sources';

const stream = new kinesis.Stream(this, 'MyStream');

myFunction.addEventSource(new KinesisEventSource(queue, {
  batchSize: 100, // default
  startingPosition: lambda.StartingPosition.TrimHorizon
});

Roadmap

Eventually, this module will support all the event sources described under Supported Event Sources in the AWS Lambda Developer Guide.

Reference

View in Nuget

csproj:

<PackageReference Include="Amazon.CDK.AWS.Lambda.EventSources" Version="0.25.3" />

dotnet:

dotnet add package Amazon.CDK.AWS.Lambda.EventSources --version 0.25.3

packages.config:

<package id="Amazon.CDK.AWS.Lambda.EventSources" version="0.25.3" />

View in Maven Central

Apache Buildr:

'software.amazon.awscdk:lambda-event-sources:jar:0.25.3'

Apache Ivy:

<dependency groupId="software.amazon.awscdk" name="lambda-event-sources" rev="0.25.3"/>

Apache Maven:

<dependency>
  <groupId>software.amazon.awscdk</groupId>
  <artifactId>lambda-event-sources</artifactId>
  <version>0.25.3</version>
</dependency>

Gradle / Grails:

compile 'software.amazon.awscdk:lambda-event-sources:0.25.3'

Groovy Grape:

@Grapes(
@Grab(group='software.amazon.awscdk', module='lambda-event-sources', version='0.25.3')
)

View in NPM

npm:

$ npm i @aws-cdk/aws-lambda-event-sources@0.25.3

package.json:

{
  "@aws-cdk/aws-lambda-event-sources": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/aws-lambda-event-sources@0.25.3

View in NPM

npm:

$ npm i @aws-cdk/aws-lambda-event-sources@0.25.3

package.json:

{
  "@aws-cdk/aws-lambda-event-sources": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/aws-lambda-event-sources@0.25.3

ApiEventSource

class @aws-cdk/aws-lambda-event-sources.ApiEventSource(method, path[, options])

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.ApiEventSource;
const { ApiEventSource } = require('@aws-cdk/aws-lambda-event-sources');
import { ApiEventSource } from '@aws-cdk/aws-lambda-event-sources';
Implements:

@aws-cdk/aws-lambda.IEventSource

Parameters:
bind(target)

Implements @aws-cdk/aws-lambda.IEventSource.bind()

Called by lambda.addEventSource to allow the event source to bind to this

function.

Parameters:target (@aws-cdk/aws-lambda.FunctionBase) –
method
Type:string (readonly)
path
Type:string (readonly)
options
Type:@aws-cdk/aws-apigateway.MethodOptions (optional) (readonly)

DynamoEventSource

class @aws-cdk/aws-lambda-event-sources.DynamoEventSource(table, props)

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.DynamoEventSource;
const { DynamoEventSource } = require('@aws-cdk/aws-lambda-event-sources');
import { DynamoEventSource } from '@aws-cdk/aws-lambda-event-sources';

Use an Amazon DynamoDB stream as an event source for AWS Lambda.

Implements:

@aws-cdk/aws-lambda.IEventSource

Parameters:
bind(target)

Implements @aws-cdk/aws-lambda.IEventSource.bind()

Called by lambda.addEventSource to allow the event source to bind to this

function.

Parameters:target (@aws-cdk/aws-lambda.FunctionBase) –
props
Type:DynamoEventSourceProps (readonly)
table
Type:@aws-cdk/aws-dynamodb.Table (readonly)

DynamoEventSourceProps (interface)

class @aws-cdk/aws-lambda-event-sources.DynamoEventSourceProps

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.DynamoEventSourceProps;
// DynamoEventSourceProps is an interface
import { DynamoEventSourceProps } from '@aws-cdk/aws-lambda-event-sources';
startingPosition

Where to begin consuming the DynamoDB stream.

Type:@aws-cdk/aws-lambda.StartingPosition
batchSize

The largest number of records that AWS Lambda will retrieve from your event

source at the time of invoking your function. Your function receives an

event with all the retrieved records.

Valid Range: Minimum value of 1. Maximum value of 1000.

Type:number (optional)
Default:100

KinesisEventSource

class @aws-cdk/aws-lambda-event-sources.KinesisEventSource(stream, props)

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.KinesisEventSource;
const { KinesisEventSource } = require('@aws-cdk/aws-lambda-event-sources');
import { KinesisEventSource } from '@aws-cdk/aws-lambda-event-sources';

Use an Amazon Kinesis stream as an event source for AWS Lambda.

Implements:

@aws-cdk/aws-lambda.IEventSource

Parameters:
bind(target)

Implements @aws-cdk/aws-lambda.IEventSource.bind()

Called by lambda.addEventSource to allow the event source to bind to this

function.

Parameters:target (@aws-cdk/aws-lambda.FunctionBase) –
props
Type:KinesisEventSourceProps (readonly)
stream
Type:@aws-cdk/aws-kinesis.IStream (readonly)

KinesisEventSourceProps (interface)

class @aws-cdk/aws-lambda-event-sources.KinesisEventSourceProps

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.KinesisEventSourceProps;
// KinesisEventSourceProps is an interface
import { KinesisEventSourceProps } from '@aws-cdk/aws-lambda-event-sources';
startingPosition

Where to begin consuming the Kinesis stream.

Type:@aws-cdk/aws-lambda.StartingPosition
batchSize

The largest number of records that AWS Lambda will retrieve from your event

source at the time of invoking your function. Your function receives an

event with all the retrieved records.

Valid Range: Minimum value of 1. Maximum value of 10000.

Type:number (optional)
Default:100

S3EventSource

class @aws-cdk/aws-lambda-event-sources.S3EventSource(bucket, props)

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.S3EventSource;
const { S3EventSource } = require('@aws-cdk/aws-lambda-event-sources');
import { S3EventSource } from '@aws-cdk/aws-lambda-event-sources';

Use S3 bucket notifications as an event source for AWS Lambda.

Implements:

@aws-cdk/aws-lambda.IEventSource

Parameters:
bind(target)

Implements @aws-cdk/aws-lambda.IEventSource.bind()

Called by lambda.addEventSource to allow the event source to bind to this

function.

Parameters:target (@aws-cdk/aws-lambda.FunctionBase) –
bucket
Type:@aws-cdk/aws-s3.Bucket (readonly)
props
Type:S3EventSourceProps (readonly)

S3EventSourceProps (interface)

class @aws-cdk/aws-lambda-event-sources.S3EventSourceProps

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.S3EventSourceProps;
// S3EventSourceProps is an interface
import { S3EventSourceProps } from '@aws-cdk/aws-lambda-event-sources';
events

The s3 event types that will trigger the notification.

Type:@aws-cdk/aws-s3.EventType[]
filters

S3 object key filter rules to determine which objects trigger this event.

Each filter must include a prefix and/or suffix that will be matched

against the s3 object key. Refer to the S3 Developer Guide for details

about allowed filter rules.

Type:@aws-cdk/aws-s3.NotificationKeyFilter[] (optional)

SnsEventSource

class @aws-cdk/aws-lambda-event-sources.SnsEventSource(topic)

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.SnsEventSource;
const { SnsEventSource } = require('@aws-cdk/aws-lambda-event-sources');
import { SnsEventSource } from '@aws-cdk/aws-lambda-event-sources';

Use an Amazon SNS topic as an event source for AWS Lambda.

Implements:@aws-cdk/aws-lambda.IEventSource
Parameters:topic (@aws-cdk/aws-sns.ITopic) –
bind(target)

Implements @aws-cdk/aws-lambda.IEventSource.bind()

Called by lambda.addEventSource to allow the event source to bind to this

function.

Parameters:target (@aws-cdk/aws-lambda.FunctionBase) –
topic
Type:@aws-cdk/aws-sns.ITopic (readonly)

SqsEventSource

class @aws-cdk/aws-lambda-event-sources.SqsEventSource(queue[, props])

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.SqsEventSource;
const { SqsEventSource } = require('@aws-cdk/aws-lambda-event-sources');
import { SqsEventSource } from '@aws-cdk/aws-lambda-event-sources';

Use an Amazon SQS queue as an event source for AWS Lambda.

Implements:

@aws-cdk/aws-lambda.IEventSource

Parameters:
bind(target)

Implements @aws-cdk/aws-lambda.IEventSource.bind()

Called by lambda.addEventSource to allow the event source to bind to this

function.

Parameters:target (@aws-cdk/aws-lambda.FunctionBase) –
props
Type:SqsEventSourceProps (readonly)
queue
Type:@aws-cdk/aws-sqs.IQueue (readonly)

SqsEventSourceProps (interface)

class @aws-cdk/aws-lambda-event-sources.SqsEventSourceProps

Language-specific names:

using Amazon.CDK.AWS.Lambda.EventSources;
import software.amazon.awscdk.services.lambda.eventsources.SqsEventSourceProps;
// SqsEventSourceProps is an interface
import { SqsEventSourceProps } from '@aws-cdk/aws-lambda-event-sources';
batchSize

The largest number of records that AWS Lambda will retrieve from your event

source at the time of invoking your function. Your function receives an

event with all the retrieved records.

Valid Range: Minimum value of 1. Maximum value of 10.

Type:number (optional)
Default:10