From 5f0c91b90e19cf6f44241a8a97b0fea6a82168a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elias=20Dr=C3=A4xler?= Date: Mon, 6 Jan 2020 18:18:05 +0100 Subject: [PATCH 1/3] feat(lambda-event-sources): add eventSourceMappingId property to EventSourceMapping Exposes the Ref of `AWS::Lambda::EventSourceMapping` as eventSourceMappingId property on the EventSourceMapping and further on the SqsEventSource, KinesisEventSource and DynamoEventSource Closes #5430 --- .../aws-lambda-event-sources/lib/dynamodb.ts | 12 +++++- .../aws-lambda-event-sources/lib/kinesis.ts | 12 +++++- .../aws-lambda-event-sources/lib/sqs.ts | 12 +++++- .../test/test.dynamo.ts | 42 +++++++++++++++++++ .../test/test.kinesis.ts | 30 +++++++++++++ .../aws-lambda-event-sources/test/test.sqs.ts | 26 ++++++++++++ .../aws-lambda/lib/event-source-mapping.ts | 9 +++- 7 files changed, 139 insertions(+), 4 deletions(-) diff --git a/packages/@aws-cdk/aws-lambda-event-sources/lib/dynamodb.ts b/packages/@aws-cdk/aws-lambda-event-sources/lib/dynamodb.ts index 82de57a8c10d6..08aaffa2241ba 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/lib/dynamodb.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/lib/dynamodb.ts @@ -9,6 +9,8 @@ export interface DynamoEventSourceProps extends StreamEventSourceProps { * Use an Amazon DynamoDB stream as an event source for AWS Lambda. */ export class DynamoEventSource extends StreamEventSource { + private _eventSourceMappingId: string | undefined = undefined; + constructor(private readonly table: dynamodb.Table, props: DynamoEventSourceProps) { super(props); @@ -22,10 +24,18 @@ export class DynamoEventSource extends StreamEventSource { throw new Error(`DynamoDB Streams must be enabled on the table ${this.table.node.path}`); } - target.addEventSourceMapping(`DynamoDBEventSource:${this.table.node.uniqueId}`, + const eventSourceMapping = target.addEventSourceMapping(`DynamoDBEventSource:${this.table.node.uniqueId}`, this.enrichMappingOptions({eventSourceArn: this.table.tableStreamArn}) ); + this._eventSourceMappingId = eventSourceMapping.eventSourceMappingId; this.table.grantStreamRead(target); } + + /** + * The Ref of the EventSourceMapping + */ + public get eventSourceMappingId(): string | undefined { + return this._eventSourceMappingId; + } } diff --git a/packages/@aws-cdk/aws-lambda-event-sources/lib/kinesis.ts b/packages/@aws-cdk/aws-lambda-event-sources/lib/kinesis.ts index 78351d428f9d0..dbff3b36ae7bc 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/lib/kinesis.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/lib/kinesis.ts @@ -9,6 +9,8 @@ export interface KinesisEventSourceProps extends StreamEventSourceProps { * Use an Amazon Kinesis stream as an event source for AWS Lambda. */ export class KinesisEventSource extends StreamEventSource { + private _eventSourceMappingId: string | undefined = undefined; + constructor(readonly stream: kinesis.IStream, props: KinesisEventSourceProps) { super(props); @@ -18,10 +20,18 @@ export class KinesisEventSource extends StreamEventSource { } public bind(target: lambda.IFunction) { - target.addEventSourceMapping(`KinesisEventSource:${this.stream.node.uniqueId}`, + const eventSourceMapping = target.addEventSourceMapping(`KinesisEventSource:${this.stream.node.uniqueId}`, this.enrichMappingOptions({eventSourceArn: this.stream.streamArn}) ); + this._eventSourceMappingId = eventSourceMapping.eventSourceMappingId; this.stream.grantRead(target); } + + /** + * The Ref of the EventSourceMapping + */ + public get eventSourceMappingId(): string | undefined { + return this._eventSourceMappingId; + } } diff --git a/packages/@aws-cdk/aws-lambda-event-sources/lib/sqs.ts b/packages/@aws-cdk/aws-lambda-event-sources/lib/sqs.ts index 515659dcecfc2..4fbaa8a0e712e 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/lib/sqs.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/lib/sqs.ts @@ -18,6 +18,8 @@ export interface SqsEventSourceProps { * Use an Amazon SQS queue as an event source for AWS Lambda. */ export class SqsEventSource implements lambda.IEventSource { + private _eventSourceMappingId: string | undefined = undefined; + constructor(readonly queue: sqs.IQueue, private readonly props: SqsEventSourceProps = { }) { if (this.props.batchSize !== undefined && (this.props.batchSize < 1 || this.props.batchSize > 10)) { throw new Error(`Maximum batch size must be between 1 and 10 inclusive (given ${this.props.batchSize})`); @@ -25,11 +27,19 @@ export class SqsEventSource implements lambda.IEventSource { } public bind(target: lambda.IFunction) { - target.addEventSourceMapping(`SqsEventSource:${this.queue.node.uniqueId}`, { + const eventSourceMapping = target.addEventSourceMapping(`SqsEventSource:${this.queue.node.uniqueId}`, { batchSize: this.props.batchSize, eventSourceArn: this.queue.queueArn, }); + this._eventSourceMappingId = eventSourceMapping.eventSourceMappingId; this.queue.grantConsumeMessages(target); } + + /** + * The Ref of the EventSourceMapping + */ + public get eventSourceMappingId(): string | undefined { + return this._eventSourceMappingId; + } } diff --git a/packages/@aws-cdk/aws-lambda-event-sources/test/test.dynamo.ts b/packages/@aws-cdk/aws-lambda-event-sources/test/test.dynamo.ts index 68b12725af0e3..ee26c852ca736 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/test/test.dynamo.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/test/test.dynamo.ts @@ -231,4 +231,46 @@ export = { test.done(); }, + 'contains eventSourceMappingId after lambda binding'(test: Test) { + // GIVEN + const stack = new cdk.Stack(); + const fn = new TestFunction(stack, 'Fn'); + const table = new dynamodb.Table(stack, 'T', { + partitionKey: { + name: 'id', + type: dynamodb.AttributeType.STRING + }, + stream: dynamodb.StreamViewType.NEW_IMAGE + }); + const eventSource = new sources.DynamoEventSource(table, { + startingPosition: lambda.StartingPosition.TRIM_HORIZON + }); + + // WHEN + fn.addEventSource(eventSource); + + // THEN + test.notEqual(eventSource.eventSourceMappingId, undefined); + test.done(); + }, + + 'eventSourceMappingId is undefined before binding to lambda'(test: Test) { + // GIVEN + const stack = new cdk.Stack(); + const table = new dynamodb.Table(stack, 'T', { + partitionKey: { + name: 'id', + type: dynamodb.AttributeType.STRING + }, + stream: dynamodb.StreamViewType.NEW_IMAGE + }); + const eventSource = new sources.DynamoEventSource(table, { + startingPosition: lambda.StartingPosition.TRIM_HORIZON + }); + + // WHEN/THEN + test.equal(eventSource.eventSourceMappingId, undefined); + test.done(); + }, + }; diff --git a/packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts b/packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts index 53bd8eb3b0c27..3302833742578 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts @@ -153,4 +153,34 @@ export = { test.done(); }, + + 'contains eventSourceMappingId after lambda binding'(test: Test) { + // GIVEN + const stack = new cdk.Stack(); + const fn = new TestFunction(stack, 'Fn'); + const stream = new kinesis.Stream(stack, 'S'); + const eventSource = new sources.KinesisEventSource(stream, { + startingPosition: lambda.StartingPosition.TRIM_HORIZON + }); + + // WHEN + fn.addEventSource(eventSource); + + // THEN + test.notEqual(eventSource.eventSourceMappingId, undefined); + test.done(); + }, + + 'eventSourceMappingId is undefined before binding to lambda'(test: Test) { + // GIVEN + const stack = new cdk.Stack(); + const stream = new kinesis.Stream(stack, 'S'); + const eventSource = new sources.KinesisEventSource(stream, { + startingPosition: lambda.StartingPosition.TRIM_HORIZON + }); + + // WHEN/THEN + test.equal(eventSource.eventSourceMappingId, undefined); + test.done(); + }, }; diff --git a/packages/@aws-cdk/aws-lambda-event-sources/test/test.sqs.ts b/packages/@aws-cdk/aws-lambda-event-sources/test/test.sqs.ts index 90587f38ebdf2..e6f0566e74029 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/test/test.sqs.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/test/test.sqs.ts @@ -112,4 +112,30 @@ export = { test.done(); }, + + 'contains eventSourceMappingId after lambda binding'(test: Test) { + // GIVEN + const stack = new cdk.Stack(); + const fn = new TestFunction(stack, 'Fn'); + const q = new sqs.Queue(stack, 'Q'); + const eventSource = new sources.SqsEventSource(q); + + // WHEN + fn.addEventSource(eventSource); + + // THEN + test.notEqual(eventSource.eventSourceMappingId, undefined); + test.done(); + }, + + 'eventSourceMappingId is undefined before binding to lambda'(test: Test) { + // GIVEN + const stack = new cdk.Stack(); + const q = new sqs.Queue(stack, 'Q'); + const eventSource = new sources.SqsEventSource(q); + + // WHEN/THEN + test.equal(eventSource.eventSourceMappingId, undefined); + test.done(); + }, }; diff --git a/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts b/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts index a30a277af3f31..431012ef9180c 100644 --- a/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts +++ b/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts @@ -67,6 +67,12 @@ export interface EventSourceMappingProps extends EventSourceMappingOptions { * modify the Lambda's execution role so it can consume messages from the queue. */ export class EventSourceMapping extends cdk.Resource { + /** + * The Ref of the EventSourceMapping + * @attribute + */ + public readonly eventSourceMappingId: string; + constructor(scope: cdk.Construct, id: string, props: EventSourceMappingProps) { super(scope, id); @@ -74,7 +80,7 @@ export class EventSourceMapping extends cdk.Resource { throw new Error(`maxBatchingWindow cannot be over 300 seconds, got ${props.maxBatchingWindow.toSeconds()}`); } - new CfnEventSourceMapping(this, 'Resource', { + const cfnEventSourceMapping = new CfnEventSourceMapping(this, 'Resource', { batchSize: props.batchSize, enabled: props.enabled, eventSourceArn: props.eventSourceArn, @@ -82,6 +88,7 @@ export class EventSourceMapping extends cdk.Resource { startingPosition: props.startingPosition, maximumBatchingWindowInSeconds: props.maxBatchingWindow && props.maxBatchingWindow.toSeconds(), }); + this.eventSourceMappingId = cfnEventSourceMapping.ref; } } From ebda1b48328e019a2b028676f3102deca1819f8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elias=20Dr=C3=A4xler?= Date: Tue, 28 Jan 2020 15:03:03 +0100 Subject: [PATCH 2/3] fixed tests, throw error if eventSourceMapping is not bound --- .../aws-lambda-event-sources/README.md | 22 ++++++++++++++++--- .../aws-lambda-event-sources/lib/dynamodb.ts | 9 +++++--- .../aws-lambda-event-sources/lib/kinesis.ts | 9 +++++--- .../aws-lambda-event-sources/lib/sqs.ts | 9 +++++--- .../test/test.dynamo.ts | 6 ++--- .../test/test.kinesis.ts | 6 ++--- .../aws-lambda-event-sources/test/test.sqs.ts | 6 ++--- .../aws-lambda/lib/event-source-mapping.ts | 2 +- 8 files changed, 47 insertions(+), 22 deletions(-) diff --git a/packages/@aws-cdk/aws-lambda-event-sources/README.md b/packages/@aws-cdk/aws-lambda-event-sources/README.md index 515949dc8da3c..8d6ff886ddddc 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/README.md +++ b/packages/@aws-cdk/aws-lambda-event-sources/README.md @@ -116,7 +116,7 @@ To process events with a Lambda function, first create or update a DynamoDB tabl 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 lambda 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. +* __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 records that arrived prior to attaching the event source. ```ts import dynamodb = require('@aws-cdk/aws-dynamodb'); @@ -145,8 +145,8 @@ 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. +* __batchSize__: Determines how many records are buffered before invoking your lambda 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 records that arrived prior to attaching the event source. ```ts import lambda = require('@aws-cdk/aws-lambda'); @@ -161,6 +161,22 @@ myFunction.addEventSource(new KinesisEventSource(queue, { }); ``` +### Event Source Mapping +After creating and binding an event source to a lambda function you can access the Ref of the created `AWS::Lambda::EventSourceMapping` as `eventSourceMappingId`. +```ts +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'); +const eventSource = new KinesisEventSource(queue, { + batchSize: 100, // default + startingPosition: lambda.StartingPosition.TRIM_HORIZON +}; +myFunction.addEventSource(eventSource); + +const eventSourceMappingId = eventSource.eventSourceMappingId; +``` ## Roadmap Eventually, this module will support all the event sources described under diff --git a/packages/@aws-cdk/aws-lambda-event-sources/lib/dynamodb.ts b/packages/@aws-cdk/aws-lambda-event-sources/lib/dynamodb.ts index 08aaffa2241ba..9e520a6edd5f7 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/lib/dynamodb.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/lib/dynamodb.ts @@ -9,7 +9,7 @@ export interface DynamoEventSourceProps extends StreamEventSourceProps { * Use an Amazon DynamoDB stream as an event source for AWS Lambda. */ export class DynamoEventSource extends StreamEventSource { - private _eventSourceMappingId: string | undefined = undefined; + private _eventSourceMappingId?: string = undefined; constructor(private readonly table: dynamodb.Table, props: DynamoEventSourceProps) { super(props); @@ -33,9 +33,12 @@ export class DynamoEventSource extends StreamEventSource { } /** - * The Ref of the EventSourceMapping + * The identifier for this EventSourceMapping */ - public get eventSourceMappingId(): string | undefined { + public get eventSourceMappingId(): string { + if (!this._eventSourceMappingId) { + throw new Error("DynamoEventSource is not yet bound to an event source mapping"); + } return this._eventSourceMappingId; } } diff --git a/packages/@aws-cdk/aws-lambda-event-sources/lib/kinesis.ts b/packages/@aws-cdk/aws-lambda-event-sources/lib/kinesis.ts index dbff3b36ae7bc..f6b83f6be2638 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/lib/kinesis.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/lib/kinesis.ts @@ -9,7 +9,7 @@ export interface KinesisEventSourceProps extends StreamEventSourceProps { * Use an Amazon Kinesis stream as an event source for AWS Lambda. */ export class KinesisEventSource extends StreamEventSource { - private _eventSourceMappingId: string | undefined = undefined; + private _eventSourceMappingId?: string = undefined; constructor(readonly stream: kinesis.IStream, props: KinesisEventSourceProps) { super(props); @@ -29,9 +29,12 @@ export class KinesisEventSource extends StreamEventSource { } /** - * The Ref of the EventSourceMapping + * The identifier for this EventSourceMapping */ - public get eventSourceMappingId(): string | undefined { + public get eventSourceMappingId(): string { + if (!this._eventSourceMappingId) { + throw new Error("KinesisEventSource is not yet bound to an event source mapping"); + } return this._eventSourceMappingId; } } diff --git a/packages/@aws-cdk/aws-lambda-event-sources/lib/sqs.ts b/packages/@aws-cdk/aws-lambda-event-sources/lib/sqs.ts index 4fbaa8a0e712e..4b15e1b8e4b5d 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/lib/sqs.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/lib/sqs.ts @@ -18,7 +18,7 @@ export interface SqsEventSourceProps { * Use an Amazon SQS queue as an event source for AWS Lambda. */ export class SqsEventSource implements lambda.IEventSource { - private _eventSourceMappingId: string | undefined = undefined; + private _eventSourceMappingId?: string = undefined; constructor(readonly queue: sqs.IQueue, private readonly props: SqsEventSourceProps = { }) { if (this.props.batchSize !== undefined && (this.props.batchSize < 1 || this.props.batchSize > 10)) { @@ -37,9 +37,12 @@ export class SqsEventSource implements lambda.IEventSource { } /** - * The Ref of the EventSourceMapping + * The identifier for this EventSourceMapping */ - public get eventSourceMappingId(): string | undefined { + public get eventSourceMappingId(): string { + if (!this._eventSourceMappingId) { + throw new Error("SqsEventSource is not yet bound to an event source mapping"); + } return this._eventSourceMappingId; } } diff --git a/packages/@aws-cdk/aws-lambda-event-sources/test/test.dynamo.ts b/packages/@aws-cdk/aws-lambda-event-sources/test/test.dynamo.ts index ee26c852ca736..437cbd556ae64 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/test/test.dynamo.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/test/test.dynamo.ts @@ -250,11 +250,11 @@ export = { fn.addEventSource(eventSource); // THEN - test.notEqual(eventSource.eventSourceMappingId, undefined); + test.ok(eventSource.eventSourceMappingId); test.done(); }, - 'eventSourceMappingId is undefined before binding to lambda'(test: Test) { + 'eventSourceMappingId throws error before binding to lambda'(test: Test) { // GIVEN const stack = new cdk.Stack(); const table = new dynamodb.Table(stack, 'T', { @@ -269,7 +269,7 @@ export = { }); // WHEN/THEN - test.equal(eventSource.eventSourceMappingId, undefined); + test.throws(() => eventSource.eventSourceMappingId, /DynamoEventSource is not yet bound to an event source mapping/); test.done(); }, diff --git a/packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts b/packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts index 3302833742578..a1427af34b3da 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/test/test.kinesis.ts @@ -167,11 +167,11 @@ export = { fn.addEventSource(eventSource); // THEN - test.notEqual(eventSource.eventSourceMappingId, undefined); + test.ok(eventSource.eventSourceMappingId); test.done(); }, - 'eventSourceMappingId is undefined before binding to lambda'(test: Test) { + 'eventSourceMappingId throws error before binding to lambda'(test: Test) { // GIVEN const stack = new cdk.Stack(); const stream = new kinesis.Stream(stack, 'S'); @@ -180,7 +180,7 @@ export = { }); // WHEN/THEN - test.equal(eventSource.eventSourceMappingId, undefined); + test.throws(() => eventSource.eventSourceMappingId, /KinesisEventSource is not yet bound to an event source mapping/); test.done(); }, }; diff --git a/packages/@aws-cdk/aws-lambda-event-sources/test/test.sqs.ts b/packages/@aws-cdk/aws-lambda-event-sources/test/test.sqs.ts index e6f0566e74029..3c596c1f8845d 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/test/test.sqs.ts +++ b/packages/@aws-cdk/aws-lambda-event-sources/test/test.sqs.ts @@ -124,18 +124,18 @@ export = { fn.addEventSource(eventSource); // THEN - test.notEqual(eventSource.eventSourceMappingId, undefined); + test.ok(eventSource.eventSourceMappingId); test.done(); }, - 'eventSourceMappingId is undefined before binding to lambda'(test: Test) { + 'eventSourceMappingId throws error before binding to lambda'(test: Test) { // GIVEN const stack = new cdk.Stack(); const q = new sqs.Queue(stack, 'Q'); const eventSource = new sources.SqsEventSource(q); // WHEN/THEN - test.equal(eventSource.eventSourceMappingId, undefined); + test.throws(() => eventSource.eventSourceMappingId, /SqsEventSource is not yet bound to an event source mapping/); test.done(); }, }; diff --git a/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts b/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts index 431012ef9180c..d4f7f3f4c9012 100644 --- a/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts +++ b/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts @@ -68,7 +68,7 @@ export interface EventSourceMappingProps extends EventSourceMappingOptions { */ export class EventSourceMapping extends cdk.Resource { /** - * The Ref of the EventSourceMapping + * The identifier for this EventSourceMapping * @attribute */ public readonly eventSourceMappingId: string; From c4e65d91a393527369072e144c0c964584b870d0 Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Wed, 26 Feb 2020 09:55:02 +0000 Subject: [PATCH 3/3] updates to the README --- .../aws-lambda-event-sources/README.md | 36 ++++++++++--------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/packages/@aws-cdk/aws-lambda-event-sources/README.md b/packages/@aws-cdk/aws-lambda-event-sources/README.md index 8d6ff886ddddc..d2e13fcdb3184 100644 --- a/packages/@aws-cdk/aws-lambda-event-sources/README.md +++ b/packages/@aws-cdk/aws-lambda-event-sources/README.md @@ -9,6 +9,11 @@ --- +An event source mapping is an AWS Lambda resource that reads from an event source and invokes a Lambda function. +You can use event source mappings to process items from a stream or queue in services that don't invoke Lambda +functions directly. Lambda provides event source mappings for the following services. Read more about lambda +event sources [here](https://docs.aws.amazon.com/lambda/latest/dg/invocation-eventsourcemapping.html). + This module includes classes that allow using various AWS services as event sources for AWS Lambda via the high-level `lambda.addEventSource(source)` API. @@ -16,6 +21,21 @@ 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. +The following code sets up a lambda function with an SQS queue event source - + +```ts +const fn = new lambda.Function(this, 'MyFunction', { /* ... */ }); + +const queue = new sqs.Queue(this, 'MyQueue'); +const eventSource = lambda.addEventSource(new SqsEventSource(queue); + +const eventSourceId = eventSource.eventSourceId; +``` + +The `eventSourceId` property contains the event source id. This will be a +[token](https://docs.aws.amazon.com/cdk/latest/guide/tokens.html) that will resolve to the final value at the time of +deployment. + ### SQS Amazon Simple Queue Service (Amazon SQS) allows you to build asynchronous @@ -161,22 +181,6 @@ myFunction.addEventSource(new KinesisEventSource(queue, { }); ``` -### Event Source Mapping -After creating and binding an event source to a lambda function you can access the Ref of the created `AWS::Lambda::EventSourceMapping` as `eventSourceMappingId`. -```ts -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'); -const eventSource = new KinesisEventSource(queue, { - batchSize: 100, // default - startingPosition: lambda.StartingPosition.TRIM_HORIZON -}; -myFunction.addEventSource(eventSource); - -const eventSourceMappingId = eventSource.eventSourceMappingId; -``` ## Roadmap Eventually, this module will support all the event sources described under