151 lines
5.3 KiB
Markdown
151 lines
5.3 KiB
Markdown
# 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:
|
||
|
||
```ts
|
||
// An sns topic for successful invocations of a lambda function
|
||
import * as sns from 'aws-cdk-lib/aws-sns';
|
||
|
||
const myTopic = new sns.Topic(this, 'Topic');
|
||
|
||
const myFn = new lambda.Function(this, 'Fn', {
|
||
runtime: lambda.Runtime.NODEJS_LATEST,
|
||
handler: 'index.handler',
|
||
code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
|
||
// sns topic for successful invocations
|
||
onSuccess: new destinations.SnsDestination(myTopic),
|
||
})
|
||
```
|
||
|
||
Example with a SQS queue for unsuccessful invocations:
|
||
|
||
```ts
|
||
// An sqs queue for unsuccessful invocations of a lambda function
|
||
import * as sqs from 'aws-cdk-lib/aws-sqs';
|
||
|
||
const deadLetterQueue = new sqs.Queue(this, 'DeadLetterQueue');
|
||
|
||
const myFn = new lambda.Function(this, 'Fn', {
|
||
runtime: lambda.Runtime.NODEJS_LATEST,
|
||
handler: 'index.handler',
|
||
code: lambda.Code.fromInline('// your code'),
|
||
// sqs queue for unsuccessful invocations
|
||
onFailure: new destinations.SqsDestination(deadLetterQueue),
|
||
});
|
||
```
|
||
|
||
See also [Configuring Destinations for Asynchronous Invocation](https://docs.aws.amazon.com/lambda/latest/dg/invocation-async.html#invocation-async-destinations).
|
||
|
||
### 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:
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"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](https://docs.aws.amazon.com/eventbridge/latest/userguide/aws-events.html)
|
||
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:
|
||
|
||
```ts
|
||
// Auto-extract response payload with a lambda destination
|
||
declare const destinationFn: lambda.Function;
|
||
|
||
const sourceFn = new lambda.Function(this, 'Source', {
|
||
runtime: lambda.Runtime.NODEJS_LATEST,
|
||
handler: 'index.handler',
|
||
code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
|
||
// auto-extract on success
|
||
onSuccess: new destinations.LambdaDestination(destinationFn, {
|
||
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.
|