AWS Lambda Developer Guide 1.Dev [Highlighted]

User Manual:
Open the PDF directly: View PDF .
Page Count: 526
Download
Open PDF In Browser	View PDF
AWS Lambda
Developer Guide

AWS Lambda Developer Guide

AWS Lambda: Developer Guide

Copyright © 2019 Amazon Web Services, Inc. and/or its aﬃliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by
Amazon.

AWS Lambda Developer Guide

Table of Contents
What Is AWS Lambda? ........................................................................................................................ 1
When Should I Use AWS Lambda? ................................................................................................ 1
Are You a First-time User of AWS Lambda? ................................................................................... 2
Getting Started .................................................................................................................................. 3
Create a Function ....................................................................................................................... 3
Invoke the Lambda Function and Verify Results, Logs, and Metrics ............................................ 5
Concepts ................................................................................................................................... 6
Command Line Tools .................................................................................................................. 7
Set Up the AWS CLI ........................................................................................................... 7
AWS Serverless Application Model CLI .................................................................................. 7
Lambda Functions .............................................................................................................................. 8
Building Lambda Functions ......................................................................................................... 8
Authoring Code for Your Lambda Function ............................................................................ 8
Deploying Code and Creating a Lambda Function ................................................................. 10
Monitoring and Troubleshooting ........................................................................................ 10
AWS Lambda-Based Application Examples ........................................................................... 11
Code Editor ............................................................................................................................. 11
Working with Files and Folders .......................................................................................... 11
Working with Code ........................................................................................................... 13
Using the Menu Bar .......................................................................................................... 16
Working in Fullscreen Mode ............................................................................................... 17
Working with Preferences .................................................................................................. 17
Working with Commands .................................................................................................. 17
Programming Model ................................................................................................................. 18
Deployment Package ................................................................................................................ 19
Permissions Policies on Lambda Deployment Packages .......................................................... 19
Accessing AWS Resources .......................................................................................................... 20
Accessing AWS Services ..................................................................................................... 20
Accessing non AWS Services .............................................................................................. 20
Accessing Private Services or Resources ............................................................................... 21
Conﬁguring Functions ....................................................................................................................... 22
Basic Conﬁguration ................................................................................................................... 22
Environment Variables .............................................................................................................. 23
Setting Up ....................................................................................................................... 23
Rules for Naming Environment Variables ............................................................................. 25
Environment Variables and Function Versioning ................................................................... 26
Environment Variable Encryption ....................................................................................... 26
Create a Lambda Function Using Environment Variables ........................................................ 27
Create a Lambda Function Using Environment Variables To Store Sensitive Information ............. 28
Versioning ............................................................................................................................... 30
Versioning ....................................................................................................................... 31
Aliases ............................................................................................................................ 34
Resource Policies .............................................................................................................. 42
Managing Versioning ........................................................................................................ 43
Traﬃc Shifting Using Aliases .............................................................................................. 45
Layers ..................................................................................................................................... 47
Conﬁguring a Function to Use Layers .................................................................................. 48
Managing Layers .............................................................................................................. 49
Including Library Dependencies in a Layer ........................................................................... 50
Layer Permissions ............................................................................................................. 51
VPC Settings ............................................................................................................................ 52
Conﬁguring a Lambda Function for Amazon VPC Access ........................................................ 52
Internet Access for Lambda Functions ................................................................................. 53
Guidelines for Setting Up VPC-Enabled Lambda Functions ..................................................... 53

iii

AWS Lambda Developer Guide

Tutorial: Amazon ElastiCache ............................................................................................. 54
Tutorial: Amazon RDS ....................................................................................................... 56
Invoking Functions ........................................................................................................................... 60
Example 1 ............................................................................................................................... 60
Example 2 ............................................................................................................................... 61
Example 2 ............................................................................................................................... 62
Invocation Types ...................................................................................................................... 63
Event Source Mapping .............................................................................................................. 64
Event Source Mapping for AWS Services ............................................................................. 64
Event Source Mapping for AWS Poll-Based Services .............................................................. 65
Event Source Mapping for Custom Applications .................................................................... 66
Retry Behavior ......................................................................................................................... 67
Scaling .................................................................................................................................... 68
Request Rate ................................................................................................................... 69
Automatic Scaling ............................................................................................................ 69
Dead Letter Queues .................................................................................................................. 70
Supported Event Sources .......................................................................................................... 71
Amazon S3 ...................................................................................................................... 72
Amazon DynamoDB .......................................................................................................... 73
Amazon Kinesis Data Streams ............................................................................................ 73
Amazon Simple Notiﬁcation Service ................................................................................... 73
Amazon Simple Email Service ............................................................................................ 74
Amazon Simple Queue Service ........................................................................................... 74
Amazon Cognito .............................................................................................................. 75
AWS CloudFormation ........................................................................................................ 75
Amazon CloudWatch Logs ................................................................................................. 75
Amazon CloudWatch Events .............................................................................................. 76
AWS CodeCommit ............................................................................................................ 76
Scheduled Events (powered by Amazon CloudWatch Events) .................................................. 76
AWS Conﬁg ..................................................................................................................... 77
Amazon Alexa .................................................................................................................. 77
Amazon Lex ..................................................................................................................... 77
Amazon API Gateway ........................................................................................................ 77
AWS IoT Button ............................................................................................................... 78
Amazon CloudFront .......................................................................................................... 78
Amazon Kinesis Data Firehose ............................................................................................ 78
Other Event Sources: Invoking a Lambda Function On Demand .............................................. 79
Sample Event Data ................................................................................................................... 79
Lambda Runtimes ............................................................................................................................ 91
Execution Environment ............................................................................................................. 92
Environment Variables Available to Lambda Functions .......................................................... 92
Execution Context .................................................................................................................... 93
Runtime Support Policy ............................................................................................................ 94
Custom Runtimes ..................................................................................................................... 95
Using a Custom Runtime ................................................................................................... 95
Building a Custom Runtime ............................................................................................... 95
Runtime Interface ..................................................................................................................... 97
Next Invocation ................................................................................................................ 97
Invocation Response ......................................................................................................... 98
Invocation Error ............................................................................................................... 98
Initialization Error ............................................................................................................. 99
Tutorial – Custom Runtime ........................................................................................................ 99
Prerequisites .................................................................................................................... 99
Create a Function ........................................................................................................... 100
Create a Layer ................................................................................................................ 101
Update the Function ....................................................................................................... 102
Update the Runtime ....................................................................................................... 103

iv

AWS Lambda Developer Guide

Share the Layer ..............................................................................................................
Clean Up .......................................................................................................................
Lambda Applications .......................................................................................................................
Manage Applications ...............................................................................................................
Monitoring Applications ..................................................................................................
Custom Monitoring Dashboards ........................................................................................
AWS SAM ..............................................................................................................................
Building a Pipeline for Your Serverless Application ......................................................................
Step 1: Set Up Your Repository ........................................................................................
Step 2: Create Your Pipeline ............................................................................................
Step 3: Update the Generated Service Policy ......................................................................
Step 4: Complete Your Beta Deployment Stage ..................................................................
Use Cases ......................................................................................................................................
Amazon S3 ............................................................................................................................
Tutorial .........................................................................................................................
Sample Code .................................................................................................................
Sample Template ............................................................................................................
Kinesis ...................................................................................................................................
Conﬁguring Your Data Stream and Function ......................................................................
Creating an Event Source Mapping ...................................................................................
Event Source Mapping API ...............................................................................................
Execution Role Permissions ..............................................................................................
Amazon CloudWatch Metrics ............................................................................................
Tutorial .........................................................................................................................
Sample Code .................................................................................................................
Sample Template ............................................................................................................
Amazon SQS ..........................................................................................................................
Conﬁguring a Queue for Use With Lambda ........................................................................
Conﬁguring a Queue as an Event Source ...........................................................................
Execution Role Permissions ..............................................................................................
Tutorial .........................................................................................................................
Sample Code .................................................................................................................
Sample Template ............................................................................................................
Amazon DynamoDB ................................................................................................................
Creating an Event Source Mapping ...................................................................................
Execution Role Permissions ..............................................................................................
Tutorial .........................................................................................................................
Sample Code .................................................................................................................
Sample Template ............................................................................................................
AWS CloudTrail ......................................................................................................................
Tutorial .........................................................................................................................
Sample Code .................................................................................................................
Amazon SNS ..........................................................................................................................
Tutorial .........................................................................................................................
Sample Code .................................................................................................................
Amazon API Gateway ..............................................................................................................
Tutorial .........................................................................................................................
Sample Code .................................................................................................................
Microservice Blueprint .....................................................................................................
Sample Template ............................................................................................................
Android App ..........................................................................................................................
Tutorial .........................................................................................................................
Sample Code .................................................................................................................
CloudWatch Events .................................................................................................................
Tutorial .........................................................................................................................
Sample Template ............................................................................................................
Schedule Expressions ......................................................................................................

v

103
104
105
105
106
106
108
108
110
111
112
113
114
114
116
122
129
129
130
131
132
133
133
133
137
140
141
143
143
143
144
147
150
150
152
152
153
157
160
161
162
166
168
168
171
173
174
182
185
186
187
188
194
195
196
198
199

AWS Lambda Developer Guide

Application Load Balancer .......................................................................................................
AWS CLI ................................................................................................................................
Prerequisites ..................................................................................................................
Create the Execution Role ................................................................................................
Create the Function ........................................................................................................
List the Lambda Functions in Your Account ........................................................................
Clean Up .......................................................................................................................
Lambda@Edge .......................................................................................................................
Monitoring .....................................................................................................................................
Using Amazon CloudWatch ......................................................................................................
AWS Lambda Troubleshooting Scenarios ...........................................................................
Monitoring Graphs ..........................................................................................................
Accessing CloudWatch Logs .............................................................................................
Lambda Metrics ..............................................................................................................
Using AWS X-Ray ....................................................................................................................
Tracing Lambda-Based Applications with AWS X-Ray ...........................................................
Setting Up AWS X-Ray with Lambda .................................................................................
Emitting Trace Segments from a Lambda Function .............................................................
The AWS X-Ray Daemon in the Lambda Environment ..........................................................
Using Environment Variables to Communicate with AWS X-Ray ............................................
Lambda Traces in the AWS X-Ray Console: Examples ...........................................................
Administration ...............................................................................................................................
Permissions ............................................................................................................................
Execution Role ...............................................................................................................
Resource-Based Policies ...................................................................................................
User Policies ..................................................................................................................
Resources and Conditions ................................................................................................
CloudTrail ..............................................................................................................................
AWS Lambda Information in CloudTrail .............................................................................
Understanding AWS Lambda Log File Entries .....................................................................
Using CloudTrail to Track Function Invocations ...................................................................
Tagging .................................................................................................................................
Tagging Lambda Functions for Billing ...............................................................................
Applying Tags to Lambda Functions ..................................................................................
Filtering on Tagged Lambda Functions ..............................................................................
Tag Restrictions ..............................................................................................................
Managing Concurrency ............................................................................................................
Account Level Concurrent Executions Limit ........................................................................
Function Level Concurrent Execution Limit .........................................................................
Throttling Behavior .........................................................................................................
Monitoring Your Concurrency Usage .................................................................................
Best Practices .........................................................................................................................
Function Code ................................................................................................................
Function Conﬁguration ....................................................................................................
Alarming and Metrics ......................................................................................................
Stream Event Invokes ......................................................................................................
Async Invokes ................................................................................................................
Lambda VPC ..................................................................................................................
Limits ....................................................................................................................................
Working with Node.js ......................................................................................................................
Deployment Package ..............................................................................................................
Handler .................................................................................................................................
Using the Callback Parameter ..........................................................................................
Example ........................................................................................................................
Context .................................................................................................................................
Logging .................................................................................................................................
Finding Logs ..................................................................................................................

vi

202
203
203
203
204
205
206
206
208
208
208
210
211
211
214
214
216
217
218
218
218
221
221
222
223
226
231
235
235
236
238
238
238
239
240
241
241
242
242
244
244
245
245
246
246
247
247
247
249
250
250
251
252
253
254
255
256

AWS Lambda Developer Guide

Errors ....................................................................................................................................
Function Error Handling ..................................................................................................
Tracing ..................................................................................................................................
Working with Python ......................................................................................................................
Deployment Package ..............................................................................................................
Without Additional Dependencies .....................................................................................
With Additional Dependencies ..........................................................................................
With a Virtual Environment .............................................................................................
Handler .................................................................................................................................
Context .................................................................................................................................
Logging .................................................................................................................................
Finding Logs ..................................................................................................................
Errors ....................................................................................................................................
Function Error Handling ..................................................................................................
Tracing ..................................................................................................................................
Working with Java ..........................................................................................................................
Deployment Package ..............................................................................................................
Creating a .jar Deployment Package Using Maven without any IDE (Java) ................................
Creating a .jar Deployment Package Using Maven and Eclipse IDE (Java) .................................
Creating a .zip Deployment Package (Java) ........................................................................
Authoring Lambda Functions Using Eclipse IDE and AWS SDK Plugin (Java) ............................
Handler .................................................................................................................................
Handler Overload Resolution ...........................................................................................
Additional Information ....................................................................................................
Handler Input/Output Types (Java) ...................................................................................
Leveraging Predeﬁned Interfaces for Creating Handler (Java) ...............................................
Context .................................................................................................................................
Logging .................................................................................................................................
Custom Appender for Log4j™ 2 .......................................................................................
LambdaLogger.log() ........................................................................................................
How to Find Logs ...........................................................................................................
Logging Examples (Java) .................................................................................................
Errors ....................................................................................................................................
Function Error Handling ..................................................................................................
Tracing ..................................................................................................................................
Sample Function ....................................................................................................................
Working with Go ............................................................................................................................
Deployment Package ..............................................................................................................
Creating a Deployment Package on Windows .....................................................................
Handler .................................................................................................................................
Handler .........................................................................................................................
Using Global State ..........................................................................................................
Context .................................................................................................................................
Accessing Invoke Context Information ...............................................................................
Logging .................................................................................................................................
Finding Logs ..................................................................................................................
Errors ....................................................................................................................................
Function Error Handling ..................................................................................................
Handling Unexpected Errors ............................................................................................
Tracing ..................................................................................................................................
Installing the X-Ray SDK for Go ........................................................................................
Conﬁguring the X-Ray SDK for Go ....................................................................................
Create a subsegment ......................................................................................................
Capture .........................................................................................................................
Tracing HTTP Requests ....................................................................................................
Environment Variables ............................................................................................................
Working with C# ............................................................................................................................

vii

257
259
260
262
262
263
263
264
266
267
268
269
270
271
272
275
276
276
278
280
283
283
284
284
285
289
293
294
294
294
295
295
298
299
300
302
304
304
305
305
306
308
309
309
310
311
312
271
313
313
314
314
314
314
315
315
316

AWS Lambda Developer Guide

Deployment Package ..............................................................................................................
.NET Core CLI .................................................................................................................
AWS Toolkit for Visual Studio ..........................................................................................
Handler .................................................................................................................................
Handling Streams ...........................................................................................................
Handling Standard Data Types .........................................................................................
Handler Signatures .........................................................................................................
Lambda Function Handler Restrictions ..............................................................................
Using Async in C# Functions with AWS Lambda ..................................................................
Context .................................................................................................................................
Logging .................................................................................................................................
How to Find Logs ...........................................................................................................
Errors ....................................................................................................................................
Function Error Handling ..................................................................................................
Working with PowerShell .................................................................................................................
Deployment Package ..............................................................................................................
Setting Up a PowerShell Development Environment ...........................................................
Using the AWSLambdaPSCore Module ...............................................................................
Handler .................................................................................................................................
Returning Data ...............................................................................................................
Context .................................................................................................................................
Logging .................................................................................................................................
How to Find Logs ...........................................................................................................
Errors ....................................................................................................................................
Function Error Handling ..................................................................................................
Working with Ruby .........................................................................................................................
Handler .................................................................................................................................
Deployment Package ..............................................................................................................
Updating a Function with No Dependencies .......................................................................
Updating a Function with Additional Dependencies .............................................................
Context .................................................................................................................................
Logging .................................................................................................................................
Errors ....................................................................................................................................
API Reference .................................................................................................................................
Actions ..................................................................................................................................
AddLayerVersionPermission ..............................................................................................
AddPermission ...............................................................................................................
CreateAlias .....................................................................................................................
CreateEventSourceMapping ..............................................................................................
CreateFunction ...............................................................................................................
DeleteAlias .....................................................................................................................
DeleteEventSourceMapping ..............................................................................................
DeleteFunction ...............................................................................................................
DeleteFunctionConcurrency ..............................................................................................
DeleteLayerVersion .........................................................................................................
GetAccountSettings .........................................................................................................
GetAlias .........................................................................................................................
GetEventSourceMapping ..................................................................................................
GetFunction ...................................................................................................................
GetFunctionConﬁguration ................................................................................................
GetLayerVersion .............................................................................................................
GetLayerVersionPolicy .....................................................................................................
GetPolicy .......................................................................................................................
Invoke ...........................................................................................................................
InvokeAsync ...................................................................................................................
ListAliases ......................................................................................................................
ListEventSourceMappings ................................................................................................

viii

316
317
324
325
326
326
327
328
328
329
330
331
331
334
336
336
337
337
339
340
340
341
341
341
342
343
344
345
345
346
347
348
348
350
350
352
356
360
364
368
376
378
381
383
385
387
389
392
395
398
403
406
408
410
415
417
420

AWS Lambda Developer Guide

ListFunctions ..................................................................................................................
ListLayers ......................................................................................................................
ListLayerVersions ............................................................................................................
ListTags .........................................................................................................................
ListVersionsByFunction ....................................................................................................
PublishLayerVersion ........................................................................................................
PublishVersion ................................................................................................................
PutFunctionConcurrency ..................................................................................................
RemoveLayerVersionPermission ........................................................................................
RemovePermission ..........................................................................................................
TagResource ...................................................................................................................
UntagResource ...............................................................................................................
UpdateAlias ...................................................................................................................
UpdateEventSourceMapping ............................................................................................
UpdateFunctionCode .......................................................................................................
UpdateFunctionConﬁguration ...........................................................................................
Data Types ............................................................................................................................
AccountLimit ..................................................................................................................
AccountUsage ................................................................................................................
AliasConﬁguration ..........................................................................................................
AliasRoutingConﬁguration ...............................................................................................
Concurrency ...................................................................................................................
DeadLetterConﬁg ...........................................................................................................
Environment ..................................................................................................................
EnvironmentError ...........................................................................................................
EnvironmentResponse .....................................................................................................
EventSourceMappingConﬁguration ...................................................................................
FunctionCode .................................................................................................................
FunctionCodeLocation .....................................................................................................
FunctionConﬁguration .....................................................................................................
Layer .............................................................................................................................
LayersListItem ................................................................................................................
LayerVersionContentInput ................................................................................................
LayerVersionContentOutput .............................................................................................
LayerVersionsListItem ......................................................................................................
TracingConﬁg .................................................................................................................
TracingConﬁgResponse ....................................................................................................
VpcConﬁg ......................................................................................................................
VpcConﬁgResponse .........................................................................................................
Certiﬁcate Errors When Using an SDK .......................................................................................
Releases ........................................................................................................................................
Earlier Updates .......................................................................................................................
AWS Glossary .................................................................................................................................

ix

423
426
428
431
433
436
440
446
449
451
454
456
458
462
466
472
479
480
481
482
484
485
486
487
488
489
490
492
493
494
498
499
500
501
502
504
505
506
507
507
509
511
517

AWS Lambda Developer Guide
When Should I Use AWS Lambda?

What Is AWS Lambda?
AWS Lambda is a compute service that lets you run code without provisioning or managing servers. AWS
Lambda executes your code only when needed and scales automatically, from a few requests per day
to thousands per second. You pay only for the compute time you consume - there is no charge when
your code is not running. With AWS Lambda, you can run code for virtually any type of application
or backend service - all with zero administration. AWS Lambda runs your code on a high-availability
compute infrastructure and performs all of the administration of the compute resources, including server
and operating system maintenance, capacity provisioning and automatic scaling, code monitoring and
logging. All you need to do is supply your code in one of the languages that AWS Lambda supports
(currently Node.js, Java, C#, Go and Python).
You can use AWS Lambda to run your code in response to events, such as changes to data in an Amazon
S3 bucket or an Amazon DynamoDB table; to run your code in response to HTTP requests using Amazon
API Gateway; or invoke your code using API calls made using AWS SDKs. With these capabilities, you
can use Lambda to easily build data processing triggers for AWS services like Amazon S3 and Amazon
DynamoDB, process streaming data stored in Kinesis, or create your own back end that operates at AWS
scale, performance, and security.
You can also build serverless applications composed of functions that are triggered by events and
automatically deploy them using AWS CodePipeline and AWS CodeBuild. For more information, see AWS
Lambda Applications (p. 105).
For more information about the AWS Lambda execution environment, see Lambda Execution
Environment and Available Libraries (p. 92). For information about how AWS Lambda
determines compute resources required to execute your code, see Basic AWS Lambda Function
Conﬁguration (p. 22).

When Should I Use AWS Lambda?
AWS Lambda is an ideal compute platform for many application scenarios, provided that you can write
your application code in languages supported by AWS Lambda (that is, Node.js, Java, Go and C# and
Python), and run within the AWS Lambda standard runtime environment and resources provided by
Lambda.
When using AWS Lambda, you are responsible only for your code. AWS Lambda manages the compute
ﬂeet that oﬀers a balance of memory, CPU, network, and other resources. This is in exchange for
ﬂexibility, which means you cannot log in to compute instances, or customize the operating system or
language runtime. These constraints enable AWS Lambda to perform operational and administrative
activities on your behalf, including provisioning capacity, monitoring ﬂeet health, applying security
patches, deploying your code, and monitoring and logging your Lambda functions.
If you need to manage your own compute resources, Amazon Web Services also oﬀers other compute
services to meet your needs.
• Amazon Elastic Compute Cloud (Amazon EC2) service oﬀers ﬂexibility and a wide range of EC2
instance types to choose from. It gives you the option to customize operating systems, network and
security settings, and the entire software stack, but you are responsible for provisioning capacity,
monitoring ﬂeet health and performance, and using Availability Zones for fault tolerance.
• Elastic Beanstalk oﬀers an easy-to-use service for deploying and scaling applications onto Amazon EC2
in which you retain ownership and full control over the underlying EC2 instances.

1

AWS Lambda Developer Guide
Are You a First-time User of AWS Lambda?

Lambda is a highly available service. For more information, see the AWS Lambda Service Level
Agreement.

Are You a First-time User of AWS Lambda?
If you are a ﬁrst-time user of AWS Lambda, we recommend that you read the following sections in order:
1. Read the product overview and watch the introductory video to understand sample use cases.
These resources are available on the AWS Lambda webpage.
2. Review the Lambda Functions (p. 8) section of this guide. To understand the programming
model and deployment options for a Lambda function there are core concepts you should be
familiar with. This section explains these concepts and provides details of how they work in diﬀerent
languages that you can use to author your Lambda function code.
3. Try the console-based Getting Started exercise. The exercise provides instructions for you to create
and test your ﬁrst Lambda function using the console. You also learn about the console provided
blueprints to quickly create your Lambda functions. For more information, see Getting Started with
AWS Lambda (p. 3).
4. Read the Deploying Applications with AWS Lambda (p. 105) section of this guide. This section
introduces various AWS Lambda components you work with to create an end-to-end experience.
Beyond the Getting Started exercise, you can explore the various use cases, each of which is provided
with a tutorial that walks you through an example scenario. Depending on your application needs (for
example, whether you want event driven Lambda function invocation or on-demand invocation), you can
follow speciﬁc tutorials that meet your speciﬁc needs. For more information, see Use Cases (p. 114).
The following topics provide additional information about AWS Lambda:
• AWS Lambda Function Versioning and Aliases (p. 30)
• Using Amazon CloudWatch (p. 208)
• Best Practices for Working with AWS Lambda Functions (p. 245)
• AWS Lambda Limits (p. 249)

2

AWS Lambda Developer Guide
Create a Function

Getting Started with AWS Lambda
To get started with AWS Lambda, use the Lambda console to create a function. In a few minutes, you can
create a function, invoke it, and view logs, metrics, and trace data.
To use Lambda and other AWS services, you need an AWS account. If you don't have an account, visit
aws.amazon.com and choose Create an AWS Account. For detailed instructions, see Create and Activate
an AWS Account.
As a best practice, you should also create an AWS Identity and Access Management (IAM) user with
administrator permissions and use that for all work that does not require root credentials. Create a
password for console access, and access keys to use command line tools. See Creating Your First IAM
Admin User and Group in the IAM User Guide for instructions.
Sections
• Create a Lambda Function with the Console (p. 3)
• AWS Lambda Concepts (p. 6)
• Command Line Tools (p. 7)

Create a Lambda Function with the Console
In this Getting Started exercise you ﬁrst create a Lambda function using the AWS Lambda console. Next,
you manually invoke the Lambda function using sample event data. AWS Lambda executes the Lambda
function and returns results. You then verify execution results, including the logs that your Lambda
function created and various CloudWatch metrics.
As you follow the steps, you will also familiarize yourself with the AWS Lambda console including:
• Explore the blueprints. Each blueprint provides sample code and sample conﬁgurations that enable
you to create Lambda functions with just a few clicks.
• View and update conﬁguration information of your Lambda function.
• Invoke a Lambda function manually and explore results in the Execution results section.
• Monitor CloudWatch metrics in the console.
Follow the steps in this section to create a simple Lambda function.

To create a Lambda function
1.

Sign in to the AWS Management Console and open the AWS Lambda console.

2.

Note that AWS Lambda oﬀers a simple Hello World function upon introduction under the
How it works label and includes a Run option, allowing you to invoke the function as a general
introduction. This tutorial introduces additional options you have to create, test and update your
Lambda functions, as well as other features provided by the Lambda console and provides links to
each, inviting you to explore each one in depth.
Choose Create a function under the Get Started section to proceed.

3

AWS Lambda Developer Guide
Create a Function

Note

The console shows the Get Started page only if you do not have any Lambda functions
created. If you have created functions already, you will see the Lambda > Functions page.
On the list page, choose Create a function to go to the Create function page.
3.

On the Create function page, choose Author from scratch.

4.

In Author from scratch, do the following:
• In Name*, specify your Lambda function name.
• In Runtime*, choose Python 3.7.
• In Role*, choose Create new role from template(s):
• In Role name*, enter a name for your role.
• Leave the Policy templates ﬁeld blank. For the purposes of this introduction, your Lambda
function will have the necessary execution permissions.

Note

For an in-depth look at AWS Lambda's security polices, see AWS Lambda
Permissions (p. 221).
• Choose Create Function.
5.

In the Add triggers panel, you can optionally choose a service that automatically triggers your
Lambda function by choosing one of the service options listed.
Depending on which service you select, you are prompted to provide relevant information for that
service. For example, if you select DynamoDB, you need to provide the following:
• The name of the DynamoDB table
• Batch size
• Starting position
For this example, do not conﬁgure a trigger.
• In Function code note that code is provided. It returns a simple "Hello from Lambda" greeting.
• Handler shows lambda_function.lambda_handler value. It is the filename.handlerfunction. The console saves the sample code in the lambda_function.py ﬁle and in the code
lambda_handler is the function name that receives the event as a parameter when the Lambda
function is invoked. For more information, see AWS Lambda Function Handler in Python (p. 266).
• Note the embedded IDE (Integrated Development Environment). To learn more, see Creating
Functions Using the AWS Lambda Console Editor (p. 11).

6.

Other conﬁguration options on this page include:
• Environment variables – for Lambda functions enable you to dynamically pass settings to your
function code and libraries, without making changes to your code. For more information, see AWS
Lambda Environment Variables (p. 23).
• Tags – are key-value pairs that you attach to AWS resources to better organize them. For more
information, see Tagging Lambda Functions (p. 238).
• Execution role – which allows you to administer security on your function, using deﬁned roles and
policies or creating new ones. For more information, see AWS Lambda Permissions (p. 221).
• Basic settings – allows you to dictate the memory allocation and timeout limit for your Lambda
function. For more information, see AWS Lambda Limits (p. 249).
• Network – allows you to select a VPC your function will access. For more information, see
Conﬁguring a Lambda Function to Access Resources in an Amazon VPC (p. 52).
• Debugging and error handling – allows you to select a Dead Letter Queues (p. 70) resource
to analyze failed function invocation retries. It also allows you to enable active tracing. For more
information, see Using AWS X-Ray (p. 214).

4

AWS Lambda Developer Guide
Invoke the Lambda Function and
Verify Results, Logs, and Metrics

• Concurrency – allows you to allocate a speciﬁc limit of concurrent executions allowed for this
function. For more information, see Function Level Concurrent Execution Limit (p. 242).
• Auditing and compliance – logs function invocations for operational and risk auditing,
governance and compliance. For more information, see Using AWS Lambda with AWS
CloudTrail (p. 161).

Invoke the Lambda Function and Verify Results, Logs,
and Metrics
Follow the steps to invoke your Lambda function using the sample event data provided in the console.
1.

On the yourfunction page, choose Test.

2.

In the Conﬁgure test event page, choose Create new test event and in Event template, leave the
default Hello World option. Enter an Event name and note the following sample event template:
{

}

"key3": "value3",
"key2": "value2",
"key1": "value1"

You can change key and values in the sample JSON, but don't change the event structure. If you do
change any keys and values, you must update the sample code accordingly.

Note

If you choose to delete the test event, go to the Conﬁgure test event page and then choose
Delete.
3.

Choose Create and then choose Test. Each user can create up to 10 test events per function. Those
test events are not available to other users.

4.

AWS Lambda executes your function on your behalf. The handler in your Lambda function receives
and then processes the sample event.

5.

Upon successful execution, view results in the console.
• The Execution result section shows the execution status as succeeded and also shows the
function execution results, returned by the return statement.
• The Summary section shows the key information reported in the Log output section (the REPORT
line in the execution log).
• The Log output section shows the log AWS Lambda generates for each execution. These are the
logs written to CloudWatch by the Lambda function. The AWS Lambda console shows these logs
for your convenience.
Note that the Click here link shows logs in the CloudWatch console. The function then adds logs to
Amazon CloudWatch in the log group that corresponds to the Lambda function.

6.

Run the Lambda function a few times to gather some metrics that you can view in the next step.

7.

Choose Monitoring. This page shows graphs for the metrics that Lambda sends to CloudWatch.

5

AWS Lambda Developer Guide
Concepts

For more information on these graphs, see Accessing Amazon CloudWatch Metrics for AWS
Lambda (p. 210).

AWS Lambda Concepts
AWS Lambda lets you run functions in a serverless environment to process events in the language of your
choice. Each instance of your function runs in an isolated execution context and processes one event at
a time. When it ﬁnishes processing the event, it returns a response and Lambda sends it another event.
Lambda automatically scales up the number of instances of your function to handle high numbers of
events.
• Function – A script or program that runs in AWS Lambda. Lambda passes invocation events to your
function. The function processes an event and returns a response. For more information, see Working
with Lambda Functions (p. 8).
• Runtimes – Lambda runtimes allow functions in diﬀerent languages to run in the same base execution
environment. You conﬁgure your function to use a runtime that matches your programming language.
The runtime sits in-between the Lambda service and your function code, relaying invocation events,
context information, and responses between the two. You can use runtimes provided by Lambda, or
build your own. For more infromation, see AWS Lambda Runtimes (p. 91).
• Layers – Lambda layers are a distribution mechanism for libraries, custom runtimes, and other function
dependencies. Layers let you manage your in-development function code independently from the
unchanging code and resources that it uses. You can conﬁgure your function to use layers that you
create, layers provided by AWS, or layers from other AWS customers. For more infromation, see AWS
Lambda Layers (p. 47)
• Event source – An AWS service, such as Amazon SNS, or a custom service, that triggers your function
and executes its logic. For more information, see AWS Lambda Event Source Mapping (p. 64).
• Downstream resources – An AWS service, such as DynamoDB tables or Amazon S3 buckets, that your
Lambda function calls once it is triggered.
• Log streams – While Lambda automatically monitors your function invocations and reports metrics to
CloudWatch, you can annotate your function code with custom logging statements that allow you to
analyze the execution ﬂow and performance of your Lambda function to ensure it's working properly.
• AWS SAM – A model to deﬁne serverless applications. AWS SAM is natively supported by AWS
CloudFormation and deﬁnes simpliﬁed syntax for expressing serverless resources. For more
information, see What Is AWS SAM? in the AWS Serverless Application Model Developer Guide.

6

AWS Lambda Developer Guide
Command Line Tools

Command Line Tools
Install the AWS Command Line Interface to manage and use Lambda functions from the command
line. Tutorials in this guide use the AWS CLI, which has commands for all Lambda API actions. Some
functionality is not available in the Lambda console and can only be accessed with the AWS CLI or the
AWS SDK.
The AWS SAM CLI is a separate command line tool that you can use to manage and test AWS SAM
applications. In addition to commands for uploading artifacts and launching AWS CloudFormation
stacks that are also available in the AWS CLI, the SAM CLI provides additional commands for validating
templates and running applications locally in a Docker container.

Set Up the AWS CLI
To set up the AWS CLI
1.

Download and conﬁgure the AWS CLI. For instructions, see the following topics in the AWS
Command Line Interface User Guide.
• Getting Set Up with the AWS Command Line Interface

2.

• Conﬁguring the AWS Command Line Interface
Add a named proﬁle for the administrator user in the AWS CLI conﬁg ﬁle. You use this proﬁle when
executing the AWS CLI commands. For more information on creating this proﬁle, see Named Proﬁles.
[profile adminuser]
aws_access_key_id = adminuser access key ID
aws_secret_access_key = adminuser secret access key
region = aws-region

For a list of available AWS regions, see Regions and Endpoints in the Amazon Web Services General
Reference.
3.

Verify the setup by entering the following commands at the command prompt.
• Try the help command to verify that the AWS CLI is installed on your computer:
$ aws help

• Try a Lambda command to verify the user can reach AWS Lambda. This command lists Lambda
functions in the account, if any. The AWS CLI uses the adminuser credentials to authenticate the
request.
$ aws lambda list-functions

AWS Serverless Application Model CLI
The AWS SAM CLI is a command line tool that operates on an AWS SAM template and application code.
With the AWS SAM CLI, you can invoke Lambda functions locally, create a deployment package for your
serverless application, deploy your serverless application to the AWS Cloud, and so on.
For more details about installing the AWS SAM CLI, see Installing the AWS SAM CLI in the AWS Serverless
Application Model Developer Guide.

7

AWS Lambda Developer Guide
Building Lambda Functions

Working with Lambda Functions
If you are new to AWS Lambda, you might ask: How does AWS Lambda execute my code? How does
AWS Lambda know the amount of memory and CPU requirements needed to run my Lambda code? The
following sections provide an overview of how a Lambda function works.
In subsequent sections, we cover how the functions you create get invoked, and how to deploy and
monitor them. We also recommend reading the Function Code and Function Conﬁguration sections at
Best Practices for Working with AWS Lambda Functions (p. 245).
To begin, we introduce you to the topic that explains the fundamentals of building a Lambda function,
Building Lambda Functions (p. 8).
Topics
• Building Lambda Functions (p. 8)
• Creating Functions Using the AWS Lambda Console Editor (p. 11)
• Programming Model (p. 18)
• Creating a Deployment Package (p. 19)
• Accessing AWS Resources from a Lambda Function (p. 20)

Building Lambda Functions
You upload your application code in the form of one or more Lambda functions to AWS Lambda, a
compute service. In turn, AWS Lambda executes the code on your behalf. AWS Lambda takes care of
provisioning and managing the servers to run the code upon invocation.
Typically, the lifecycle for an AWS Lambda-based application includes authoring code, deploying code to
AWS Lambda, and then monitoring and troubleshooting. The following are general questions that come
up in each of these lifecycle phases:
• Authoring code for your Lambda function – What languages are supported? Is there a programming
model that I need to follow? How do I package my code and dependencies for uploading to AWS
Lambda? What tools are available?
• Uploading code and creating Lambda functions – How do I upload my code package to AWS
Lambda? How do I tell AWS Lambda where to begin executing my code? How do I specify compute
requirements like memory and timeout?
• Monitoring and troubleshooting – For my Lambda function that is in production, what metrics are
available? If there are any failures, how do I get logs or troubleshoot issues?
The following sections provide introductory information and the Example section at the end provides
working examples for you to explore.

Authoring Code for Your Lambda Function
You can author your Lambda function code in the languages that are supported by AWS Lambda. For a
list of supported languages, see Lambda Execution Environment and Available Libraries (p. 92). There
are tools for authoring code, such as the AWS Lambda console, Eclipse IDE, and Visual Studio IDE. But the
available tools and options depend on the following:

8

AWS Lambda Developer Guide
Authoring Code for Your Lambda Function

• Language you choose to write your Lambda function code.
• Libraries that you use in your code. AWS Lambda runtime provides some of the libraries and you must
upload any additional libraries that you use.
The following table lists languages, and the available tools and options that you can use.
Language

Tools and Options for Authoring Code

Node.js

• AWS Lambda console
• Visual Studio, with IDE plug-in (see AWS Lambda Support in
Visual Studio)
• Your own authoring environment
• For more information, see Deploying Code and Creating a
Lambda Function (p. 10).

Java

• Eclipse, with AWS Toolkit for Eclipse (see Using AWS Lambda with
the AWS Toolkit for Eclipse)
• Your own authoring environment
• For more information, see Deploying Code and Creating a
Lambda Function (p. 10).

C#

• Visual Studio, with IDE plug-in (see AWS Lambda Support in
Visual Studio)
• .NET Core (see .NET Core installation guide)
• Your own authoring environment
• For more information, see Deploying Code and Creating a
Lambda Function (p. 10).

Python

• AWS Lambda console
• Your own authoring environment
• For more information, see Deploying Code and Creating a
Lambda Function (p. 10).

Go

• Your own authoring environment
• For more information, see Deploying Code and Creating a
Lambda Function (p. 10).

PowerShell

• Your own authoring environment
• PowerShell Core 6.0 (see Installing PowerShell Core)
• .NET Core 2.1 SDK (see .NET downloads)
• AWSLambdaPSCore Module (see PowerShell Gallery)

In addition, regardless of the language you choose, there is a pattern to writing Lambda function code.
For example, how you write the handler method of your Lambda function (that is, the method that
AWS Lambda ﬁrst calls when it begins executing the code), how you pass events to the handler, what
statements you can use in your code to generate logs in CloudWatch Logs, how to interact with AWS
Lambda runtime and obtain information such as the time remaining before timeout, and how to handle
exceptions. The Programming Model (p. 18) section provides information for each of the supported
languages.

Note

After you familiarize yourself with AWS Lambda, see the Use Cases (p. 114), which provide
step-by-step instructions to help you explore the end-to-end experience.

9

AWS Lambda Developer Guide
Deploying Code and Creating a Lambda Function

Deploying Code and Creating a Lambda Function
To create a Lambda function, you ﬁrst package your code and dependencies in a deployment package.
Then, you upload the deployment package to AWS Lambda to create your Lambda function.
Topics
• Creating a Deployment Package – Organizing Code and Dependencies (p. 10)
• Uploading a Deployment Package – Creating a Lambda Function (p. 10)
• Testing a Lambda Function (p. 10)

Creating a Deployment Package – Organizing Code and
Dependencies
You must ﬁrst organize your code and dependencies in certain ways and create a deployment package.
Instructions to create a deployment package vary depending on the language you choose to author
the code. For example, you can use build plugins such as Jenkins (for Node.js and Python), and Maven
(for Java) to create the deployment packages. For more information, see Creating a Deployment
Package (p. 19).
When you create Lambda functions using the console, the console creates the deployment package for
you, and then uploads it to create your Lambda function.

Uploading a Deployment Package – Creating a Lambda Function
AWS Lambda provides the CreateFunction (p. 368) operation, which is what you use to create a Lambda
function. You can use the AWS Lambda console, AWS CLI, and AWS SDKs to create a Lambda function.
Internally, all of these interfaces call the CreateFunction operation.
In addition to providing your deployment package, you can provide conﬁguration information when you
create your Lambda function including the compute requirements of your Lambda function, the name
of the handler method in your Lambda function, and the runtime, which depends on the language you
chose to author your code. For more information, see Working with Lambda Functions (p. 8).

Testing a Lambda Function
If your Lambda function is designed to process events of a speciﬁc type, you can use sample event data
to test your Lambda function using one of the following methods:
• Test your Lambda function in the console.
• Test your Lambda function using the AWS CLI. You can use the Invoke method to invoke your Lambda
function and pass in sample event data.
• Test your Lambda function locally using the AWS SAM CLI.
The console provides sample event data. The same data is also provided in the Sample Events Published
by Event Sources (p. 79) topic, which you can use in the AWS CLI to invoke your Lambda function.

Monitoring and Troubleshooting
After your Lambda function is in production, AWS Lambda automatically monitors functions on your
behalf, reporting metrics through Amazon CloudWatch. For more information, see Accessing Amazon
CloudWatch Metrics for AWS Lambda (p. 210).

10

AWS Lambda Developer Guide
AWS Lambda-Based Application Examples

To help you troubleshoot failures in a function, Lambda logs all requests handled by your function
and also automatically stores logs that your code generates in Amazon CloudWatch Logs. For more
information, see Accessing Amazon CloudWatch Logs for AWS Lambda (p. 211).

AWS Lambda-Based Application Examples
This guide provides several examples with step-by-step instructions. If you are new to AWS Lambda, we
recommend you try the following exercises:
• Getting Started with AWS Lambda (p. 3) – The Getting Started exercise provides a console-based
experience. Sample code is provided for your preferred runtimes. You can also code within the console,
using the Code Editor and upload it to AWS Lambda, and test it using sample event data provided in
the console.
• Use Cases (p. 114) – If you cannot author your code using the console, you must create your own
deployment packages and use the AWS CLI (or SDKs) to create your Lambda function. For more
information, see Authoring Code for Your Lambda Function (p. 8). Most examples in the Use Cases
section use the AWS CLI. If you are new to AWS Lambda, we recommend that you try one of these
exercises.

Creating Functions Using the AWS Lambda
Console Editor
The code editor in the AWS Lambda console enables you to write, test, and view the execution results of
your Lambda function code.
The code editor includes the menu bar, windows, and the editor pane.

You use the menu bar to run common commands. For more information, see Using the Menu
Bar (p. 16).
You use windows to work with ﬁles, folders, and other commands. For more information, see Working
with Files and Folders (p. 11) and Working with Commands (p. 17).
You use the editor pane to write code. For more information, see Working with Code (p. 13).

Working with Files and Folders
You can use the Environment window in the code editor to create, open, and manage ﬁles for your
function.

11

AWS Lambda Developer Guide
Working with Files and Folders

To show or hide the Environment window, choose the Environment button. If the Environment button
is not visible, choose Window, Environment on the menu bar.

To open a single ﬁle and show its contents in the editor pane, double-click the ﬁle in the Environment
window.
To open multiple ﬁles and show their contents in the editor pane, choose the ﬁles in the Environment
window. Right-click the selection, and then choose Open.
To create a new ﬁle, do one of the following:
• In the Environment window, right-click the folder where you want the new ﬁle to go, and then choose
New File. Type the ﬁle's name and extension, and then press Enter.
• Choose File, New File on the menu bar. When you're ready to save the ﬁle, choose File, Save or File,
Save As on the menu bar. Then use the Save As dialog box that displays to name the ﬁle and choose
where to save it.
• In the tab buttons bar in the editor pane, choose the + button, and then choose New File. When you're
ready to save the ﬁle, choose File, Save or File, Save As on the menu bar. Then use the Save As dialog
box that displays to name the ﬁle and choose where to save it.

12

AWS Lambda Developer Guide
Working with Code

To create a new folder, right-click the folder in the Environment window where you want the new
folder to go, and then choose New Folder. Type the folder's name, and then press Enter.
To save a ﬁle, with the ﬁle open and its contents visible in the editor pane, choose File, Save on the
menu bar.
To rename a ﬁle or folder, right-click the ﬁle or folder in the Environment window. Type the
replacement name, and then press Enter.
To delete ﬁles or folders, choose the ﬁles or folders in the Environment window. Right-click the
selection, and then choose Delete. Then conﬁrm the deletion by choosing Yes (for a single selection) or
Yes to All.
To cut, copy, paste, or duplicate ﬁles or folders, choose the ﬁles or folders in the Environment window.
Right-click the selection, and then choose Cut, Copy, Paste, or Duplicate, respectively.
To collapse folders, choose the gear icon in the Environment window, and then choose Collapse All
Folders.

To show or hide hidden ﬁles, choose the gear icon in the Environment window, and then choose Show
Hidden Files.
You can also create, open, and manage ﬁles by using the Commands window. For more information, see
Working with Commands (p. 17).

Working with Code
Use the editor pane in the code editor to view and write code.

13

AWS Lambda Developer Guide
Working with Code

Working with Tab Buttons
Use the tab buttons bar to select, view, and create ﬁles.

To display an open ﬁle's contents, do one of the following:
• Choose the ﬁle's tab.
• Choose the drop-down menu button in the tab buttons bar, and then choose the ﬁle's name.

To close an open ﬁle, do one of the following:
• Choose the X icon in the ﬁle's tab.
• Choose the ﬁle's tab. Then choose the drop-down menu button in the tab buttons bar, and choose
Close Pane.
To close multiple open ﬁles, choose the drop-down menu in the tab buttons bar, and then choose Close
All Tabs in All Panes or Close All But Current Tab as needed.

14

AWS Lambda Developer Guide
Working with Code

To create a new ﬁle, choose the + button in the tab buttons bar, and then choose New File. When you're
ready to save the ﬁle, choose File, Save or File, Save As on the menu bar. Then use the Save As dialog
box that displays to name the ﬁle and choose where to save it.

Working with the Status Bar
Use the status bar to move quickly to a line in the active ﬁle and to change how code is displayed.

To move quickly to a line in the active ﬁle, choose the line selector, type the line number to go to, and
then press Enter.

To change the code color scheme in the active ﬁle, choose the code color scheme selector, and then
choose the new code color scheme.

To change in the active ﬁle whether soft tabs or spaces are used, the tab size, or whether to convert
to spaces or tabs, choose the spaces and tabs selector, and then choose the new settings.

15

AWS Lambda Developer Guide
Using the Menu Bar

To change for all ﬁles whether to show or hide invisible characters or the gutter, auto-pair brackets
or quotes, wrap lines, or the font size, choose the gear icon, and then choose the new settings.

Using the Menu Bar
You can use the menu bar to run common commands.

To hide the menu bar, choose the up arrow in the menu bar.

To show the menu bar if it is hidden, choose the down arrow in the menu bar.

For a list of what the commands do, see the Menu Commands Reference in the AWS Cloud9 User Guide.
Note that some of the commands listed in that reference are not available in the code editor.

16

AWS Lambda Developer Guide
Working in Fullscreen Mode

You can also run commands by using the Commands window. For more information, see Working with
Commands (p. 17).

Working in Fullscreen Mode
You can expand the code editor to get more room to work with your code.
To expand the code editor to the edges of the web browser window, choose the Toggle fullscreen
button in the menu bar.

To shrink the code editor to its original size, choose the Toggle fullscreen button again.
In fullscreen mode, additional options are displayed on the menu bar: Save and Test. Choosing Save
saves the function code. Choosing Test or Conﬁgure Events enables you to create or edit the function's
test events.

Working with Preferences
You can change various code editor settings such as which coding hints and warnings are displayed, code
folding behaviors, code autocompletion behaviors, and much more.
To change code editor settings, choose the Preferences gear icon in the menu bar.

For a list of what the settings do, see the following references in the AWS Cloud9 User Guide.
• Project Setting Changes You Can Make
• User Setting Changes You Can Make
Note that some of the settings listed in those references are not available in the code editor.

Working with Commands
You can use the Commands window to run various commands such as those found on the menu bar, in
the Environment window, in the editor pane.
To show or hide the Commands window, choose the Commands button. If the Commands button is
not visible, choose Window, Commands on the menu bar.

17

AWS Lambda Developer Guide
Programming Model

To run a command, choose it in the Commands window. To ﬁnd a command, type some or all of the
command's name in the search box.

For a list of what the commands do, see the Commands Reference in the AWS Cloud9 User Guide. Note
that some of the commands listed in that reference are not available in the code editor.

Programming Model
You write code for your Lambda function in one of the languages AWS Lambda supports. Regardless of
the language you choose, there is a common pattern to writing code for a Lambda function that includes
the following core concepts:
• Handler – Handler is the function AWS Lambda calls to start execution of your Lambda function. You
identify the handler when you create your Lambda function. When a Lambda function is invoked, AWS
Lambda starts executing your code by calling the handler function. AWS Lambda passes any event
data to this handler as the ﬁrst parameter. Your handler should process the incoming event data and
may invoke any other functions/methods in your code.
• Context – AWS Lambda also passes a context object to the handler function, as the second
parameter. Via this context object your code can interact with AWS Lambda. For example, your code
can ﬁnd the execution time remaining before AWS Lambda terminates your Lambda function.
In addition, for languages such as Node.js, there is an asynchronous platform that uses callbacks. AWS
Lambda provides additional methods on this context object. You use these context object methods to
tell AWS Lambda to terminate your Lambda function and optionally return values to the caller.
• Logging – Your Lambda function can contain logging statements. AWS Lambda writes these logs to
CloudWatch Logs. Speciﬁc language statements generate log entries, depending on the language you
use to author your Lambda function code.
Logging is subject to CloudWatch Logs limits. Log data can be lost due to throttling or, in some cases,
when the execution context (p. 93) is terminated.
• Exceptions – Your Lambda function needs to communicate the result of the function execution to
AWS Lambda. Depending on the language you author your Lambda function code, there are diﬀerent
ways to end a request successfully or to notify AWS Lambda an error occurred during execution. If you
invoke the function synchronously, then AWS Lambda forwards the result back to the client.
• Concurrency – When your function is invoked more quickly than a single instance of your function can
process events, Lambda scales by running additional instances. Each instance of your function handles
only one request at a time, so you don't need to worry about synchronizing threads or processes. You
can, however, use asynchronous language features to process batches of events in parallel, and save
data to the /tmp directory for use in future invocations on the same instance.

18

AWS Lambda Developer Guide
Deployment Package

Your Lambda function code must be written in a stateless style, and have no aﬃnity with the underlying
compute infrastructure. Your code should expect local ﬁle system access, child processes, and similar
artifacts to be limited to the lifetime of the request. Persistent state should be stored in Amazon S3,
Amazon DynamoDB, or another cloud storage service. Requiring functions to be stateless enables AWS
Lambda to launch as many copies of a function as needed to scale to the incoming rate of events and
requests. These functions may not always run on the same compute instance from request to request,
and a given instance of your Lambda function may be used more than once by AWS Lambda. For more
information, see Best Practices for Working with AWS Lambda Functions (p. 245).
• Building Lambda Functions with Node.js (p. 250)
• Building Lambda Functions with Python (p. 262)
• Building Lambda Functions with Java (p. 275)
• Building Lambda Functions with Go (p. 304)
• Building Lambda Functions with C# (p. 316)
• Building Lambda Functions with PowerShell (p. 336)

Creating a Deployment Package
To create a Lambda function you ﬁrst create a Lambda function deployment package, a .zip or .jar ﬁle
consisting of your code and any dependencies. When creating the zip, include only the code and its
dependencies, not the containing folder. You will then need to set the appropriate security permissions
for the zip package.
• AWS Lambda Deployment Package in Node.js (p. 250)
• AWS Lambda Deployment Package in Python (p. 262)
• AWS Lambda Deployment Package in Java (p. 276)
• AWS Lambda Deployment Package in Go (p. 304)
• AWS Lambda Deployment Package in C# (p. 316)
• AWS Lambda Deployment Package in PowerShell (p. 336)

Permissions Policies on Lambda Deployment
Packages
Zip packages uploaded with incorrect permissions may cause execution failure. AWS Lambda requires
global read permissions on code ﬁles and any dependent libraries that comprise your deployment
package. To ensure permissions are not restricted to your user account, you can check using the
following samples:
• Linux/Unix/OSX environments: Use zipinfo as shown in the sample below:
$ zipinfo test.zip
Archive: test.zip
Zip file size: 473 bytes, number of entries: 2
-r-------- 3.0 unx
0 bx stor 17-Aug-10 09:37 exlib.py
-r-------- 3.0 unx
234 tx defN 17-Aug-10 09:37 index.py
2 files, 234 bytes uncompressed, 163 bytes compressed: 30.3%

The -r-------- indicates that only the ﬁle owner has read permissions, which can cause Lambda
function execution failures. The following indicates what you would see if there are requisite global
read permissions:

19

AWS Lambda Developer Guide
Accessing AWS Resources

$ zipinfo test.zip
Archive: test.zip
Zip file size: 473 bytes, number of entries: 2
-r--r--r-- 3.0 unx
0 bx stor 17-Aug-10 09:37 exlib.py
-r--r--r-- 3.0 unx
234 tx defN 17-Aug-10 09:37 index.py
2 files, 234 bytes uncompressed, 163 bytes compressed: 30.3%

To ﬁx this recursively, run the following command:
$ chmod 644 $(find /tmp/package_contents -type f)
$ chmod 755 $(find /tmp/package_contents -type d)

• The ﬁrst command changes all ﬁles in /tmp/package_contents to have read/write permissions to
owners, read to group and global.
• The second command cascades the same permissions for directories.

Accessing AWS Resources from a Lambda Function
Lambda does not enforce any restrictions on your function logic – if you can code for it, you can run it
within a Lambda function. As part of your function, you may need to call other APIs, or access other AWS
services like databases.

Accessing AWS Services
To access other AWS services, you can use the AWS SDK. AWS Lambda automatically sets the credentials
required by the SDK to those of the IAM role associated with your function – you do not need to take any
additional steps. For example, here’s sample code using the Python SDK for accessing an S3 object.
import boto3
import botocore
BUCKET_NAME = 'my-bucket' # replace with your bucket name
KEY = 'my_image_in_s3.jpg' # replace with your object key
s3 = boto3.resource('s3')
try:

s3.Bucket(BUCKET_NAME).download_file(KEY, 'my_local_image.jpg')
except botocore.exceptions.ClientError as e:
if e.response['Error']['Code'] == "404":
print("The object does not exist.")
else:
raise

For convenience, AWS Lambda includes versions of the AWS SDK as part of the execution environment
so you don’t have to include it. See Lambda Execution Environment and Available Libraries (p. 92) for
the version of the included SDK. We recommend including your own copy of the AWS SDK for production
applications so you can control your dependencies.

Accessing non AWS Services
You can include any SDK to access any service as part of your Lambda function. For example, you can
include the SDK for Twilio to access information from your Twilio account. You can use AWS Lambda

20

AWS Lambda Developer Guide
Accessing Private Services or Resources

Environment Variables (p. 23) for storing the credential information for the SDKs after encrypting the
credentials.

Accessing Private Services or Resources
By default, your service or API must be accessible over the public internet for AWS Lambda to access
it. However, you may have APIs or services that are not exposed this way. Typically, you create these
resources inside Amazon Virtual Private Cloud (Amazon VPC) so that they cannot be accessed over
the public Internet. These resources could be AWS service resources, such as Amazon Redshift data
warehouses, Amazon ElastiCache clusters, or Amazon RDS instances. They could also be your own
services running on your own EC2 instances. By default, resources within a VPC are not accessible from
within a Lambda function.
AWS Lambda runs your function code securely within a VPC by default. However, to enable your
Lambda function to access resources inside your private VPC, you must provide additional VPC-speciﬁc
conﬁguration information that includes VPC subnet IDs and security group IDs. AWS Lambda uses this
information to set up elastic network interfaces (ENIs) that enable your function to connect securely to
other resources within your private VPC.

Important

AWS Lambda does not support connecting to resources within Dedicated Tenancy VPCs. For
more information, see Dedicated VPCs.
To learn how to conﬁgure a Lambda function to access resources within a VPC, see Conﬁguring a Lambda
Function to Access Resources in an Amazon VPC (p. 52)

21

AWS Lambda Developer Guide
Basic Conﬁguration

Conﬁguring AWS Lambda Functions
You can use the AWS Lambda API or console to conﬁgure settings on your Lambda functions. Basic
function settings (p. 22) include the description, role, runtime, and role that you specify when you
create a function in the Lambda console. You can conﬁgure more settings after you create a function, or
use the API to set things like the handler name, memory allocation, and security groups during creation.
To keep secrets out of your function code, store them in the function's conﬁguration and read them from
the execution environment during initialization. Environment variables (p. 23) are always encrypted
at rest, and can be encrypted in transit as well. Use environment variables to make your function code
portable by removing connection strings, passwords, and endpoints for external resources.
Versions and aliases (p. 30) are secondary resources that you can create to manage function
deployment and invocation. Publish versions of your function to store its code and conﬁguration as a
separate resource that cannot be changed, and create an alias that points to a speciﬁc version. Then you
can conﬁgure your clients to invoke a function alias, and update the alias when you want to point the
client to a new version, instead of updating the client.
As you add libraries and other dependencies to your function, creating and uploading a deployment
package can slow down development. Use layers (p. 47) to manage your function's dependencies
independently and keep your deployment package small. You can also use layers to share your own
libraries with other customers and use publicly available layers with your functions.
To use your Lambda function with AWS resources in an Amazon VPC, conﬁgure it with security groups
and subnets to create a VPC connection (p. 52). Lambda uses elastic network interfaces (ENIs) to
create the connection, so you need to ensure that your account has enough ENI capacity to handle the
number of connections made as your function scales up under load.
Topics
• Basic AWS Lambda Function Conﬁguration (p. 22)
• AWS Lambda Environment Variables (p. 23)
• AWS Lambda Function Versioning and Aliases (p. 30)
• AWS Lambda Layers (p. 47)
• Conﬁguring a Lambda Function to Access Resources in an Amazon VPC (p. 52)

Basic AWS Lambda Function Conﬁguration
A Lambda function consists of code and any associated dependencies. In addition, a Lambda
function also has conﬁguration information associated with it. Initially, you specify the conﬁguration
information when you create a Lambda function. Lambda provides an API for you to update some of the
conﬁguration data.

To conﬁgure function settings
1.

Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

2.

Choose a function.

3.

Settings are on the ﬁrst page shown, beneath the Function code editor. If you choose other
resources in the Designer panel, choose the function node to return to function settings.

4.

Conﬁgure any of the available options and then choose Save.

22

AWS Lambda Developer Guide
Environment Variables

Settings
• Memory – Specify the amount of memory you want to allocate for your Lambda function. AWS
Lambda allocates CPU power proportional to the memory by using the same ratio as a general
purpose Amazon EC2 instance type, such as an M3 type. For example, if you allocate 256 MB memory,
your Lambda function will receive twice the CPU share than if you allocated only 128 MB.
You can update the conﬁguration and request additional memory in 64 MB increments from 128MB to
3008 MB. For information about relevant limits, see AWS Lambda Limits (p. 249).
You can also update the memory size of your functions using the following AWS CLI command.
$ aws lambda update-function-configuration --function-name myfunction --memory-size 256

• Timeout – You pay for the AWS resources that are used to run your Lambda function. To prevent
your Lambda function from running indeﬁnitely, you specify a timeout. When the speciﬁed timeout
is reached, AWS Lambda terminates execution of your Lambda function. We recommend you set this
value based on your expected execution time. The default timeout is 3 seconds.

Note

You can invoke a Lambda function synchronously either by calling the Invoke operation or
by using an AWS SDK in your preferred runtime. If you anticipate a long-running Lambda
function, your client may time out before function execution completes. To avoid this, update
the client timeout or your SDK conﬁguration. For more information, see Invoke (p. 410).
• Execution role – The role that AWS Lambda assumes when it executes the Lambda function. For more
information, see AWS Lambda Execution Role (p. 222).
• Handler name – The handler method is the entry point that executes your Lambda function code and
any event source dependencies that you have included as part of your Lambda function. This setting
appears in the function code editor.

AWS Lambda Environment Variables
Environment variables for Lambda functions enable you to dynamically pass settings to your function
code and libraries, without making changes to your code. Environment variables are key-value pairs that
you create and modify as part of your function conﬁguration, using either the AWS Lambda Console,
the AWS Lambda CLI or the AWS Lambda SDK. AWS Lambda then makes these key value pairs available
to your Lambda function code using standard APIs supported by the language, like process.env for
Node.js functions.
You can use environment variables to help libraries know what directory to install ﬁles in, where to
store outputs, store connection and logging settings, and more. By separating these settings from the
application logic, you don't need to update your function code when you need to change the function
behavior based on diﬀerent settings.

Setting Up
Suppose you want a Lambda function to behave diﬀerently as it moves through lifecycle stages from
development to deployment. For example, the dev, test, and production stages can contain databases
that the function needs to connect to that require diﬀerent connection information and use diﬀerent
table names. You can create environment variables to reference the database names, connection
information or table names and set the value for the function based on the stage in which it’s executing
(for example, development, test, production) while your function code remains unchanged.
The following screenshots show how to modify your function's conﬁguration using the AWS console. The
ﬁrst screenshot conﬁgures the settings for the function corresponding to a test stage. The second one
conﬁgures settings for a production stage.

23

AWS Lambda Developer Guide
Setting Up

24

AWS Lambda Developer Guide
Rules for Naming Environment Variables

Note the Encryption conﬁguration section. You will learn more about using this in the Create a Lambda
Function Using Environment Variables To Store Sensitive Information (p. 28) tutorial.
You can also use the AWS CLI to create Lambda functions that contain environment variables. For more
details, see the CreateFunction (p. 368) and UpdateFunctionConﬁguration (p. 472) APIs. Environment
variables are also supported when creating and updating functions using AWS CloudFormation.
Environment variables can also be used to conﬁgure settings speciﬁc to the language runtime or a library
included in your function. For example, you can modify PATH to specify a directory where executables
are stored. You can also set runtime-speciﬁc environment variables, such as PYTHONPATH for Python or
NODE_PATH for Node.js.
The following example creates a new Lambda function that sets the LD_LIBRARY_PATH environment
variable, which is used to specify a directory where shared libraries are dynamically loaded at runtime.
In this example, the Lambda function code uses the shared library in the /usr/bin/test/lib64
directory. Note that the Runtime parameter uses nodejs6.10 but you can also specify nodejs8.10.
$ aws lambda create-function --function-name myTestFunction \
--zip-file fileb://package.zip \
--role role-arn \
--environment Variables="{LD_LIBRARY_PATH=/usr/bin/test/lib64}" \
--handler index.handler --runtime nodejs6.10

Rules for Naming Environment Variables
There is no limit to the number of environment variables you can create as long as the total size of the
set does not exceed 4 KB.
Other requirements include:
• Must start with letters [a-zA-Z].

25

AWS Lambda Developer Guide
Environment Variables and Function Versioning

• Can only contain alphanumeric characters and underscores ([a-zA-Z0-9_].
In addition, there are a speciﬁc set of keys that AWS Lambda reserves. If you try to set values for any of
these reserved keys, you will receive an error message indicating that the action is not allowed. For more
information on these keys, see Environment Variables Available to Lambda Functions (p. 92).

Environment Variables and Function Versioning
Function versioning provides a way to manage your Lambda function code by enabling you to publish
one or more versions of your Lambda function as it proceeds from development to test to production.
For each version of a Lambda function that you publish, the environment variables (as well as other
function-speciﬁc conﬁgurations such as MemorySize and Timeout limit) are saved as a snapshot of that
version and those settings are immutable (cannot be changed).
As application and conﬁguration requirements evolve, you can create new versions of your Lambda
function and update the environment variables to meet those requirements prior to the newest version
being published. The current version of your function is $LATEST.
In addition, you can create aliases, which are pointers to a particular version of your function. The
advantage of aliases is that if you need to roll back to a previous function version, you point the alias to
that version, which contains the environment variables required for that version. For more information,
see AWS Lambda Function Versioning and Aliases (p. 30).

Environment Variable Encryption
When you create or update Lambda functions that use environment variables, AWS Lambda encrypts
them using the AWS Key Management Service. When your Lambda function is invoked, those values are
decrypted and made available to the Lambda code.
The ﬁrst time you create or update Lambda functions that use environment variables in a region,
a default service key is created for you automatically within AWS KMS. This key is used to encrypt
environment variables. However, should you wish to use encryption helpers and use KMS to encrypt
environment variables after your Lambda function is created, then you must create your own AWS KMS
key and choose it instead of the default key. The default key will give errors when chosen. Creating
your own key gives you more ﬂexibility, including the ability to create, rotate, disable, and deﬁne access
controls, and to audit the encryption keys used to protect your data. For more information, see the AWS
Key Management Service Developer Guide.
If you use your own key, you will be billed per AWS Key Management Service Pricing guidelines. You will
not be billed if you use the default service key provided by AWS Lambda.
If you’re using the default KMS service key for Lambda, then no additional IAM permissions are required
in your function execution role – your role will just work automatically without changes. If you’re
supplying your own (custom) KMS key, then you’ll need to add kms:Decrypt to your execution role. In
addition, the user that will be creating and updating the Lambda function must have permissions to use
the KMS key. For more information on KMS keys, see the Using Key Policies in AWS KMS.

Note

AWS Lambda authorizes your function to use the default KMS key through a user grant, which it
adds when you assign the role to the function. If you delete the role and create a new role with
the same name, you need to refresh the role's grant. Refresh the grant by re-assigning the role
to the function.

Storing Sensitive Information
As mentioned in the previous section, when you deploy your Lambda function, all the environment
variables you've speciﬁed are encrypted by default after, but not during, the deployment process. They
are then decrypted automatically by AWS Lambda when the function is invoked. If you need to store

26

AWS Lambda Developer Guide
Create a Lambda Function Using Environment Variables

sensitive information in an environment variable, we strongly suggest you encrypt that information
before deploying your Lambda function.
Fortunately, the Lambda console makes that easier for you by providing encryption helpers that leverage
AWS Key Management Service to store that sensitive information as Ciphertext. The Lambda console
also provides decryption helper code to decrypt that information for use in your in Lambda function
code. For more information, see Create a Lambda Function Using Environment Variables To Store
Sensitive Information (p. 28).

Error scenarios
If your function conﬁguration exceeds 4KB, or you use environment variable keys reserved by AWS
Lambda, then your update or create operation will fail with a conﬁguration error. During execution time,
it's possible that the encryption/decryption of environment variables can fail. If AWS Lambda is unable
to decrypt the environment variables due to an AWS KMS service exception, AWS KMS will return an
exception message explaining what the error conditions are and what, if any, remedies you can apply
to address the issue. These will be logged to your function log stream in Amazon CloudWatch logs. For
example, if the KMS key you are using to access the environment variables is disabled, you will see the
following error:
Lambda was unable to configure access to your environment variables because the KMS key
used is disabled.
Please check your KMS key settings.

Create a Lambda Function Using Environment
Variables
This section will illustrate how you can modify a Lambda function's behavior through conﬁguration
changes that require no changes to the Lambda function code.
In this tutorial, you will do the following:
• Create a deployment package with sample code that returns the value of an environment variable that
speciﬁes the name of an Amazon S3 bucket.
• Invoke a Lambda function and verify that the Amazon S3 bucket name that is returned matches the
value set by the environment variable.
• Update the Lambda function by changing the Amazon S3 bucket name speciﬁed by the environment
variable.
• Invoke the Lambda function again and verify that the Amazon S3 bucket name that is returned
matches the updated value.

Set Up the Lambda Environment
The code sample below reads the environment variable of a Lambda function that returns the name of
an Amazon S3 bucket.
1. Open a text editor and copy the following code:
var AWS = require('aws-sdk');
exports.handler = function(event, context, callback) {
var bucketName = process.env.S3_BUCKET;
callback(null, bucketName);
}

27

AWS Lambda Developer Guide
Create a Lambda Function Using Environment
Variables To Store Sensitive Information

2. Save the ﬁle as index.js.
3. Zip the index.js. ﬁle as Test_Environment_Variables.zip.

Create an Execution Role
Create an IAM role (execution role) that you can specify at the time you create your Lambda function.
1.
2.

Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
Follow the steps in IAM Roles in the IAM User Guide to create an IAM role (execution role). As you
follow the steps to create a role, note the following:
• In Select Role Type, choose AWS Service Roles, and then choose AWS Lambda.

3.

• In Attach Policy, choose the policy named AWSLambdaBasicExecutionRole.
Write down the Amazon Resource Name (ARN) of the IAM role. You need this value when you create
your Lambda function in the next step.

Create the Lambda function and Test It
In this section, you create a Lambda function containing an environment variable that speciﬁes an
Amazon S3 bucket named Test. When invoked, the function simply returns the name of the Amazon S3
bucket. Then you update the conﬁguration by changing the Amazon S3 bucket name to Prod and when
invoked again, the function returns the updated name of the Amazon S3 bucket.
To create the Lambda function, open a command prompt and run the following Lambda AWS CLI
create-function command. You need to provide the .zip ﬁle path and the execution role ARN.
$ aws lambda create-function --function-name ReturnBucketName \
--zip-file fileb://file-path/Test_Environment_Variables.zip \
--role role-arn \
--environment Variables={S3_BUCKET=Test} \
--handler index.handler --runtime nodejs8.10

Next, run the following Lambda CLI invoke command to invoke the function.
$ aws lambda invoke --function-name ReturnBucketName outputfile.txt

The Lambda function will return the name of the Amazon S3 bucket as "Test".
Next, run the following Lambda CLI update-function-configuration command to update the
Amazon S3 environment variable by pointing it to the Prod bucket.
$ aws lambda update-function-configuration --function-name ReturnBucketName \
--environment Variables={S3_BUCKET=Prod}

Run the aws lambda invoke command again using the same parameters. This time, the Lambda
function will return the Amazon S3 bucket name as Prod.

Create a Lambda Function Using Environment
Variables To Store Sensitive Information
Along with specifying conﬁguration settings for your Lambda function, you can also use environment
variables to store sensitive information, such as a database password, using AWS Key Management

28

AWS Lambda Developer Guide
Create a Lambda Function Using Environment
Variables To Store Sensitive Information

Service and the Lambda console's encryption helpers. For more information, see Environment Variable
Encryption (p. 26). The following example shows you how to do this and also how to use KMS to
decrypt that information.
This tutorial will demonstrate how you can use the Lambda console to encrypt an environment variable
containing sensitive information. Note that if you are updating an existing function, you can skip ahead
to the instruction step outlining how to Expand the Environment Variables section of Step 2: Conﬁgure
the Lambda Function (p. 29).

Step 1: Create the Lambda Function
1.

Sign in to the AWS Management Console and open the AWS Lambda console at https://
console.aws.amazon.com/lambda/.

2.

Choose Create a Lambda function.

3.

In Select blueprint, choose the Author from scratch button.

4.

In Basic information, do the following:
• In Name, specify your Lambda function name.
• In Role, choose Choose an existing role.
• In Existing role, choose lambda_basic_execution.

Note

If the policy of the execution role does not have the decrypt permission, you will need
add it.
• Choose Create function.

Step 2: Conﬁgure the Lambda Function
1.

Under Conﬁguration, specify the Runtime of your choice.

2.

Under the Lambda function code section you can take advantage of the Edit code inline option to
replace the Lambda function handler code with your custom code.

3.

Note the Triggers tab. Under the Triggers page, you can optionally choose a service that
automatically triggers your Lambda function by choosing the Add trigger button and then choosing
the gray box with ellipses (...) to display a list of available services. For this example, do not conﬁgure
a trigger and choose Conﬁguration.

4.

Note the Monitoring tab. This page will provide immediate CloudWatch metrics for your Lambda
function invocations, as well as links to other helpful guides, including Using AWS X-Ray (p. 214).

5.

Expand the Environment variables section.

6.

Enter your key-value pair. Expand the Encryption conﬁguration section. Note that Lambda provides
a default service key under KMS key to encrypt at rest which encrypts your information after it has
been uploaded. If the information you provided is sensitive, you can additionally check the Enable
helpers for encryption in transit checkbox and supply a custom key. This masks the value you
entered and results in a call to AWS KMS to encrypt the value and return it as Ciphertext. If you
haven't created a KMS key for your account, you will be provided a link to the AWS IAM console to
create one. The account must have have encrypt and decrypt permissions for that key. Note that
the Encrypt button toggles to Decrypt after you choose it. This aﬀords you the option to update the
information. Once you have done that, choose the Encrypt button.
The Code button provides sample decrypt code speciﬁc to the runtime of your Lambda function that
you can use with your application.

Note

You cannot use the default Lambda service key for encrypting sensitive information on the
client side. For more information, see Environment Variable Encryption (p. 26).
29

AWS Lambda Developer Guide
Versioning

AWS Lambda Function Versioning and Aliases
By using versioning, you can manage your in-production function code in AWS Lambda better. When
you use versioning in AWS Lambda, you can publish one or more versions of your Lambda function. As
a result, you can work with diﬀerent variations of your Lambda function in your development workﬂow,
such as development, beta, and production.
Each Lambda function version has a unique Amazon Resource Name (ARN). After you publish a version, it
is immutable (that is, it can't be changed).
AWS Lambda also supports creating aliases for each of your Lambda function versions. Conceptually,
an AWS Lambda alias is a pointer to a speciﬁc Lambda function version. It's also a resource similar to a
Lambda function, and each alias has a unique ARN. Each alias maintains an ARN for the function version
to which it points. An alias can only point to a function version, not to another alias. Unlike versions,
which are immutable, aliases are mutable (that is, they can be changed). You can update aliases to point
to diﬀerent versions of functions.

Aliases enable you to abstract the process of promoting new Lambda function versions into production
from the mapping of the Lambda function version and its event source.
For example, suppose Amazon S3 is the event source that invokes your Lambda function when new
objects are created in a bucket. When Amazon S3 is your event source, you store the event source
mapping information in the bucket notiﬁcation conﬁguration. In that conﬁguration, you can identify the
Lambda function ARN that Amazon S3 can invoke. However, in this case each time you publish a new
version of your Lambda function you need to update the notiﬁcation conﬁguration so that Amazon S3
invokes the correct version.
In contrast, instead of specifying the function ARN, suppose that you specify an alias ARN in the
notiﬁcation conﬁguration (for example, PROD alias ARN). As you promote new versions of your Lambda
function into production, you only need to update the PROD alias to point to the latest stable version.
You don't need to update the notiﬁcation conﬁguration in Amazon S3.

30

AWS Lambda Developer Guide
Versioning

The same applies when you need to roll back to a previous version of your Lambda function. In this
scenario, you just update the PROD alias to point to a diﬀerent function version. There is no need to
update event source mappings.
We recommend that you use versioning and aliases to deploy your Lambda functions when building
applications with multiple dependencies and developers involved.
Topics
• Introduction to AWS Lambda Versioning (p. 31)
• Introduction to AWS Lambda Aliases (p. 34)
• Versioning, Aliases, and Resource Policies (p. 42)
• Managing Versioning Using the AWS Management Console, the AWS CLI, or Lambda API
Operations (p. 43)
• Traﬃc Shifting Using Aliases (p. 45)

Introduction to AWS Lambda Versioning
Following, you can ﬁnd how to create a Lambda function and publish a version from it. You can also
ﬁnd how to update function code and conﬁguration information when you have one or more published
versions. In addition, you can ﬁnd information on how to delete function versions, either speciﬁc versions
or an entire Lambda function with all of its versions and associated aliases.

Creating a Lambda Function (the $LATEST Version)
When you create a Lambda function, there is only one version—the $LATEST version.

You can refer to this function using its Amazon Resource Name (ARN). There are two ARNs associated
with this initial version:
• Qualiﬁed ARN – The function ARN with the version suﬃx.
arn:aws:lambda:aws-region:acct-id:function:helloworld:$LATEST

• Unqualiﬁed ARN – The function ARN without the version suﬃx.
You can use this unqualiﬁed ARN in all relevant operations. However, you cannot use it to create an
alias. For more information, see Introduction to AWS Lambda Aliases (p. 34).
The unqualiﬁed ARN has its own resource policies.
arn:aws:lambda:aws-region:acct-id:function:helloworld

31

AWS Lambda Developer Guide
Versioning

Note

Unless you choose to publish versions, the $LATEST function version is the only Lambda
function version that you have. You can use either the qualiﬁed or unqualiﬁed ARN in your event
source mapping to invoke the $LATEST version.
The following is an example response for a CreateFunction API call.
{

}

"CodeSize": 287,
"Description": "test function."
"FunctionArn": "arn:aws:lambda:aws-region:acct-id:function:helloworld",
"FunctionName": "helloworld",
"Handler": "helloworld.handler",
"LastModified": "2015-07-16T00:34:31.322+0000",
"MemorySize": 128,
"Role": "arn:aws:iam::acct-id:role/lambda_basic_execution",
"Runtime": "nodejs6.10",
"Timeout": 3,
"CodeSHA256": "OjRFuuHKizEE8tHFIMsI+iHR6BPAfJ5S0rW31Mh6jKg=",
"Version": "$LATEST"

For more information, see CreateFunction (p. 368).
In this response, AWS Lambda returns the unqualiﬁed ARN of the newly created function and also its
version, $LATEST. The response also shows that the Version is $LATEST. The CodeSha256 is the
checksum of the deployment package that you uploaded.

Publishing an AWS Lambda Function Version
When you publish a version, AWS Lambda makes a snapshot copy of the Lambda function code (and
conﬁguration) in the $LATEST version. A published version is immutable. That is, you can't change the
code or conﬁguration information. The new version has a unique ARN that includes a version number
suﬃx as shown following.

You can publish a version by using any of the following methods:
• Publish a version explicitly – You can use the PublishVersion API operation to explicitly publish
a version. For more information, see PublishVersion (p. 440). This operation creates a new version
using the code and conﬁguration in the $LATEST version.
• Publish a version at the time you create or update a Lambda function – You can also use the
CreateFunction or UpdateFunctionCode requests to publish a version by adding the optional
publish parameter in the request:
• Specify the publish parameter in your CreateFunction request to create a new Lambda
function (the $LATEST version). You can then immediately publish the new function by creating

32

AWS Lambda Developer Guide
Versioning

a snapshot and assigning it to be version 1. For more information about CreateFunction, see
CreateFunction (p. 368).
• Specify the publish parameter in your UpdateFunctionCode request to update the code in the
$LATEST version. You can then publish a version from the $LATEST. For more information about
UpdateFunctionCode, see UpdateFunctionCode (p. 466).
If you specify the publish parameter at the time you create a Lambda function, the function
conﬁguration information that AWS Lambda returns in response shows the version number of the
newly published version. In the following example, the version is 1.
{

}

"CodeSize": 287,
"Description": "test function."
"FunctionArn": "arn:aws:lambda:aws-region:acct-id:function:helloworld",
"FunctionName": "helloworld",
"Handler": "helloworld.handler",
"LastModified": "2015-07-16T00:34:31.322+0000",
"MemorySize": 128,
"Role": "arn:aws:iam::acct-id:role/lambda_basic_execution",
"Runtime": "nodejs6.10",
"Timeout": 3,
"CodeSHA256": "OjRFuuHKizEE8tHFIMsI+iHR6BPAfJ5S0rW31Mh6jKg=",
"Version": "1"

Note

Lambda only publishes a new version if the code hasn't yet been published or if the code has
changed when compared against the $LATEST version. If there is no change, the $LATEST
published version is returned.
We recommend that you publish a version at the same time that you create your Lambda function or
update your Lambda function code. This recommendation especially applies when multiple developers
contribute to the same Lambda function development. You can use the publish parameter in your
request to do this.
When you have multiple developers working on a project, you can have a scenario where developer A
creates a Lambda function ($LATEST version). Before developer A publishes this version, developer B
might update the code (the deployment package) associated with the $LATEST version. In this case, you
lose the original code that developer A uploaded. When both developers add the publish parameter, it
prevents the race condition described.
Each version of a Lambda function is a unique resource with a Amazon Resource Name (ARN). The
following example shows the ARN of version number 1 of the helloworld Lambda function.
arn:aws:lambda:aws-region:acct-id:function:helloworld:1

You can publish multiple versions of a Lambda function. Each time you publish a version, AWS Lambda
copies $LATEST version (code and conﬁguration information) to create a new version. When you publish
additional versions, AWS Lambda assigns a monotonically increasing sequence number for versioning,
even if the function was deleted and recreated. Version numbers are never reused, even for a function
that has been deleted and recreated. This approach means that the consumer of a function version can
depend on the executable of that version to never change (except if it's deleted).
If you want to reuse a qualiﬁer, use aliases with your versions. Aliases can be deleted and re-created with
the same name.

33

AWS Lambda Developer Guide
Aliases

Updating Lambda Function Code and Conﬁguration
AWS Lambda maintains your latest function code in the $LATEST version. When you update your
function code, AWS Lambda replaces the code in the $LATEST version of the Lambda function. For more
information, see UpdateFunctionCode (p. 466).
You have the following options of publishing a new version as you update your Lambda function code:
• Publish a version in the same update code request – Use the UpdateFunctionCode API operation
(recommended).
• First update the code, and then explicitly publish a version – Use the PublishVersion API
operation.
You can update code and conﬁguration information (such as description, memory size, and execution
timeout) for the $LATEST version of the Lambda function.

Deleting a Lambda Function and a Speciﬁc Version
With versioning, you have the following choices:
• Delete a speciﬁc version – You can delete a Lambda function version by specifying the version you
want to delete in your DeleteFunction request. If there are aliases that depend on this version, the
request fails. AWS Lambda deletes the version only if there are no aliases dependent on this version.
For more information about aliases, see Introduction to AWS Lambda Aliases (p. 34).
• Delete the entire Lambda function (all of its versions and aliases) – To delete the Lambda function
and all of its versions, don't specify any version in your DeleteFunction request. Doing this deletes
the entire function including all of its versions and aliases.

Introduction to AWS Lambda Aliases
You can create one or more aliases for your Lambda function. An AWS Lambda alias is like a pointer to
a speciﬁc Lambda function version. For more information about versioning, see Introduction to AWS
Lambda Versioning (p. 31).
By using aliases, you can access the Lambda function an alias is pointing to (for example, to invoke the
function) without the caller having to know the speciﬁc version the alias is pointing to.
AWS Lambda aliases enable the following use cases:
• Easier support for promotion of new versions of Lambda functions and rollback when needed –
After initially creating a Lambda function (the $LATEST version), you can publish a version 1 of it.

34

AWS Lambda Developer Guide
Aliases

By creating an alias named PROD that points to version 1, you can now use the PROD alias to invoke
version 1 of the Lambda function.
Now, you can update the code (the $LATEST version) with all of your improvements, and then
publish another stable and improved version (version 2). You can promote version 2 to production by
remapping the PROD alias so that it points to version 2. If you ﬁnd something wrong, you can easily
roll back the production version to version 1 by remapping the PROD alias so that it points to version
1.
• Simplify management of event source mappings – Instead of using Amazon Resource Names (ARNs)
for Lambda function in event source mappings, you can use an alias ARN. This approach means that
you don't need to update your event source mappings when you promote a new version or roll back to
a previous version.
Both the Lambda function and alias are AWS Lambda resources, and like all other AWS resources they
both have unique ARNs. The following example shows a Lambda function (the $LATEST version), with
one published version. Each version has an alias pointing to it.

You can access the function using either the function ARN or the alias ARN.
• Because the function version for an unqualiﬁed function always maps to $LATEST, you can access it
using the qualiﬁed or unqualiﬁed function ARN. The following shows a qualiﬁed function ARN with the
$LATEST version suﬃx.
arn:aws:lambda:aws-region:acct-id:function:helloworld:$LATEST

• When using any of the alias ARNs, you are using a qualiﬁed ARN. Each alias ARN has an alias name
suﬃx.
arn:aws:lambda:aws-region:acct-id:function:helloworld:PROD
arn:aws:lambda:aws-region:acct-id:function:helloworld:BETA
arn:aws:lambda:aws-region:acct-id:function:helloworld:DEV

35

AWS Lambda Developer Guide
Aliases

AWS Lambda provides the following API operations for you to create and manage aliases:
• CreateAlias (p. 360)
• UpdateAlias (p. 458)
• GetAlias (p. 389)
• ListAliases (p. 417)
• DeleteAlias (p. 376)

Example: Using Aliases to Manage Lambda Function Versions
The following is an example scenario of how to use versioning and aliases to promote new versions of
Lambda functions into production.
Initially, you create a Lambda function.
The function you create is the $LATEST version. You also create an alias (DEV, for development)
that points to the newly created function. Developers can use this alias to test the function with the
event sources in a development environment.

You then test the function version using event sources in a beta environment in a stable way, while
continuing to develop newer versions.
You publish a version from the $LATEST and have another alias (BETA) point to it. This approach
allows you to associate your beta event sources to this speciﬁc alias. In the event source mappings,
use the BETA alias to associate your Lambda function with the event source.

36

AWS Lambda Developer Guide
Aliases

You then promote the Lambda function version in production to work with event sources in
production environment.
After testing the BETA version of the function, you can deﬁne the production version by creating
an alias that maps to version 1. In this approach, you point your production event sources to this
speciﬁc version. You do this by creating a PROD alias and using the PROD alias ARN in all of your
production event source mappings.

37

AWS Lambda Developer Guide
Aliases

You continue development, publish more versions, and test.
As you develop your code, you can update the $LATEST version by uploading updated code and
then publish to beta testing by having the BETA alias point to it. This simple remapping of the beta
alias lets you put version 2 of your Lambda function into beta without changing any of your event
sources. This approach is how aliases enable you to control which versions of your function are used
with speciﬁc event sources in your development environment.

If you want to try creating this setup using the AWS Command Line Interface, see Tutorial: Using AWS
Lambda Aliases (p. 38).

Tutorial: Using AWS Lambda Aliases
This AWS CLI-based tutorial creates Lambda function versions and aliases that point to it as described in
the Example: Using Aliases to Manage Lambda Function Versions (p. 36).
This example uses the us-west-2 (US West Oregon) region to create the Lambda function and aliases.
1.

Create a deployment package that you can upload to create your Lambda function:
a.

Open a text editor, and then copy the following code.
console.log('Loading function');
exports.handler = function(event, context, callback) {
console.log('value1 =', event.key1);
console.log('value2 =', event.key2);
console.log('value3 =', event.key3);
callback(null, "message");
};

b.

Save the ﬁle as helloworld.js.
38

AWS Lambda Developer Guide
Aliases

c.
2.

Zip the helloworld.js ﬁle as helloworld.zip.

Create an AWS Identity and Access Management (IAM) role (execution role) that you can specify at
the time you create your Lambda function:
a.

Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.

b.

Follow the steps in IAM Roles in the IAM User Guide to create an IAM role (execution role). As you
follow the steps to create a role, note the following:
• For Select Role Type, choose AWS Service Roles, and then choose AWS Lambda.
• For Attach Policy, choose the policy named AWSLambdaBasicExecutionRole.

c.
3.

Write down the Amazon Resource Name (ARN) of the IAM role. You need this value when you
create your Lambda function in the next step.

Create a Lambda function (helloworld).
aws lambda create-function \
--region region \
--function-name helloworld \
--zip-file fileb://file-path/helloworld.zip \
--role arn:aws:iam::account-id:role/lambda_basic_execution \
--handler helloworld.handler \
--runtime nodejs6.10 \
--profile adminuser

The response returns the conﬁguration information showing $LATEST as the function version as
shown in the following example response.
{

}

4.

"CodeSha256": "OjRFuuHKizEE8tHFIMsI+iHR6BPAfJ5S0rW31Mh6jKg=",
"FunctionName": "helloworld",
"CodeSize": 287,
"MemorySize": 128,
"FunctionArn": "arn:aws:lambda:us-west-2:account-id:function:helloworld",
"Version": "$LATEST",
"Role": "arn:aws:iam::account-id:role/lambda_basic_execution",
"Timeout": 3,
"LastModified": "2015-09-30T18:39:53.873+0000",
"Handler": "helloworld.handler",
"Runtime": "nodejs6.10",
"Description": ""

Create an alias (DEV) that points to the $LATEST version of the helloworld Lambda function.
aws lambda create-alias \
--region region \
--function-name helloworld \
--description "sample alias" \
--function-version "\$LATEST" \
--name DEV \
--profile adminuser

The response returns the alias information, including the function version it points to and the
alias ARN. The ARN is the same as the function ARN with an alias name suﬃx. The following is an
example response.
{

"AliasArn": "arn:aws:lambda:us-west-2:account-id:function:helloworld:DEV",

39

AWS Lambda Developer Guide
Aliases

}

5.

"FunctionVersion": "$LATEST",
"Name": "DEV",
"Description": "sample alias"

Publish a version of the helloworld Lambda function.
aws lambda publish-version \
--region region \
--function-name helloworld \
--profile adminuser

The response returns conﬁguration information of the function version, including the version
number, and the function ARN with the version suﬃx. The following is an example response.
{

}

6.

"CodeSha256": "OjRFuuHKizEE8tHFIMsI+iHR6BPAfJ5S0rW31Mh6jKg=",
"FunctionName": "helloworld",
"CodeSize": 287,
"MemorySize": 128,
"FunctionArn": "arn:aws:lambda:us-west-2:account-id:function:helloworld:1",
"Version": "1",
"Role": "arn:aws:iam::account-id:role/lambda_basic_execution",
"Timeout": 3,
"LastModified": "2015-10-03T00:48:00.435+0000",
"Handler": "helloworld.handler",
"Runtime": "nodejs6.10
",
"Description": ""

Create an alias (BETA) for the for the helloworld Lambda function version 1.
aws lambda create-alias \
--region region \
--function-name helloworld \
--description "sample alias" \
--function-version 1 \
--name BETA \
--profile adminuser

Now you have two aliases for the helloworld function. The DEV alias points to the $LATEST
function version, and the BETA alias points to version 1 of the Lambda function.
7.

Suppose that you want to put the version 1 of the helloworld function in production. Create
another alias (PROD) that points to version 1.
aws lambda create-alias \
--region region \
--function-name helloworld \
--description "sample alias" \
--function-version 1 \
--name PROD \
--profile adminuser

At this time, you have both the BETA and PROD aliases pointing to version 1 of the Lambda function.
8.

You can now publish a newer version (for example, version 2), but ﬁrst you need to update your code
and upload a modiﬁed deployment package. If the $LATEST version is not changed, you cannot
publish more than one version of it. Assuming you updated the deployment package, uploaded it,
40

AWS Lambda Developer Guide
Aliases

and published version 2, you can now change the BETA alias to point to version 2 of the Lambda
function.
aws lambda update-alias \
--region region \
--function-name helloworld \
--function-version 2 \
--name BETA \
--profile adminuser

Now you have three aliases pointing to a diﬀerent version of the Lambda function (DEV alias points
to the $LATEST version, BETA alias points to version 2, and the PROD alias points to version 1 of the
Lambda function.
For information about using the AWS Lambda console to manage versioning, see Managing Versioning
Using the AWS Management Console, the AWS CLI, or Lambda API Operations (p. 43).

Granting Permissions in a Push Model
In a push model (see AWS Lambda Event Source Mapping (p. 64)), event sources such as Amazon
S3 invoke your Lambda function. These event sources maintain a mapping that identiﬁes the function
version or alias that they invoke when events occur. Note the following:
• We recommend that you specify an existing Lambda function alias in the mapping conﬁguration (see
Introduction to AWS Lambda Aliases (p. 34)). For example, if the event source is Amazon S3, you
specify the alias ARN in the bucket notiﬁcation conﬁguration so that Amazon S3 can invoke the alias
when it detects speciﬁc events.
• In the push model, you grant event sources permissions using a resource policy that you attach to your
Lambda function. In versioning, the permissions you add are speciﬁc to the qualiﬁer that you specify in
the AddPermission request (see Versioning, Aliases, and Resource Policies (p. 42)).
For example, the following AWS CLI command grants Amazon S3 permissions to invoke the PROD
alias of the helloworld Lambda function (note that the --qualifier parameter speciﬁes the alias
name).
aws lambda add-permission \
--region region \
--function-name helloworld \
--qualifier PROD \
--statement-id 1 \
--principal s3.amazonaws.com \
--action lambda:InvokeFunction \
--source-arn arn:aws:s3:::examplebucket \
--source-account 111111111111 \
--profile adminuser

In this case, Amazon S3 is now able to invoke the PROD alias and AWS Lambda can then execute the
helloworld Lambda function version that the PROD alias points to. For this to work, you must use the
PROD alias ARN in the S3 bucket's notiﬁcation conﬁguration.
For information about how to handle Amazon S3 events, see Tutorial: Using AWS Lambda with
Amazon S3 (p. 116).

Note

If you use the AWS Lambda console to add an event source for your Lambda function, the
console adds the necessary permissions for you.

41

AWS Lambda Developer Guide
Resource Policies

Versioning, Aliases, and Resource Policies
With versioning and aliases you can access a Lambda function using various ARNs. For example, consider
the following scenario.

You can invoke for example the helloworld function version 1 using any of the following two ARNs:
• Using the qualiﬁed function ARN as shown following.
arn:aws:lambda:aws-region:acct-id:function:helloworld:1

• Using the BETA alias ARN as shown following.
arn:aws:lambda:aws-region:acct-id:function:helloworld:BETA

In a push model, event sources (such as Amazon S3 and custom applications) can invoke any of the
Lambda function versions as long you grant the necessary permissions to these event sources by using
an access policy associated with the Lambda function. For more information about the push model, see
AWS Lambda Event Source Mapping (p. 64).
Assuming that you grant permission, the next question is, "can an event source invoke a function version
using any of the associated ARNs?" The answer is, it depends on how you identiﬁed function in your add
permissions request (see AddPermission (p. 356)). The key to understanding this is that the permission
you grant apply only to the ARN used in the add permission request:
• If you use a qualiﬁed function name (such as helloworld:1), the permission is valid for invoking
the helloworld function version 1 only using its qualiﬁed ARN (using any other ARNs results in a
permission error).
• If you use an alias name (such as helloworld:BETA), the permission is valid only for invoking the
helloworld function using the BETA alias ARN (using any other ARNs results in a permission error,
including the function version ARN to which the alias points).

42

AWS Lambda Developer Guide
Managing Versioning

• If you use an unqualiﬁed function name (such as helloworld), the permission is valid only for
invoking the helloworld function using the unqualiﬁed function ARN (using any other ARNs will
result in a permission error).

Note

Note that even though the access policy is only on the unqualiﬁed ARN, the code and
conﬁguration of the invoked Lambda function is still from function version $LATEST. The
unqualiﬁed function ARN maps to the $LATEST version but the permissions you add are ARNspeciﬁc.
• If you use a qualiﬁed function name using the $LATEST version (helloworld:$LATEST), the
permission is valid for invoking the helloworld function version $LATEST only using its qualiﬁed
ARN (using unqualiﬁed ARN results in a permission error).

Managing Versioning Using the AWS Management
Console, the AWS CLI, or Lambda API Operations
You can manage Lambda function versioning programmatically using AWS SDKs (or make the AWS
Lambda API calls directly, if you need to), using AWS Command Line Interface (AWS CLI), or the AWS
Lambda console.
AWS Lambda provides the following APIs to manage versioning and aliases:
PublishVersion (p. 440)
ListVersionsByFunction (p. 433)
CreateAlias (p. 360)
UpdateAlias (p. 458)
DeleteAlias (p. 376)
GetAlias (p. 389)
ListAliases (p. 417)
In addition to these APIs, existing relevant APIs also support versioning related operations.
For an example of how you can use the AWS CLI, see Tutorial: Using AWS Lambda Aliases (p. 38).
This section explains how you can use the AWS Lambda console to manage versioning. In the AWS
Lambda console, choose a function and then choose Qualiﬁers.

43

AWS Lambda Developer Guide
Managing Versioning

The expanded Qualiﬁers menu displays a Versions and Aliases tab, as shown in the following screen
shot. In the Versions pane, you can see a list of versions for the selected function. If you have not
previously published a version for the selected function, the Versions pane lists only the $LATEST
version, as shown following.

Choose the Aliases tab to see a list of aliases for the function. Initially, you won't have any aliases, as
shown following.

44

AWS Lambda Developer Guide
Traﬃc Shifting Using Aliases

Now you can publish a version or create aliases for the selected Lambda function by using the Actions
menu.

To learn about versioning and aliases, see AWS Lambda Function Versioning and Aliases (p. 30).

Traﬃc Shifting Using Aliases
By default, an alias points to a single Lambda function version. When the alias is updated to point to a
diﬀerent function version, incoming request traﬃc in turn instantly points to the updated version. This
exposes that alias to any potential instabilities introduced by the new version. To minimize this impact,
you can implement the routing-config parameter of the Lambda alias that allows you to point to two

45

AWS Lambda Developer Guide
Traﬃc Shifting Using Aliases

diﬀerent versions of the Lambda function and dictate what percentage of incoming traﬃc is sent to each
version.
For example, you can specify that only 2 percent of incoming traﬃc is routed to the new version while
you analyze its readiness for a production environment, while the remaining 98 percent is routed to the
original version. As the new version matures, you can gradually update the ratio as necessary until you
have determined the new version is stable. You can then update the alias to route all traﬃc to the new
version.

Note

You can point an alias to a maximum of two Lambda function versions. In addition:
• Both versions should have the same Dead Letter Queues (p. 70) conﬁguration (or no DLQ
conﬁguration).
• Both versions should have the same IAM execution role.
• When pointing an alias to more than one version, the alias cannot point to $LATEST.

Traﬃc Shifting Using an Alias (CLI)
To conﬁgure an alias to shift traﬃc between two function versions based on weights by using the
CreateAlias (p. 360) operation, you need to conﬁgure the routing-config parameter. The example
following points an alias to two diﬀerent Lambda function versions, with version 2 receiving 2 percent of
the invocation traﬃc and the remaining 98 percent invoking version 1.
aws lambda create-alias --name alias name --function-name function-name \ --functionversion 1
--routing-config AdditionalVersionWeights={"2"=0.02}

You can update the percentage of incoming traﬃc to your new version (version 2) by using the
UpdateAlias (p. 458) operation. For example, you can boost the invocation traﬃc to your new version
to 5 percent, as shown following.
aws lambda update-alias --name alias name --function-name function-name \
--routing-config AdditionalVersionWeights={"2"=0.05}

To route all traﬃc to version 2, again use the UpdateAlias operation to change the functionversion property to point to version 2. Then set the routing-config parameter to an empty string,
as shown following.
aws lambda update-alias --name alias name --function-name function-name \
--function-version 2 --routing-config ''

Traﬃc Shifting Using an Alias (Console)
You can conﬁgure traﬃc shifting with an alias by using the Lambda console as described below:
1.

Open your Lambda function and verify that you have at least two previously published versions.
Otherwise, you can go to Introduction to AWS Lambda Versioning (p. 31) to learn more about
versioning, and publish your ﬁrst function version.

2.
3.

For Actions, choose Create alias.
In the Create a new alias window, specify a value for Name*, optionally for Description, and for
Version* of the Lambda function that the alias will point to. Here the version is 1.
Under Additional version, specify the following:

4.

a.

Specify a second Lambda function version.

46

AWS Lambda Developer Guide
Layers

b.

5.

Type a weight value for the function. Weight is the percentage of traﬃc that is assigned to that
version when the alias is invoked. The ﬁrst version receives the residual weight. For example,
if you specify 10 percent to Additional version, the ﬁrst version automatically is assigned 90
percent.

Choose Create.

Determining Which Version Has Been Invoked
When your alias is shifting traﬃc between two function versions, there are two ways to determine which
Lambda function version has been invoked:
1. CloudWatch Logs – Lambda automatically emits a START log entry that contains the invoked version
ID to CloudWatch Logs for every function invocation. An example follows.
19:44:37 START RequestId: request id Version: $version
Lambda uses the Executed Version dimension to ﬁlter the metric data by the executed
version. This only applies to alias invocations. For more information, see AWS Lambda CloudWatch
Dimensions (p. 214).
2. Response payload (synchronous invocations) – Responses to synchronous function invocations
include an x-amz-executed-version header to indicate which function version has been invoked.

AWS Lambda Layers
You can conﬁgure your Lambda function to pull in additional code and content in the form of layers. A
layer is a ZIP archive that contains libraries, a custom runtime (p. 95), or other dependencies. With
layers, you can use libraries in your function without needing to include them in your deployment
package.
Layers let you keep your deployment package small, which makes development easier. You can avoid
errors that can occur when you install and package dependencies with your function code. For Node.js,
Python, and Ruby functions, you can develop your function code in the Lambda console (p. 11) as long as
you keep your deployment package under 3 MB.

Note

A function can use up to 5 layers at a time. The total unzipped size of the function and all layers
can't exceed the unzipped deployment package size limit of 250 MB. For more information, see
AWS Lambda Limits (p. 249).
You can create layers, or use layers published by AWS and other AWS customers. Layers support
resource-based policies (p. 51) for granting permission speciﬁc AWS accounts, AWS Organizations, or
all accounts.
Layers are extracted to the /opt directory in the function execution environment. Each runtime looks for
libraries in a diﬀerent location under /opt, depending on the language. Structure your layer (p. 50) so
that function code can access libraries without additional conﬁguration.
You can also use AWS Serverless Application Model (AWS SAM) to manage layers and your function's
layer conﬁguration. For instructions, see Declaring Serverless Resources in the AWS Serverless Application
Model Developer Guide.
Sections
• Conﬁguring a Function to Use Layers (p. 48)
• Managing Layers (p. 49)

47

AWS Lambda Developer Guide
Conﬁguring a Function to Use Layers

• Including Library Dependencies in a Layer (p. 50)
• Layer Permissions (p. 51)

Conﬁguring a Function to Use Layers
You can specify up to 5 layers in your function's conﬁguration, during or after function creation. You
choose a speciﬁc version of a layer to use. If you want to use a diﬀerent version later, update your
function's conﬁguration.
To add layers to your function, use the update-function-configuration command. The following
example adds two layers: one from the same account as the function, and one from a diﬀerent account.
$ aws lambda update-function-configuration --function-name my-function \
--layers arn:aws:lambda:us-east-2:123456789012:layer:my-layer:3
\
arn:aws:lambda:us-east-2:210987654321:layer:their-layer:2
{
"FunctionName": "test-layers",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"Runtime": "nodejs8.10",
"Role": "arn:aws:iam::123456789012:role/service-role/lambda-role",
"Handler": "index.handler",
"CodeSize": 402,
"Description": "",
"Timeout": 5,
"MemorySize": 128,
"LastModified": "2018-11-14T22:47:04.542+0000",
"CodeSha256": "kDHAEY62Ni3OovMwVO8tNvgbRoRa6IOOKqShm7bSWF4=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "Active"
},
"RevisionId": "81cc64f5-5772-449a-b63e-12330476bcc4",
"Layers": [
{
"Arn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer:3",
"CodeSize": 169
},
{
"Arn": "arn:aws:lambda:us-east-2:210987654321:layer:their-layer:2",
"CodeSize": 169
}
]
}

You must specify the version of each layer to use by providing the full ARN of the layer version. When
you add layers to a function that already has layers, the previous list is overwritten by the new one.
Include all layers every time you update the layer conﬁguration. To remove all layers, specify an empty
list.
$ aws lambda update-function-configuration --function-name my-function --layers []

Your function can access the content of the layer during execution in the /opt directory. Layers are
applied in the order that's speciﬁed, merging any folders with the same name. If the same ﬁle appears in
multiple layers, the version in the last applied layer is used.
The creator of a layer can delete the version of the layer that you're using. When this happens, your
function continues to run as though the layer version still existed. However, when you update the layer
conﬁguration, you must remove the reference to the deleted version.

48

AWS Lambda Developer Guide
Managing Layers

Managing Layers
To create a layer, use the publish-layer-version command with a name, description, ZIP archive,
and a list of runtimes (p. 91) that are compatible with the layer. The list of runtimes is optional, but it
makes the layer easier to discover.
$ aws lambda publish-layer-version --layer-name my-layer --description "My layer" -license-info "MIT" \
--content S3Bucket=lambda-layers-us-east-2-123456789012,S3Key=layer.zip --compatibleruntimes python3.6 python3.7
{
"Content": {
"Location": "https://awslambda-us-east-2-layers.s3.us-east-2.amazonaws.com/
snapshots/123456789012/my-layer-4aaa2fbb-ff77-4b0a-ad92-5b78a716a96a?
versionId=27iWyA73cCAYqyH...",
"CodeSha256": "tv9jJO+rPbXUUXuRKi7CwHzKtLDkDRJLB3cC3Z/ouXo=",
"CodeSize": 169
},
"LayerArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer",
"LayerVersionArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer:1",
"Description": "My layer",
"CreatedDate": "2018-11-14T23:03:52.894+0000",
"Version": 1,
"LicenseInfo": "MIT",
"CompatibleRuntimes": [
"python3.6",
"python3.7"
]
}

Each time you call publish-layer-version, you create a new version. Functions that use the layer
refer directly to a layer version. You can conﬁgure permissions (p. 51) on an existing layer version, but
to make any other changes, you must create a new version.
To ﬁnd layers that are compatible with your function's runtime, use the list-layers command.
$ aws lambda list-layers --compatible-runtime python3.7
{
"Layers": [
{
"LayerName": "my-layer",
"LayerArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer",
"LatestMatchingVersion": {
"LayerVersionArn": "arn:aws:lambda:us-east-2:123456789012:layer:mylayer:2",
"Version": 2,
"Description": "My layer",
"CreatedDate": "2018-11-15T00:37:46.592+0000",
"CompatibleRuntimes": [
"python3.6",
"python3.7"
]
}
}
]
}

You can omit the runtime option to list all layers. The details in the response reﬂect the latest version of
the layer. See all the versions of a layer with list-layer-versions. To see more information about a
version, use get-layer-version.

49

AWS Lambda Developer Guide
Including Library Dependencies in a Layer

$ aws lambda get-layer-version --layer-name my-layer --version-number 2
{
"Content": {
"Location": "https://awslambda-us-east-2-layers.s3.us-east-2.amazonaws.com/
snapshots/123456789012/my-layer-91e9ea6e-492d-4100-97d5-a4388d442f3f?
versionId=GmvPV.309OEpkfN...",
"CodeSha256": "tv9jJO+rPbXUUXuRKi7CwHzKtLDkDRJLB3cC3Z/ouXo=",
"CodeSize": 169
},
"LayerArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer",
"LayerVersionArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer:2",
"Description": "My layer",
"CreatedDate": "2018-11-15T00:37:46.592+0000",
"Version": 2,
"CompatibleRuntimes": [
"python3.6",
"python3.7"
]
}

The link in the response lets you download the layer archive and is valid for 10 minutes. To delete a layer
version, use the delete-layer-version command.
$ aws lambda delete-layer-version --layer-name my-layer --version-number 1

When you delete a layer version, you can no longer conﬁgure functions to use it. However, any function
that already uses the version continues to have access to it.

Including Library Dependencies in a Layer
You can move runtime dependencies out of your function code by placing them in a layer. Lambda
runtimes include paths in the /opt directory to ensure that your function code has access to libraries
that are included in layers.
To include libraries in a layer, place them in one of the folders supported by your runtime.
• Node.js – nodejs/node_modules, nodejs/node8/node_modules (NODE_PATH)

Example AWS X-Ray SDK for Node.js
xray-sdk.zip
# nodejs/node_modules/aws-xray-sdk

• Python – python, python/lib/python3.7/site-packages (site directories)

Example Pillow
pillow.zip
# python/PIL
# python/Pillow-5.3.0.dist-info

• Java – java/lib (classpath)

Example Jackson
jackson.zip
# java/lib/jackson-core-2.2.3.jar

50

AWS Lambda Developer Guide
Layer Permissions

• Ruby – ruby/gems/2.5.0 (GEM_PATH), ruby/lib (RUBY_LIB)

Example JSON
json.zip
# ruby/gems/2.5.0/json

• All – bin (PATH), lib (LD_LIBRARY_PATH)

Example JQ
jq.zip
# bin/jq

For more information about path settings in the Lambda execution environment, see Lambda Execution
Environment and Available Libraries (p. 92).

Layer Permissions
Layer usage permissions are managed on the resource. To conﬁgure a function with a layer, you need
permission to call GetLayerVersion on the layer version. For functions in your account, you can get
this permission from your user policy (p. 226) or from the function's resource-based policy (p. 223).
To use a layer in another account, you need permission on your user policy, and the owner of the other
account must grant your account permission with a resource-based policy.
To grant layer-usage permission to another account, add a statement to the layer version's permissions
policy with the add-layer-version-permission command. In each statement, you can grant
permission to a single account, all accounts, or an organization.
The following example grants all accounts in an organization permission to use version 3 of a layer.
$ aws lambda add-layer-version-permission --layer-name my-layer \
--statement-id engineering-org --version-number 3 --principal '*' \
--action lambda:GetLayerVersion --organization-id o-t194hfs8cz
{
"Statement": "{\"Sid\":\"engineering-org\",\"Effect\":\"Allow\",\"Principal
\":\"*\",\"Action\":\"lambda:GetLayerVersion\",\"Resource\":\"arn:aws:lambda:uswest-2:123456789012:layer:my-layer:3\",\"Condition\":{\"StringEquals\":
{\"aws:PrincipalOrgID\":\"o-t194hfs8cz\"}}}",
"RevisionId": "b0cd9796-d4eb-4564-939f-de7fe0b42236"
}

To grant permission to all AWS accounts, use * for the principal, and omit the organization ID. To grant
permission to a single account, use the account number for the principal. For multiple accounts or
organizations, add multiple statements.
Permissions only apply to a single version of a layer. Repeat the procedure each time you create a new
layer version.
Use the get-layer-version-policy command to view the permissions on a layer, and removelayer-version-permission to remove statements from the policy.
$ aws lambda get-layer-version-policy --layer-name my-layer --version-number 3
{
"Statement": "{\"Sid\":\"engineering-org\",\"Effect\":\"Allow\",\"Principal
\":\"*\",\"Action\":\"lambda:GetLayerVersion\",\"Resource\":\"arn:aws:lambda:uswest-2:123456789012:layer:my-layer:3\",\"Condition\":{\"StringEquals\":
{\"aws:PrincipalOrgID\":\"o-t194hfs8cz\"}}}",

51

AWS Lambda Developer Guide
VPC Settings
"RevisionId": "b0cd9796-d4eb-4564-939f-de7fe0b42236"
}
$ aws lambda remove-layer-version-permission --layer-name my-layer --version-number 3 -statement-id engineering-org

Conﬁguring a Lambda Function to Access
Resources in an Amazon VPC
Typically, you create resources inside Amazon Virtual Private Cloud (Amazon VPC) so that they cannot
be accessed over the public Internet. These resources could be AWS service resources, such as Amazon
Redshift data warehouses, Amazon ElastiCache clusters, or Amazon RDS instances. They could also
be your own services running on your own EC2 instances. By default, resources within a VPC are not
accessible from within a Lambda function.
AWS Lambda runs your function code securely within a VPC by default. However, to enable your
Lambda function to access resources inside your private VPC, you must provide additional VPC-speciﬁc
conﬁguration information that includes VPC subnet IDs and security group IDs. AWS Lambda uses this
information to set up elastic network interfaces (ENIs) that enable your function to connect securely to
other resources within your private VPC.
AWS Lambda does not support connecting to resources within Dedicated Tenancy VPCs. For more
information, see Dedicated VPCs.

Conﬁguring a Lambda Function for Amazon VPC
Access
You add VPC information to your Lambda function conﬁguration using the VpcConfig parameter,
either at the time you create a Lambda function (see CreateFunction (p. 368)), or you can add it to the
existing Lambda function conﬁguration (see UpdateFunctionConﬁguration (p. 472)). Following are AWS
CLI examples:
• The create-function CLI command speciﬁes the --vpc-config parameter to provide VPC
information at the time you create a Lambda function.
$ aws lambda create-function \
--function-name ExampleFunction \
--runtime go1.x \
--role execution-role-arn \
--zip-file fileb://path/app.zip \
--handler app.handler \
--vpc-config SubnetIds=comma-separated-vpc-subnet-ids,SecurityGroupIds=comma-separatedsecurity-group-ids \
--memory-size 1024

Note

The Lambda function execution role must have permissions to create, describe and delete
ENIs. AWS Lambda provides a permissions policy, AWSLambdaVPCAccessExecutionRole,
with permissions for the necessary EC2 actions (ec2:CreateNetworkInterface,
ec2:DescribeNetworkInterfaces, and ec2:DeleteNetworkInterface) that you can
use when creating a role. You can review the policy in the IAM console. Do not delete this
role immediately after your Lambda function execution. There is a delay between the time
your Lambda function executes and ENI deletion. If you do delete the role immediately after
function execution, you are responsible for deleting the ENIs.

52

AWS Lambda Developer Guide
Internet Access for Lambda Functions

• The update-function-configuration CLI command speciﬁes the --vpc-config parameter to
add VPC information to an existing Lambda function conﬁguration.
$ aws lambda update-function-configuration \
--function-name ExampleFunction \
--vpc-config SubnetIds=comma-separated-vpc-subnet-ids,SecurityGroupIds=security-group-ids

To remove VPC-related information from your Lambda function conﬁguration, use the
UpdateFunctionConfiguration API by providing an empty list of subnet IDs and security group
IDs as shown in the following example CLI command.
$ aws lambda update-function-configuration \
--function-name ExampleFunction \
--vpc-config SubnetIds=[],SecurityGroupIds=[]

Note the following additional considerations:
• When you add VPC conﬁguration to a Lambda function, it can only access resources in that VPC. If a
Lambda function needs to access both VPC resources and the public Internet, the VPC needs to have a
Network Address Translation (NAT) instance inside the VPC.
• When a Lambda function is conﬁgured to run within a VPC, it incurs an additional ENI start-up penalty.
This means address resolution may be delayed when trying to connect to network resources.

Internet Access for Lambda Functions
AWS Lambda uses the VPC information you provide to set up ENIs that allow your Lambda function
to access VPC resources. Each ENI is assigned a private IP address from the IP address range within the
Subnets you specify, but is not assigned any public IP addresses. Therefore, if your Lambda function
requires Internet access (for example, to access AWS services that don't have VPC endpoints ), you
can conﬁgure a NAT instance inside your VPC or you can use the Amazon VPC NAT gateway. For more
information, see NAT Gateways in the Amazon VPC User Guide. You cannot use an Internet gateway
attached to your VPC, since that requires the ENI to have public IP addresses.

Important

If your Lambda function needs Internet access, do not attach it to a public subnet or to a private
subnet without Internet access. Instead, attach it only to private subnets with Internet access
through a NAT instance or an Amazon VPC NAT gateway.

Guidelines for Setting Up VPC-Enabled Lambda
Functions
Your Lambda function automatically scales based on the number of events it processes. The following
are general guidelines for setting up VPC-enabled Lambda functions to support the scaling behavior.
• If your Lambda function accesses a VPC, you must make sure that your VPC has suﬃcient ENI capacity
to support the scale requirements of your Lambda function. You can use the following formula to
approximately determine the ENI requirements.
Projected peak concurrent executions * (Memory in GB / 3GB)

Where:
• Projected peak concurrent execution – Use the information in Managing Concurrency (p. 241) to
determine this value.

53

AWS Lambda Developer Guide
Tutorial: Amazon ElastiCache

• Memory – The amount of memory you conﬁgured for your Lambda function.
• The subnets you specify should have suﬃcient available IP addresses to match the number of ENIs.
We also recommend that you specify at least one subnet in each Availability Zone in your Lambda
function conﬁguration. By specifying subnets in each of the Availability Zones, your Lambda function
can run in another Availability Zone if one goes down or runs out of IP addresses.
If your VPC does not have suﬃcient ENIs or subnet IPs, your Lambda function will not scale
as requests increase, and you will see an increase in invocation errors with EC2 error types like
EC2ThrottledException. For asynchronous invocation, if you see an increase in errors without
corresponding CloudWatch Logs, invoke the Lambda function synchronously in the console to get the
error responses.

Tutorial: Conﬁguring a Lambda Function to Access
Amazon ElastiCache in an Amazon VPC
In this tutorial, you do the following:
• Create an Amazon ElastiCache cluster in your default Amazon Virtual Private Cloud. For more
information about Amazon ElastiCache, see Amazon ElastiCache.
• Create a Lambda function to access the ElastiCache cluster. When you create the Lambda function,
you provide subnet IDs in your Amazon VPC and a VPC security group to allow the Lambda function
to access resources in your VPC. For illustration in this tutorial, the Lambda function generates a UUID,
writes it to the cache, and retrieves it from the cache.
• Invoke the Lambda function and verify that it accessed the ElastiCache cluster in your VPC.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.
2.
3.

Open the roles page in the IAM console.
Choose Create role.
Create a role with the following properties.

54

AWS Lambda Developer Guide
Tutorial: Amazon ElastiCache

• Trusted entity – Lambda.
• Permissions – AWSLambdaVPCAccessExecutionRole.
• Role name – lambda-vpc-role.
The AWSLambdaVPCAccessExecutionRole has the permissions that the function needs to manage
network connections to a VPC.

Create an ElastiCache Cluster
Create an ElastiCache cluster in your default VPC.
1.

Run the following AWS CLI command to create a Memcached cluster.
$ aws elasticache create-cache-cluster --cache-cluster-id ClusterForLambdaTest \
--cache-node-type cache.m3.medium --engine memcached --num-cache-nodes 1 \
--security-group-ids your-default-vpc-security-group

You can look up the default VPC security group in the VPC console under Security Groups. Your
example Lambda function will add and retrieve an item from this cluster.
2.

Write down the conﬁguration endpoint for the cache cluster that you launched. You can get this
from the Amazon ElastiCache console. You will specify this value in your Lambda function code in
the next section.

Create a Deployment Package
The following example Python code reads and writes an item to your ElastiCache cluster.

Example app.py
from __future__ import print_function
import time
import uuid
import sys
import socket
import elasticache_auto_discovery
from pymemcache.client.hash import HashClient
#elasticache settings
elasticache_config_endpoint = "your-elasticache-cluster-endpoint:port"
nodes = elasticache_auto_discovery.discover(elasticache_config_endpoint)
nodes = map(lambda x: (x[1], int(x[2])), nodes)
memcache_client = HashClient(nodes)
def handler(event, context):
"""
This function puts into memcache and get from it.
Memcache is hosted using elasticache
"""
#Create a random UUID... this will the sample element we add to the cache.
uuid_inserted = uuid.uuid4().hex
#Put the UUID to the cache.
memcache_client.set('uuid', uuid_inserted)
#Get item (UUID) from the cache.
uuid_obtained = memcache_client.get('uuid')
if uuid_obtained.decode("utf-8") == uuid_inserted:
# this print should go to the CloudWatch Logs and Lambda console.

55

AWS Lambda Developer Guide
Tutorial: Amazon RDS
print ("Success: Fetched value %s from memcache" %(uuid_inserted))
else:
raise Exception("Value is not the same as we put :(. Expected %s got %s"
%(uuid_inserted, uuid_obtained))
return "Fetched value from memcache: " + uuid_obtained.decode("utf-8")

Dependencies
• pymemcache – The Lambda function code uses this library to create a HashClient object to set and
get items from memcache.
• elasticache-auto-discovery – The Lambda function uses this library to get the nodes in your Amazon
ElastiCache cluster.
Install dependencies with Pip and create a deployment package. For instructions, see AWS Lambda
Deployment Package in Python (p. 262).

Create the Lambda Function
Create the Lambda function with the create-function command.
$ aws lambda create-function --function-name AccessMemCache --timeout 30 --memory-size 1024
\
--zip-file fileb://function.zip --handler app.handler --runtime python3.7 \
--role execution-role-arn \
--vpc-config SubnetIds=comma-separated-vpc-subnet-ids,SecurityGroupIds=default-securitygroup-id

You can ﬁnd the subnet IDs and the default security group ID of your VPC from the VPC console.

Test the Lambda Function
In this step, you invoke the Lambda function manually using the invoke command. When the Lambda
function executes, it generates a UUID and writes it to the ElastiCache cluster that you speciﬁed in your
Lambda code. The Lambda function then retrieves the item from the cache.
1.

Invoke the Lambda function with the invoke command.
$ aws lambda invoke --function-name AccessMemCache output.txt

2.

Verify that the Lambda function executed successfully as follows:
• Review the output.txt ﬁle.
• Review the results in the AWS Lambda console.
• Verify the results in CloudWatch Logs.

Now that you have created a Lambda function that accesses an ElastiCache cluster in your VPC, you can
have the function invoked in response to events. For information about conﬁguring event sources and
examples, see Use Cases (p. 114).

Tutorial: Conﬁguring a Lambda Function to Access
Amazon RDS in an Amazon VPC
In this tutorial, you do the following:

56

AWS Lambda Developer Guide
Tutorial: Amazon RDS

• Launch an Amazon RDS MySQL database engine instance in your default Amazon VPC. In the
MySQL instance, you create a database (ExampleDB) with a sample table (Employee) in it. For more
information about Amazon RDS, see Amazon RDS.
• Create a Lambda function to access the ExampleDB database, create a table (Employee), add a few
records, and retrieve the records from the table.
• Invoke the Lambda function and verify the query results. This is how you verify that your Lambda
function was able to access the RDS MySQL instance in the VPC.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.
2.
3.

Open the roles page in the IAM console.
Choose Create role.
Create a role with the following properties.
• Trusted entity – Lambda.
• Permissions – AWSLambdaVPCAccessExecutionRole.
• Role name – lambda-vpc-role.

The AWSLambdaVPCAccessExecutionRole has the permissions that the function needs to manage
network connections to a VPC.

Create an Amazon RDS Database Instance
In this tutorial, the example Lambda function creates a table (Employee), inserts a few records, and then
retrieves the records. The table that the Lambda function creates has the following schema:
Employee(EmpID, Name)

Where EmpID is the primary key. Now, you need to add a few records to this table.
First, you launch an RDS MySQL instance in your default VPC with ExampleDB database. If you already
have an RDS MySQL instance running in your default VPC, skip this step.

57

AWS Lambda Developer Guide
Tutorial: Amazon RDS

You can launch an RDS MySQL instance using one of the following methods:
• Follow the instructions at Creating a MySQL DB Instance and Connecting to a Database on a MySQL DB
Instance in the Amazon RDS User Guide.
• Use the following AWS CLI command:
$ aws rds create-db-instance --db-name ExampleDB --engine MySQL \
--db-instance-identifier MySQLForLambdaTest --backup-retention-period 3 \
--db-instance-class db.t2.micro --allocated-storage 5 --no-publicly-accessible \
--master-username username --master-user-password password

Write down the database name, user name, and password. You also need the host address (endpoint)
of the DB instance, which you can get from the RDS console. You might need to wait until the instance
status is available and the Endpoint value appears in the console.

Create a Deployment Package
The following example Python code runs a SELECT query against the Employee table in the MySQL RDS
instance that you created in the VPC. The code creates a table in the ExampleDB database, adds sample
records, and retrieves those records.

Example app.py
import sys
import logging
import rds_config
import pymysql
#rds settings
rds_host = "rds-instance-endpoint"
name = rds_config.db_username
password = rds_config.db_password
db_name = rds_config.db_name
logger = logging.getLogger()
logger.setLevel(logging.INFO)
try:

conn = pymysql.connect(rds_host, user=name, passwd=password, db=db_name,
connect_timeout=5)
except:
logger.error("ERROR: Unexpected error: Could not connect to MySQL instance.")
sys.exit()
logger.info("SUCCESS: Connection to RDS MySQL instance succeeded")
def handler(event, context):
"""
This function fetches content from MySQL RDS instance
"""
item_count = 0
with conn.cursor() as cur:
cur.execute("create table Employee3 ( EmpID int
NULL, PRIMARY KEY (EmpID))")
cur.execute('insert into Employee3 (EmpID, Name)
cur.execute('insert into Employee3 (EmpID, Name)
cur.execute('insert into Employee3 (EmpID, Name)
conn.commit()
cur.execute("select * from Employee3")
for row in cur:
item_count += 1

58

NOT NULL, Name varchar(255) NOT
values(1, "Joe")')
values(2, "Bob")')
values(3, "Mary")')

AWS Lambda Developer Guide
Tutorial: Amazon RDS
logger.info(row)
#print(row)
conn.commit()
return "Added %d items from RDS MySQL table" %(item_count)

Executing pymysql.connect() outside of the handler allows your function to re-use the database
connection for better performance.
A second ﬁle contains connection information for the function.

Example rds_conﬁg.py
#config file containing credentials for RDS MySQL instance
db_username = "username"
db_password = "password"
db_name = "ExampleDB"

Dependencies
• pymysql – The Lambda function code uses this library to access your MySQL instance (see PyMySQL) .
Install dependencies with Pip and create a deployment package. For instructions, see AWS Lambda
Deployment Package in Python (p. 262).

Create the Lambda Function
Create the Lambda function with the create-function command.
$ aws lambda create-function --function-name CreateTableAddRecordsAndRead --runtime
python3.7 \
--zip-file fileb://app.zip --handler app.handler \
--role execution-role-arn \
--vpc-config SubnetIds=comma-separated-subnet-ids,SecurityGroupIds=default-vpc-securitygroup-id

Test the Lambda Function
In this step, you invoke the Lambda function manually using the invoke command. When the Lambda
function executes, it runs the SELECT query against the Employee table in the RDS MySQL instance and
prints the results, which also go to the CloudWatch Logs.
1.

Invoke the Lambda function with the invoke command.
$ aws lambda invoke --function-name CreateTableAddRecordsAndRead output.txt

2.

Verify that the Lambda function executed successfully as follows:
• Review the output.txt ﬁle.
• Review the results in the AWS Lambda console.
• Verify the results in CloudWatch Logs.

Now that you have created a Lambda function that accesses a database in your VPC, you can have the
function invoked in response to events. For information about conﬁguring event sources and examples,
see Use Cases (p. 114).

59

AWS Lambda Developer Guide
Example 1

Invoking AWS Lambda Functions
When building applications on AWS Lambda, including serverless applications, the core components
are Lambda functions and event sources. An event source is the AWS service or custom application that
publishes events, and a Lambda function is the custom code that processes the events. To illustrate,
consider the following scenarios:
• File processing – Suppose you have a photo sharing application. People use your application to upload
photos, and the application stores these user photos in an Amazon S3 bucket. Then, your application
creates a thumbnail version of each user's photos and displays them on the user's proﬁle page. In this
scenario, you may choose to create a Lambda function that creates a thumbnail automatically. Amazon
S3 is one of the supported AWS event sources that can publish object-created events and invoke your
Lambda function. Your Lambda function code can read the photo object from the S3 bucket, create a
thumbnail version, and then save it in another S3 bucket.
• Data and analytics – Suppose you are building an analytics application and storing raw data in a
DynamoDB table. When you write, update, or delete items in a table, DynamoDB streams can publish
item update events to a stream associated with the table. In this case, the event data provides the
item key, event name (such as insert, update, and delete), and other relevant details. You can write a
Lambda function to generate custom metrics by aggregating raw data.
• Websites – Suppose you are creating a website and you want to host the backend logic on Lambda.
You can invoke your Lambda function over HTTP using Amazon API Gateway as the HTTP endpoint.
Now, your web client can invoke the API, and then API Gateway can route the request to Lambda.
• Mobile applications – Suppose you have a custom mobile application that produces events. You can
create a Lambda function to process events published by your custom application. For example, in
this scenario you can conﬁgure a Lambda function to process the clicks within your custom mobile
application.
Each of these event sources uses a speciﬁc format for the event data. For more information, see Sample
Events Published by Event Sources (p. 79). When a Lambda function is invoked, it receives the event as
a parameter for the Lambda function.
AWS Lambda supports many AWS services as event sources. For more information, see Supported Event
Sources (p. 71). When you conﬁgure these event sources to trigger a Lambda function, the Lambda
function is invoked automatically when events occur. You deﬁne event source mapping, which is how you
identify what events to track and which Lambda function to invoke.
In addition to the supported AWS services, user applications can also generate events—you can build
your own custom event sources. Custom event sources invoke a Lambda function using the AWS Lambda
Invoke (p. 410) operation. User applications, such as client, mobile, or web applications, can publish
events and invoke Lambda functions on demand using the AWS SDKs or AWS Mobile SDKs, such as the
AWS Mobile SDK for Android.
The following are introductory examples of event sources and how the end-to-end experience works.

Example 1: Amazon S3 Pushes Events and Invokes
a Lambda Function
Amazon S3 can publish events of diﬀerent types, such as PUT, POST, COPY, and DELETE object events on
a bucket. Using the bucket notiﬁcation feature, you can conﬁgure an event source mapping that directs
Amazon S3 to invoke a Lambda function when a speciﬁc type of event occurs, as shown in the following
illustration.

60

AWS Lambda Developer Guide
Example 2

The diagram illustrates the following sequence:
1. The user creates an object in a bucket.
2. Amazon S3 detects the object created event.
3. Amazon S3 invokes your Lambda function using the permissions provided by the execution role. For
more information on execution roles, see AWS Lambda Permissions (p. 221). Amazon S3 knows
which Lambda function to invoke based on the event source mapping that is stored in the bucket
notiﬁcation conﬁguration.
4. AWS Lambda executes the Lambda function, specifying the event as a parameter.
Note the following:
• The event source mapping is maintained within the event source service, Amazon S3 in this scenario.
This is true for all supported AWS event sources except the poll-based sources (Kinesis and DynamoDB
streams or Amazon SQS queues). The next example explains poll-based event sources.
• The event source (Amazon S3) invokes the Lambda function (referred to as the push model). Again, this
is true for all supported AWS services except the poll-based event sources.
• In order for the event source (Amazon S3) to invoke your Lambda function, you must grant
permissions using the permissions policy attached to the Lambda function.

Example 2: AWS Lambda Pulls Events from a
Kinesis Stream and Invokes a Lambda Function
For poll-based event sources, AWS Lambda polls the source and then invokes the Lambda function
when records are detected on that source. For poll-based sources, event source mapping information is
stored in AWS Lambda. AWS Lambda provides an API for you to create and manage these event source
mappings.
• CreateEventSourceMapping (p. 364)
• UpdateEventSourceMapping (p. 462)
The following diagram shows how a custom application writes records to a Kinesis stream.

61

AWS Lambda Developer Guide
Example 2

The diagram illustrates the following sequence:
1. The custom application writes records to a Kinesis stream.
2. AWS Lambda continuously polls the stream, and invokes the Lambda function when the service
detects new records on the stream. AWS Lambda knows which stream to poll and which Lambda
function to invoke based on the event source mapping you create in Lambda.
3. The Lambda function is invoked with the incoming event.
Note the following:
• When working with stream-based event sources, the following is true:
• You create event source mappings in AWS Lambda.
• AWS Lambda invokes the Lambda function synchronously (referred to as the pull model).
• AWS Lambda does not need permission to invoke your Lambda function, therefore you don't need to
add any permissions to the permissions policy attached to your Lambda function.
• Your Lambda role needs permission to read from the stream.

Example 3: AWS Lambda Pulls Events from an
Amazon SQS Queue and Invokes a Lambda
Function
For poll-based event sources, AWS Lambda polls the source and then invokes the Lambda function
when records are detected on that source. For poll-based sources, event source mapping information is
stored in AWS Lambda. AWS Lambda provides an API for you to create and manage these event source
mappings.
• CreateEventSourceMapping (p. 364)
• UpdateEventSourceMapping (p. 462)
The following diagram shows how a custom application writes records to an Amazon SQS queue:

62

AWS Lambda Developer Guide
Invocation Types

The diagram illustrates the following sequence:
1. The custom application writes records to an Amazon SQS queue.
2. AWS Lambda continuously polls the queue, and invokes the Lambda function when the service detects
new records. AWS Lambda knows which queue to poll and which Lambda function to invoke based on
the event source mapping you create in Lambda.
3. The Lambda function is invoked with the incoming event.
Note the following:
• When working with poll-based events, the following is true:
• You create event source mappings in AWS Lambda.
• AWS Lambda invokes the Lambda function synchronously (referred to as the pull model).
• AWS Lambda does not need permission to invoke your Lambda function, therefore you don't need to
add any permissions to the permissions policy attached to your Lambda function.
• Your Lambda role needs permission to read from the queue and queue attributes.

Invocation Types
AWS Lambda supports synchronous and asynchronous invocation of a Lambda function. You can control
the invocation type only when you invoke a Lambda function (referred to as on-demand invocation). The
following examples illustrate on-demand invocations:
• Your custom application invokes a Lambda function.
• You manually invoke a Lambda function (for example, using the AWS CLI) for testing purposes.
In both cases, you invoke your Lambda function using the Invoke (p. 410) operation, and you can
specify the invocation type as synchronous or asynchronous.
When you use an AWS services as a trigger, the invocation type is predetermined for each service. You
have no control over the invocation type that these event sources use when they invoke your Lambda
function.
For example, Amazon S3 always invokes a Lambda function asynchronously and Amazon Cognito
always invokes a Lambda function synchronously. For poll-based AWS services (Amazon Kinesis, Amazon
DynamoDB, Amazon Simple Queue Service), AWS Lambda polls the stream or message queue and
invokes your Lambda function synchronously.
63

AWS Lambda Developer Guide
Event Source Mapping

AWS Lambda Event Source Mapping
Lambda functions and event sources are the core components of AWS Lambda. An event source is the
entity that publishes events, and a Lambda function is the custom code that processes the events.
Supported event sources are the AWS services that can be preconﬁgured to work with AWS Lambda. The
conﬁguration is referred to as event source mapping, which maps an event source to a Lambda function.
It enables automatic invocation of your Lambda function when events occur.
Each event source mapping identiﬁes the type of events to publish and the Lambda function to invoke
when events occur. The speciﬁc Lambda function then receives the event information as a parameter and
your Lambda function code then processes the event.
You can also create custom applications to include AWS resource events and invoke a Lambda function.
For more information, see Using AWS Lambda with the AWS Command Line Interface (p. 203)
You may be wondering—where do I keep the event mapping information? Do I keep it within the event
source or within AWS Lambda? The following sections explain event source mapping for each of these
event source categories. These sections also explain how the Lambda function is invoked and how you
manage permissions to allow invocation of your Lambda function.
Topics
• Event Source Mapping for AWS Services (p. 64)
• Event Source Mapping for AWS Poll-Based Services (p. 65)
• Event Source Mapping for Custom Applications (p. 66)

Event Source Mapping for AWS Services
Except for the poll-based AWS services (Amazon Kinesis Data Streams and DynamoDB streams or
Amazon SQS queues), other supported AWS services publish events and can also invoke your Lambda
function (referred to as the push model). In the push model, note the following:
• Event source mappings are maintained within the event source. Relevant API support in the event
sources enables you to create and manage event source mappings. For example, Amazon S3 provides
the bucket notiﬁcation conﬁguration API. Using this API, you can conﬁgure an event source mapping
that identiﬁes the bucket events to publish and the Lambda function to invoke.
• Because the event sources invoke your Lambda function, you need to grant the event source the
necessary permissions using a resource-based policy. For more information, see Using Resource-Based
Policies for AWS Lambda (p. 223).
The following example illustrates how this model works.

Example – Amazon S3 Pushes Events and Invokes a Lambda Function
Suppose that you want your AWS Lambda function invoked for each object created bucket event. You add
the necessary event source mapping in the bucket notiﬁcation conﬁguration.

64

AWS Lambda Developer Guide
Event Source Mapping for AWS Poll-Based Services

The diagram illustrates the ﬂow:
1. The user creates an object in a bucket.
2. Amazon S3 detects the object created event.
3. Amazon S3 invokes your Lambda function according to the event source mapping described in the
bucket notiﬁcation conﬁguration.
4. AWS Lambda veriﬁes the permissions policy attached to the Lambda function to ensure that Amazon
S3 has the necessary permissions. For more information on permissions policies, see AWS Lambda
Permissions (p. 221)
5. Once AWS Lambda veriﬁes the attached permissions policy, it executes the Lambda function.
Remember that your Lambda function receives the event as a parameter.

Event Source Mapping for AWS Poll-Based Services
AWS Lambda supports the following poll-based services:
• Amazon Kinesis
• Amazon DynamoDB
• Amazon SQS
Once you have conﬁgured the necessary CreateEventSourceMapping (p. 364), AWS Lambda polls the
event source and invokes your Lambda function (referred to as the pull model). In the pull model, note
the following:
• The event source mappings are maintained within the AWS Lambda. AWS Lambda provides
the relevant APIs to create and manage event source mappings. For more information, see
CreateEventSourceMapping (p. 364).
• AWS Lambda needs your permission to poll Kinesis and DynamoDB streams or Amazon SQS queues
and read records. You grant these permissions via the execution role, using the permissions policy
associated with role that you specify when you create your Lambda function. AWS Lambda does not
need any permissions to invoke your Lambda function.
The following example illustrates how this model works.

65

AWS Lambda Developer Guide
Event Source Mapping for Custom Applications

Example – AWS Lambda Pulls Events from an Amazon Kinesis Stream and Invokes a Lambda
Function
The following diagram shows a custom application that writes records to a Kinesis stream and how
AWS Lambda polls the stream. When AWS Lambda detects a new record on the stream, it invokes your
Lambda function.
Suppose you have a custom application that writes records to a Kinesis stream. You want to invoke a
Lambda function when new records are detected on the stream. You create a Lambda function and the
necessary event source mapping in AWS Lambda.

The diagram illustrates the following sequence:
1. The custom application writes records to an Amazon Kinesis stream.
2. AWS Lambda continuously polls the stream and invokes the Lambda function once the service detects
new records on the stream. AWS Lambda knows which stream to poll and which Lambda function to
invoke based on the event source mapping you create in AWS Lambda.
3. AWS Lambda executes the Lambda function.
The example uses a Kinesis stream but the same applies when working with a DynamoDB stream.

Event Source Mapping for Custom Applications
If you have custom applications that publish and process events, you can create a Lambda function to
process these events. In this case, there is no preconﬁguration required—you don't have to set up an
event source mapping. Instead, the event source uses the AWS Lambda Invoke API. If the application
and Lambda function are owned by diﬀerent AWS accounts, the AWS account that owns the Lambda
function must allow cross-account permissions in the permissions policy associated with the Lambda
function.
The following example illustrates how this works.

Example – Custom Application Publishes Events and Invokes a Lambda Function
The following diagram shows how a custom application in your account can invoke a Lambda function. In
this example, the custom application is using the same account credentials as the account that owns the
Lambda function, and, therefore, does not require additional permissions to invoke the function.

66

AWS Lambda Developer Guide
Retry Behavior

In the following example, the user application and Lambda function are owned by diﬀerent AWS
accounts. In this case, the AWS account that owns the Lambda function must have cross-account
permissions in the permissions policy associated with the Lambda function. For more information, see
AWS Lambda Permissions (p. 221).

AWS Lambda Retry Behavior
A Lambda function can fail for any of the following reasons:
• The function times out while trying to reach an endpoint.
• The function fails to successfully parse input data.
• The function experiences resource constraints, such as out-of-memory errors or other timeouts.
If any of these failures occur, your function will throw an exception. How the exception is handled
depends upon how the Lambda function was invoked:
• Event sources that aren't stream-based – Some of these event sources are set up to invoke a Lambda
function synchronously and others invoke it asynchronously. Accordingly, exceptions are handled as
follows:
• Synchronous invocation – Lambda includes the FunctionError ﬁeld in the response body, with
details about the error in the X-Amz-Function-Error header. The status code is 200 for function
errors. Lambda only returns error status codes if there is an issue with the request, function, or

67

AWS Lambda Developer Guide
Scaling

permissions that prevents the handler from processing the event. See Invoke Errors (p. 412) for
details.
AWS service triggers (p. 71) can retry depending on the service. If you invoke the Lambda
function directly from your application, you can choose whether to retry or not.
• Asynchronous invocation – Asynchronous events are queued before being used to invoke the
Lambda function. If AWS Lambda is unable to fully process the event, it will automatically retry the
invocation twice, with delays between retries. If you have speciﬁed a Dead Letter Queue for your
function, then the failed event is sent to the speciﬁed Amazon SQS queue or Amazon SNS topic. If
you don't specify a Dead Letter Queue (DLQ), which is not required and is the default setting, then
the event will be discarded. For more information, see Dead Letter Queues (p. 70).
• Poll-based event sources that are stream-based – These consist of Kinesis Data Streams or
DynamoDB. When a Lambda function invocation fails, AWS Lambda attempts to process the erring
batch of records until the time the data expires, which can be up to seven days.
The exception is treated as blocking, and AWS Lambda will not read any new records from the shard
until the failed batch of records either expires or is processed successfully. This ensures that AWS
Lambda processes the stream events in order.
• Poll-based event sources that are not stream-based – This consists of Amazon Simple Queue Service.
If you conﬁgure an Amazon SQS queue as an event source, AWS Lambda will poll a batch of records
in the queue and invoke your Lambda function. If the invocation fails or times out, every message in
the batch will be returned to the queue, and each will be available for processing once the Visibility
Timeout period expires. (Visibility timeouts are a period of time during which Amazon Simple Queue
Service prevents other consumers from receiving and processing the message).
Once an invocation successfully processes a batch, each message in that batch will be removed
from the queue. When a message is not successfully processed, it is either discarded or if you have
conﬁgured an Amazon SQS Dead Letter Queue, the failure information will be directed there for you
to analyze.
If you don't require ordered processing of events, the advantage of using Amazon SQS queues is that
AWS Lambda will continue to process new messages, regardless of a failed invocation of a previous
message. In other words, processing of new messages will not be blocked.
For more information about invocation modes, see AWS Lambda Event Source Mapping (p. 64).

Understanding Scaling Behavior
Concurrent executions refers to the number of executions of your function code that are happening at
any given time. You can estimate the concurrent execution count, but the concurrent execution count will
diﬀer depending on whether or not your Lambda function is processing events from a poll-based event
source.
If you create a Lambda function to process events from event sources that aren't poll-based (for
example, Lambda can process every event from other sources, like Amazon S3 or API Gateway), each
published event is a unit of work, in parallel, up to your account limits. Therefore, the number of events
(or requests) these event sources publish inﬂuences the concurrency. You can use the this formula to
estimate your concurrent Lambda function invocations:
events (or requests) per second * function duration

For example, consider a Lambda function that processes Amazon S3 events. Suppose that the Lambda
function takes on average three seconds and Amazon S3 publishes 10 events per second. Then, you will
have 30 concurrent executions of your Lambda function.

68

AWS Lambda Developer Guide
Request Rate

The number of concurrent executions for poll-based event sources also depends on additional factors, as
noted following:
• Poll-based event sources that are stream-based
• Amazon Kinesis Data Streams
• Amazon DynamoDB
For Lambda functions that process Kinesis or DynamoDB streams the number of shards is the unit
of concurrency. If your stream has 100 active shards, there will be at most 100 Lambda function
invocations running concurrently. This is because Lambda processes each shard’s events in sequence.
• Poll-based event sources that are not stream-based: For Lambda functions that process Amazon
SQS queues, AWS Lambda will automatically scale the polling on the queue until the maximum
concurrency level is reached, where each message batch can be considered a single concurrent unit.
AWS Lambda's automatic scaling behavior is designed to keep polling costs low when a queue is empty
while simultaneously enabling you to achieve high throughput when the queue is being used heavily.
When an Amazon SQS event source mapping is initially enabled, Lambda begins long-polling the
Amazon SQS queue. Long polling helps reduce the cost of polling Amazon Simple Queue Service by
reducing the number of empty responses, while providing optimal processing latency when messages
arrive.
As the inﬂux of messages to a queue increases, AWS Lambda automatically scales up polling activity
until the number of concurrent function executions reaches 1000, the account concurrency limit, or
the (optional) function concurrency limit, whichever is lower. Amazon Simple Queue Service supports
an initial burst of 5 concurrent function invocations and increases concurrency by 60 concurrent
invocations per minute.

Note

Account-level limits are impacted by other functions in the account, and per-function
concurrency applies to all events sent to a function. For more information, see Managing
Concurrency (p. 241).

Request Rate
Request rate refers to the rate at which your Lambda function is invoked. For all services except the pollbased services, the request rate is the rate at which the event sources generate the events. For poll-based
services, AWS Lambda calculates the request rate as follows:
request rate = number of concurrent executions / function duration

For example, if there are ﬁve active shards on a stream (that is, you have ﬁve Lambda functions running
in parallel) and your Lambda function takes about two seconds, the request rate is 2.5 requests/second.

Automatic Scaling
AWS Lambda dynamically scales function execution in response to increased traﬃc, up to your
concurrency limit (p. 249). Under sustained load, your function's concurrency bursts to an initial level
between 500 and 3000 concurrent executions that varies per region. After the initial burst, the function's
capacity increases by an additional 500 concurrent executions each minute until either the load is
accommodated, or the total concurrency of all functions in the region hits the limit.
Region

Initial concurrency burst

US East (Ohio), US West (N. California), Canada (Central)

500

69

AWS Lambda Developer Guide
Dead Letter Queues

Region

Initial concurrency burst

US West (Oregon), US East (N. Virginia)

3000

Asia Paciﬁc (Seoul), Asia Paciﬁc (Mumbai), Asia Paciﬁc
(Singapore), Asia Paciﬁc (Sydney)

500

Asia Paciﬁc (Tokyo)

1000

EU (London), EU (Paris), EU (Stockholm)

500

EU (Frankfurt)

1000

EU (Ireland)

3000

South America (São Paulo)

500

China (Beijing), China (Ningxia)

500

AWS GovCloud (US-West)

500

Note

If your function is connected to a VPC, the Amazon VPC network interface limit can prevent it
from scaling. For more information, see Conﬁguring a Lambda Function to Access Resources in
an Amazon VPC (p. 52).
To limit scaling, you can conﬁgure functions with reserved concurrency. For more information, see
Managing Concurrency (p. 241).

Dead Letter Queues
Any Lambda function invoked asynchronously is retried twice before the event is discarded. If the retries
fail and you're unsure why, use Dead Letter Queues (DLQ) to direct unprocessed events to an Amazon
SQS queue or an Amazon SNS topic to analyze the failure.
AWS Lambda directs events that cannot be processed to the speciﬁed Amazon SNS topic topic or
Amazon SQS queue. Functions that don't specify a DLQ will discard events after they have exhausted
their retries. For more information about retry policies, see AWS Lambda Retry Behavior (p. 67).
You conﬁgure a DLQ by specifying the Amazon Resource Name TargetArn value on the Lambda
function's DeadLetterConfig parameter.
{

"Code": {
"ZipFile": blob,
"S3Bucket": "string",
"S3Key": "string",
"S3ObjectVersion": "string"
},
"Description": "string",
"FunctionName": "string",
"Handler": "string",
"MemorySize": number,
"Role": "string",
"Runtime": "string",
"Timeout": number
"Publish": bool,
"DeadLetterConfig": {

70

AWS Lambda Developer Guide
Supported Event Sources

}

}

"TargetArn": "string"

In addition, you need to add permissions to the execution role (p. 222) of your Lambda function,
depending on which service you have directed unprocessed events:
• For Amazon SQS: SendMessage
• For Amazon SNS: Publish
The payload written to the DLQ target ARN is the original event payload with no modiﬁcations to the
message body. The attributes of the message contain information to help you understand why the event
wasn’t processed:

DLQ Message Attributes
Name

Type

Value

RequestID

String

Unique request identiﬁer

ErrorCode

Number

3-digit HTTP error code

ErrorMessage

String

Error message (truncated to
1 KB)

DLQ messages can fail to reach their target due to permissions issues, or if the total size of the message
exceeds the limit for the target queue or topic. For example, if an Amazon SNS notiﬁcation with a
body close to 256 KB triggers a function that results in an error, the additional event data added by
Amazon SNS, combined with the attributes added by Lambda, can cause the message to exceed the
maximum size allowed in the DLQ. When it can't write to the DLQ, Lambda deletes the event and emits
the DeadLetterErrors (p. 211) metric.

If you are using Amazon SQS as an event source, conﬁgure a DLQ on the Amazon SQS queue itself and
not the Lambda function. For more information, see Using AWS Lambda with Amazon SQS (p. 141).

Supported Event Sources
This topic lists the supported AWS services that you can conﬁgure as event sources for AWS Lambda
functions. After you preconﬁgure the event source mapping, your Lambda function gets invoked
automatically when these event sources detect events. For more information about invocation modes,
see AWS Lambda Event Source Mapping (p. 64).
For all of the event sources listed in this topic, note the following:
• Event sources maintain the event source mapping, except for the poll-based services (Amazon
Kinesis Data Streams, Amazon DynamoDB Streams and Amazon Simple Queue Service). For the
poll-based services, AWS Lambda maintains the event source mapping. AWS Lambda provides the
CreateEventSourceMapping (p. 364) operation for you to create and manage the event source
mapping. For more information, see AWS Lambda Event Source Mapping (p. 64).

71

AWS Lambda Developer Guide
Amazon S3

• The invocation type that these event sources use when invoking a Lambda function is also
preconﬁgured. For example, Amazon S3 always invokes a Lambda function asynchronously and
Amazon Cognito invokes a Lambda function synchronously. The only time you can control the
invocation type is when you are invoking the Lambda function yourself using the Invoke (p. 410)
operation (for example, invoking a Lambda function on demand from your custom application).
• In order to process AWS events, your Lambda functions may need to include additional libraries,
depending on the programming language used to create the function. Functions written in Node.js or
Python do not require any additional libraries. For C#, you need to include AWS Lambda for .NET Core.
For Java, you need to include aws-lambda-java-libs.

Important

Each of the included packages should be used without modiﬁcation. Removing dependencies,
adding conﬂicting dependencies, or selectively including classes from the packages can result
in unexpected behavior.
You can also invoke a Lambda function on demand. For details, see Other Event Sources: Invoking a
Lambda Function On Demand (p. 79).
For examples of events that are published by these event sources, see Sample Events Published by Event
Sources (p. 79).
Topics
• Amazon S3 (p. 72)
• Amazon DynamoDB (p. 73)
• Amazon Kinesis Data Streams (p. 73)
• Amazon Simple Notiﬁcation Service (p. 73)
• Amazon Simple Email Service (p. 74)
• Amazon Simple Queue Service (p. 74)
• Amazon Cognito (p. 75)
• AWS CloudFormation (p. 75)
• Amazon CloudWatch Logs (p. 75)
• Amazon CloudWatch Events (p. 76)
• AWS CodeCommit (p. 76)
• Scheduled Events (powered by Amazon CloudWatch Events) (p. 76)
• AWS Conﬁg (p. 77)
• Amazon Alexa (p. 77)
• Amazon Lex (p. 77)
• Amazon API Gateway (p. 77)
• AWS IoT Button (p. 78)
• Amazon CloudFront (p. 78)
• Amazon Kinesis Data Firehose (p. 78)
• Other Event Sources: Invoking a Lambda Function On Demand (p. 79)

Amazon S3
You can write Lambda functions to process S3 bucket events, such as the object-created or objectdeleted 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.

72

AWS Lambda Developer Guide
Amazon DynamoDB

You can use the bucket notiﬁcation conﬁguration feature in Amazon S3 to conﬁgure the event source
mapping, identifying the bucket events that you want Amazon S3 to publish and which Lambda function
to invoke.
For an example Amazon S3 event, see Event Message Structure, Amazon S3 Put Sample Event (p. 85),
and Amazon S3 Delete Sample Event (p. 85). For an example use case, see Using AWS Lambda with
Amazon S3 (p. 114).
Error handling for a given event source depends on how Lambda is invoked. Amazon S3 invokes your
Lambda function asynchronously. For more information on how errors are retried, see AWS Lambda
Retry Behavior (p. 67).

Amazon DynamoDB
You can use Lambda functions as triggers for your Amazon DynamoDB table. Triggers are custom actions
you take in response to updates made to the DynamoDB table. To create a trigger, ﬁrst you enable
Amazon DynamoDB Streams for your table. AWS Lambda polls the stream and your Lambda function
processes any updates published to the stream.
This is a stream-based event source. For a stream-based service, you create event source mapping in AWS
Lambda, identifying the stream to poll and which Lambda function to invoke.
For an example DynamoDB event, see Test the Lambda Function (p. 154) and Amazon DynamoDB
Update Sample Event (p. 82). For general format, see GetRecord in the Amazon DynamoDB API
Reference. For an example use case, see Using AWS Lambda with Amazon DynamoDB (p. 150).
Error handling for a given event source depends on how Lambda is invoked. DynamoDB is a streambased event source. For more information on how errors are retried, see AWS Lambda Retry
Behavior (p. 67).

Amazon Kinesis Data Streams
You can conﬁgure AWS Lambda to automatically poll your stream and process any new records such as
website click streams, ﬁnancial transactions, social media feeds, IT logs, and location-tracking events.
Then, AWS Lambda polls the stream periodically (once per second) for new records.
For stream-based services, you create event source mapping in AWS Lambda, identifying the stream to
poll and which Lambda function to invoke.
For an example event, see Amazon Kinesis Data Streams Sample Event (p. 84). For an example use
case, see Using AWS Lambda with Amazon Kinesis (p. 129).
Error handling for a given event source depends on how Lambda is invoked. Amazon Kinesis Data
Streams is a stream-based event source. For more information on how errors are retried, see AWS
Lambda Retry Behavior (p. 67).

Amazon Simple Notiﬁcation Service
You can write Lambda functions to process Amazon Simple Notiﬁcation Service notiﬁcations. 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.

73

AWS Lambda Developer Guide
Amazon Simple Email Service

You conﬁgure the event source mapping in Amazon SNS via topic subscription conﬁguration. For more
information, see Invoking Lambda functions using Amazon SNS notiﬁcations in the Amazon Simple
Notiﬁcation Service Developer Guide.
For an example event, see Appendix: Message and JSON Formats and Amazon SNS Sample
Event (p. 82). For an example use case, see Using AWS Lambda with Amazon SNS from Diﬀerent
Accounts (p. 168).
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.
Error handling for a given event source depends on how Lambda is invoked. Amazon SNS invokes your
Lambda function asynchronously. For more information on how errors are retried, see AWS Lambda
Retry Behavior (p. 67).

Amazon Simple Email Service
Amazon Simple Email Service (Amazon SES) is a cost-eﬀective email service. With Amazon SES, in
addition to sending emails, you can also use the service to receive messages. For more information about
Amazon SES, see Amazon Simple Email Service. When you use Amazon SES to receive messages, you
can conﬁgure Amazon SES to call your Lambda function when messages arrive. The service can then
invoke your Lambda function by passing in the incoming email event, which in reality is an Amazon SES
message in an Amazon SNS event, as a parameter. For example scenarios, see Considering Your Use Case
for Amazon SES Email Receiving.
You conﬁgure event source mapping using the rule conﬁguration in Amazon SES. The following topics
provide additional information in the Amazon Simple Email Service Developer Guide:
• For sample events, see Lambda Action and Amazon SES Email Receiving Sample Event (p. 80).
• For Lambda function examples, see Lambda Function Examples.
Error handling for a given event source depends on how Lambda is invoked. Amazon SES invokes your
Lambda function asynchronously. For more information on how errors are retried, see AWS Lambda
Retry Behavior (p. 67).

Amazon Simple Queue Service
Amazon Simple Queue Service (Amazon SQS) allows you to build asynchronous workﬂows. For more
information about Amazon SQS, see Amazon Simple Queue Service. You can conﬁgure 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 (p. 87).
To set up Amazon Simple Queue Service as an event source for AWS Lambda, you ﬁrst 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:
• VisibilityTimeout: May impact the period between retries.
• TimeToWait: Will determine long poll duration. The default value is 20 seconds.
For more information, see What is Amazon Simple Queue Service?. You then create your AWS Lambda
function by adding your function code that handles processing of the Amazon SQS queue messages.

74

AWS Lambda Developer Guide
Amazon Cognito

Finally, you can conﬁgure AWS Lambda to respond to new messages available on Amazon SQS queues
using one of the following API operations:
• CreateEventSourceMapping (p. 364)
• UpdateEventSourceMapping (p. 462)
Error handling for a given event source depends on how Lambda is invoked. Amazon SQS is a poll-based
service. For more information on how errors are retried, see AWS Lambda Retry Behavior (p. 67).

Amazon Cognito
The Amazon Cognito Events feature enables you to run Lambda functions in response to events in
Amazon Cognito. For example, you can invoke a Lambda function for the Sync Trigger events, that
is published each time a dataset is synchronized. To learn more and walk through an example, see
Introducing Amazon Cognito Events: Sync Triggers in the Mobile Development blog.
You conﬁgure event source mapping using Amazon Cognito event subscription conﬁguration. For
information about event source mapping and a sample event, see Amazon Cognito Events in the
Amazon Cognito Developer Guide. For another example event, see Amazon Cognito Sync Trigger Sample
Event (p. 84)
Error handling for a given event source depends on how Lambda is invoked. Amazon Cognito is
conﬁgured to invoke a Lambda function synchronously. For more information on how errors are retried,
see AWS Lambda Retry Behavior (p. 67).

AWS CloudFormation
As part of deploying AWS CloudFormation stacks, you can specify a Lambda function as a custom
resource to execute any custom commands. Associating a Lambda function with a custom
resource enables you to invoke your Lambda function whenever you create, update, or delete AWS
CloudFormation stacks.
You conﬁgure event source mapping in AWS CloudFormation using stack deﬁnition. For more
information, see AWS Lambda-backed Custom Resources in the AWS CloudFormation User Guide.
For an example event, see AWS CloudFormation Create Request Sample Event (p. 80). Note that this
event is actually a AWS CloudFormation message in an Amazon SNS event.
Error handling for a given event source depends on how Lambda is invoked. AWS CloudFormation
invokes your Lambda function synchronously. For more information on how errors are retried, see AWS
Lambda Retry Behavior (p. 67).

Amazon CloudWatch Logs
You can use AWS Lambda functions to perform custom analysis on Amazon CloudWatch Logs using
CloudWatch Logs subscriptions. CloudWatch Logs subscriptions provide access to a real-time feed of
log events from CloudWatch Logs and deliver it to your AWS Lambda function for custom processing,
analysis, or loading to other systems. For more information about CloudWatch Logs, see Monitoring Log
Files.
You maintain event source mapping in Amazon CloudWatch Logs using the log subscription
conﬁguration. For more information, see Real-time Processing of Log Data with Subscriptions (Example
2: AWS Lambda) in the Amazon CloudWatch User Guide.
For an example event, see Amazon CloudWatch Logs Sample Event (p. 82).

75

AWS Lambda Developer Guide
Amazon CloudWatch Events

Error handling for a given event source depends on how Lambda is invoked. Amazon CloudWatch
Logs invokes your Lambda function asynchronously (invoking a Lambda function does not block
write operation into the logs). For more information on how errors are retried, see AWS Lambda Retry
Behavior (p. 67).

Amazon CloudWatch Events
Amazon CloudWatch Events help you to respond to state changes in your AWS resources. When your
resources change state, they automatically send events into an event stream. You can create rules that
match selected events in the stream and route them to your AWS Lambda function to take action. For
example, you can automatically invoke an AWS Lambda function to log the state of an EC2 instance or
AutoScaling Group.
You maintain event source mapping in Amazon CloudWatch Events by using a rule target deﬁnition. For
more information, see the PutTargets operation in the Amazon CloudWatch Events API Reference.
For sample events, see Supported Event Types in the Amazon CloudWatch User Guide.
Error handling for a given event source depends on how Lambda is invoked. Amazon CloudWatch Events
invokes your Lambda function asynchronously. For more information on how errors are retried, see AWS
Lambda Retry Behavior (p. 67).

AWS CodeCommit
You can create a trigger for an AWS CodeCommit repository so that events in the repository will invoke
a Lambda function. For example, you can invoke a Lambda function when a branch or tag is created
or when a push is made to an existing branch. For more information, see Manage Triggers for an AWS
CodeCommit Repository.
You maintain the event source mapping in AWS CodeCommit by using a repository trigger. For more
information, see the PutRepositoryTriggers operation.
Error handling for a given event source depends on how Lambda is invoked. AWS CodeCommit invokes
your Lambda function asynchronously. For more information on how errors are retried, see AWS Lambda
Retry Behavior (p. 67).

Scheduled Events (powered by Amazon CloudWatch
Events)
You can also set up AWS Lambda to invoke your code on a regular, scheduled basis using the schedule
event capability in Amazon CloudWatch Events. To set a schedule you can specify a ﬁxed rate (number
of hours, days, or weeks) or specify a cron expression (see Schedule Expression Syntax for Rules in the
Amazon CloudWatch User Guide).
You maintain event source mapping in Amazon CloudWatch Events by using a rule target deﬁnition. For
more information, see the PutTargets operation in the Amazon CloudWatch Events API Reference.
For an example use case, see Using AWS Lambda with Amazon CloudWatch Events (p. 195).
For an example event, see Scheduled Event Sample Event (p. 81).
Error handling for a given event source depends on how Lambda is invoked. Amazon CloudWatch Events
is conﬁgured to invoke a Lambda function asynchronously. For more information on how errors are
retried, see AWS Lambda Retry Behavior (p. 67).

76

AWS Lambda Developer Guide
AWS Conﬁg

AWS Conﬁg
You can use AWS Lambda functions to evaluate whether your AWS resource conﬁgurations comply
with your custom Conﬁg rules. As resources are created, deleted, or changed, AWS Conﬁg records these
changes and sends the information to your Lambda functions. Your Lambda functions then evaluate
the changes and report results to AWS Conﬁg. You can then use AWS Conﬁg to assess overall resource
compliance: you can learn which resources are noncompliant and which conﬁguration attributes are the
cause of noncompliance.
You maintain event source mapping in AWS Conﬁg by using a rule target deﬁnition. For more
information, see the PutConﬁgRule operation in the AWS Conﬁg API reference.
For more information, see Evaluating Resources With AWS Conﬁg Rules. For an example of setting a
custom rule, see Developing a Custom Rule for AWS Conﬁg. For example Lambda functions, see Example
AWS Lambda Functions for AWS Conﬁg Rules (Node.js).
Error handling for a given event source depends on how Lambda is invoked. AWS Conﬁg is conﬁgured
to invoke a Lambda function asynchronously. For more information on how errors are retried, see AWS
Lambda Retry Behavior (p. 67).

Amazon Alexa
You can use Lambda functions to build services that give new skills to Alexa, the Voice assistant on
Amazon Echo. The Alexa Skills Kit provides the APIs, tools, and documentation to create these new skills,
powered by your own services running as Lambda functions. Amazon Echo users can access these new
skills by asking Alexa questions or making requests. For more information, see:
• Getting Started with Alexa Skills Kit.
• alexa-skills-kit-sdk-for-nodejs
• alexa-skills-kit-java
Error handling for a given event source depends on how Lambda is invoked. Amazon Echo is conﬁgured
to invoke a Lambda function synchronously. For more information on how errors are retried, see AWS
Lambda Retry Behavior (p. 67).

Amazon Lex
Amazon Lex is an AWS service for building conversational interfaces into applications using voice and
text. Amazon Lex provides pre-build integration with AWS Lambda, allowing you to create Lambda
functions for use as code hook with your Amazon Lex bot. In your intent conﬁguration, you can identify
your Lambda function to perform initialization/validation, fulﬁllment, or both.
For more information, see Using Lambda Functions. For an example use case, see Exercise 1: Create
Amazon Lex Bot Using a Blueprint.
Error handling for a given event source depends on how Lambda is invoked. Amazon Lex is conﬁgured
to invoke a Lambda function synchronously. For more information on how errors are retried, see AWS
Lambda Retry Behavior (p. 67).

Amazon API Gateway
You can invoke a Lambda function over HTTPS. You can do this by deﬁning a custom REST API endpoint
using Amazon API Gateway. You map individual API operations, such as GET and PUT, to speciﬁc Lambda
functions. When you send an HTTPS request to the API endpoint, the Amazon API Gateway service
invokes the corresponding Lambda function.

77

AWS Lambda Developer Guide
AWS IoT Button

For more information, see Make Synchronous Calls to Lambda Functions. For an example use case, see
Using AWS Lambda with Amazon API Gateway (p. 173).
Error handling for a given event source depends on how Lambda is invoked. Amazon API Gateway is
conﬁgured to invoke a Lambda function synchronously. For more information on how errors are retried,
see AWS Lambda Retry Behavior (p. 67).
In addition, you can also use Lambda functions with other AWS services that publish data to one of the
supported AWS event sources listed in this topic. For example, you can:
• Trigger Lambda functions in response to CloudTrail updates because it records all API access events to
an Amazon S3 bucket.
• Trigger Lambda functions in response to CloudWatch alarms because it publishes alarm events to an
Amazon SNS topic.

AWS IoT Button
The AWS IoT button is a programmable button based on the Amazon Dash Button hardware. This simple
Wi-Fi device is easy to conﬁgure and designed for developers to get started with AWS Lambda, among
many other AWS services, without writing device-speciﬁc code.
You can code the button's logic in the cloud to conﬁgure button clicks to count or track items, call or
alert someone, start or stop something, order services, or even provide feedback. For example, you can
click the button to unlock or start a car, open your garage door, call a cab, call your spouse or a customer
service representative, track the use of common household chores, medications or products, or remotely
control your home appliances.
Error handling for a given event source depends on how Lambda is invoked. AWS IoT is conﬁgured to
invoke a Lambda function asynchronously. For more information on how errors are retried, see AWS
Lambda Retry Behavior (p. 67).

Amazon CloudFront
Lambda@Edge lets you run Lambda functions at AWS Regions and Amazon CloudFront edge locations in
response to CloudFront events, without provisioning or managing servers. You can use Lambda functions
to change CloudFront requests and responses at the following points:
• After CloudFront receives a request from a viewer (viewer request)
• Before CloudFront forwards the request to the origin (origin request)
• After CloudFront receives the response from the origin (origin response)
• Before CloudFront forwards the response to the viewer (viewer response)
For more information, see Lambda@Edge (p. 206)
Error handling for a given event source depends on how Lambda is invoked. CloudFront is conﬁgured
to invoke a Lambda function synchronously. For more information on how errors are retried, see AWS
Lambda Retry Behavior (p. 67).

Amazon Kinesis Data Firehose
Amazon Kinesis Data Firehose is the easiest way to load streaming data into AWS. It can capture,
transform, and load streaming data into downstream services such as Kinesis Data Analytics or Amazon
S3, enabling near real-time analytics with existing business intelligence tools and dashboards you’re

78

AWS Lambda Developer Guide
Other Event Sources: Invoking
a Lambda Function On Demand

already using today. You can write Lambda functions to request additional, customized processing of the
data before it is sent downstream.
Error handling for a given event source depends on how Lambda is invoked. Kinesis Data Firehose is
conﬁgured to invoke a Lambda function synchronously. For more information on how errors are retried,
see AWS Lambda Retry Behavior (p. 67).

Other Event Sources: Invoking a Lambda Function On
Demand
In addition to invoking Lambda functions using event sources, you can also invoke your Lambda function
on demand. You don't need to preconﬁgure any event source mapping in this case. However, make sure
that the custom application has the necessary permissions to invoke your Lambda function.
For example, user applications can also generate events (build your own custom event sources). User
applications such as client, mobile, or web applications can publish events and invoke Lambda functions
using the AWS SDKs or AWS Mobile SDKs such as the AWS Mobile SDK for Android.
For more information, see Tools for Amazon Web Services. For an example tutorial, see Using AWS
Lambda with Amazon API Gateway (p. 173).

Sample Events Published by Event Sources
The following is a list of example events published by the supported AWS services. For more information
about the supported AWS event sources, see Supported Event Sources (p. 71).

Note

JSON keys may vary in case between AWS event sources.

Sample Events
• AWS CloudFormation Create Request Sample Event (p. 80)
• Amazon SES Email Receiving Sample Event (p. 80)
• Scheduled Event Sample Event (p. 81)
• Amazon CloudWatch Logs Sample Event (p. 82)
• Amazon SNS Sample Event (p. 82)
• Amazon DynamoDB Update Sample Event (p. 82)
• Amazon Cognito Sync Trigger Sample Event (p. 84)
• Amazon Kinesis Data Streams Sample Event (p. 84)
• Amazon S3 Put Sample Event (p. 85)
• Amazon S3 Delete Sample Event (p. 85)
• Amazon Lex Sample Event (p. 86)
• API Gateway Proxy Request Event (p. 86)
• API Gateway Proxy Response Event (p. 88)
• Amazon SQS Event (p. 87)
• CloudFront Event (p. 88)
• AWS Conﬁg Event (p. 89)
• AWS IoT Button Event (p. 89)
• Kinesis Data Firehose Event (p. 89)

79

AWS Lambda Developer Guide
Sample Event Data

AWS CloudFormation Create Request Sample Event
{

}

"StackId": "arn:aws:cloudformation:us-west-2:EXAMPLE/stack-name/guid",
"ResponseURL": "http://pre-signed-S3-url-for-response",
"ResourceProperties": {
"StackName": "stack-name",
"List": [
"1",
"2",
"3"
]
},
"RequestType": "Create",
"ResourceType": "Custom::TestResource",
"RequestId": "unique id for this create request",
"LogicalResourceId": "MyTestResource"

Amazon SES Email Receiving Sample Event
{

"Records": [
{
"eventVersion": "1.0",
"ses": {
"mail": {
"commonHeaders": {
"from": [
"Jane Doe "
],
"to": [
"johndoe@example.com"
],
"returnPath": "janedoe@example.com",
"messageId": "<0123456789example.com>",
"date": "Wed, 7 Oct 2015 12:34:56 -0700",
"subject": "Test Subject"
},
"source": "janedoe@example.com",
"timestamp": "1970-01-01T00:00:00.000Z",
"destination": [
"johndoe@example.com"
],
"headers": [
{
"name": "Return-Path",
"value": ""
},
{
"name": "Received",
"value": "from mailer.example.com (mailer.example.com [203.0.113.1])
by inbound-smtp.us-west-2.amazonaws.com with SMTP id o3vrnil0e2ic for
johndoe@example.com; Wed, 07 Oct 2015 12:34:56 +0000 (UTC)"
},
{
"name": "DKIM-Signature",
"value": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com;
s=example; h=mime-version:from:date:message-id:subject:to:content-type;
bh=jX3F0bCAI7sIbkHyy3mLYO28ieDQz2R0P8HwQkklFj4=; b=sQwJ+LMe9RjkesGu
+vqU56asvMhrLRRYrWCbV"
},
{
"name": "MIME-Version",

80

AWS Lambda Developer Guide
Sample Event Data
"value": "1.0"

},
{

"name": "From",
"value": "Jane Doe "

},
{

"name": "Date",
"value": "Wed, 7 Oct 2015 12:34:56 -0700"

},
{

"name": "Message-ID",
"value": "<0123456789example.com>"

},
{

"name": "Subject",
"value": "Test Subject"

},
{

"name": "To",
"value": "johndoe@example.com"

},
{

"name": "Content-Type",
"value": "text/plain; charset=UTF-8"

}
],
"headersTruncated": false,
"messageId": "o3vrnil0e2ic28tr"

},
"receipt": {
"recipients": [
"johndoe@example.com"
],
"timestamp": "1970-01-01T00:00:00.000Z",
"spamVerdict": {
"status": "PASS"
},
"dkimVerdict": {
"status": "PASS"
},
"processingTimeMillis": 574,
"action": {
"type": "Lambda",
"invocationType": "Event",
"functionArn": "arn:aws:lambda:us-west-2:012345678912:function:Example"
},
"spfVerdict": {
"status": "PASS"
},
"virusVerdict": {
"status": "PASS"
}
}

}

]

}

},
"eventSource": "aws:ses"

Scheduled Event Sample Event
{

"account": "123456789012",
"region": "us-east-1",

81

AWS Lambda Developer Guide
Sample Event Data

}

"detail": {},
"detail-type": "Scheduled Event",
"source": "aws.events",
"time": "1970-01-01T00:00:00Z",
"id": "cdc73f9d-aea9-11e3-9d5a-835b769c0d9c",
"resources": [
"arn:aws:events:us-east-1:123456789012:rule/my-schedule"
]

Amazon CloudWatch Logs Sample Event
{

"awslogs": {
"data": "H4sIAAAAAAAAAHWPwQqCQBCGX0Xm7EFtK
+smZBEUgXoLCdMhFtKV3akI8d0bLYmibvPPN3wz00CJxmQnTO41whwWQRIctmEcB6sQbFC3CjW3XW8kxpOpP
+OC22d1Wml1qZkQGtoMsScxaczKN3plG8zlaHIta5KqWsozoTYw3/djzwhpLwivWFGHGpAFe7DL68JlBUk
+l7KSN7tCOEJ4M3/qOI49vMHj+zCKdlFqLaU2ZHV2a4Ct/an0/ivdX8oYc1UVX860fQDQiMdxRQEAAA=="
}
}

Amazon SNS Sample Event
{

}

"Records": [
{
"EventVersion": "1.0",
"EventSubscriptionArn": eventsubscriptionarn,
"EventSource": "aws:sns",
"Sns": {
"SignatureVersion": "1",
"Timestamp": "1970-01-01T00:00:00.000Z",
"Signature": "EXAMPLE",
"SigningCertUrl": "EXAMPLE",
"MessageId": "95df01b4-ee98-5cb9-9903-4c221d41eb5e",
"Message": "Hello from SNS!",
"MessageAttributes": {
"Test": {
"Type": "String",
"Value": "TestString"
},
"TestBinary": {
"Type": "Binary",
"Value": "TestBinary"
}
},
"Type": "Notification",
"UnsubscribeUrl": "EXAMPLE",
"TopicArn": topicarn,
"Subject": "TestInvoke"
}
}
]

Amazon DynamoDB Update Sample Event
{

"Records": [
{
"eventID": "1",
"eventVersion": "1.0",

82

AWS Lambda Developer Guide
Sample Event Data
"dynamodb": {
"Keys": {
"Id": {
"N": "101"
}
},
"NewImage": {
"Message": {
"S": "New item!"
},
"Id": {
"N": "101"
}
},
"StreamViewType": "NEW_AND_OLD_IMAGES",
"SequenceNumber": "111",
"SizeBytes": 26
},
"awsRegion": "us-west-2",
"eventName": "INSERT",
"eventSourceARN": eventsourcearn,
"eventSource": "aws:dynamodb"

},
{

"eventID": "2",
"eventVersion": "1.0",
"dynamodb": {
"OldImage": {
"Message": {
"S": "New item!"
},
"Id": {
"N": "101"
}
},
"SequenceNumber": "222",
"Keys": {
"Id": {
"N": "101"
}
},
"SizeBytes": 59,
"NewImage": {
"Message": {
"S": "This item has changed"
},
"Id": {
"N": "101"
}
},
"StreamViewType": "NEW_AND_OLD_IMAGES"
},
"awsRegion": "us-west-2",
"eventName": "MODIFY",
"eventSourceARN": sourcearn,
"eventSource": "aws:dynamodb"

},
{

"eventID": "3",
"eventVersion": "1.0",
"dynamodb": {
"Keys": {
"Id": {
"N": "101"
}
},

83

AWS Lambda Developer Guide
Sample Event Data
"SizeBytes": 38,
"SequenceNumber": "333",
"OldImage": {
"Message": {
"S": "This item has changed"
},
"Id": {
"N": "101"
}
},
"StreamViewType": "NEW_AND_OLD_IMAGES"

}

]

}

},
"awsRegion": "us-west-2",
"eventName": "REMOVE",
"eventSourceARN": sourcearn,
"eventSource": "aws:dynamodb"

Amazon Cognito Sync Trigger Sample Event

}

{
"datasetName": "datasetName",
"eventType": "SyncTrigger",
"region": "us-east-1",
"identityId": "identityId",
"datasetRecords": {
"SampleKey2": {
"newValue": "newValue2",
"oldValue": "oldValue2",
"op": "replace"
},
"SampleKey1": {
"newValue": "newValue1",
"oldValue": "oldValue1",
"op": "replace"
}
},
"identityPoolId": "identityPoolId",
"version": 2

Amazon Kinesis Data Streams Sample Event
{
"Records": [
{
"eventID":
"shardId-000000000000:49545115243490985018280067714973144582180062593244200961",
"eventVersion": "1.0",
"kinesis": {
"partitionKey": "partitionKey-3",
"data": "SGVsbG8sIHRoaXMgaXMgYSB0ZXN0IDEyMy4=",
"kinesisSchemaVersion": "1.0",
"sequenceNumber": "49545115243490985018280067714973144582180062593244200961"
},
"invokeIdentityArn": identityarn,
"eventName": "aws:kinesis:record",

84

AWS Lambda Developer Guide
Sample Event Data

}

]

}

"eventSourceARN": eventsourcearn,
"eventSource": "aws:kinesis",
"awsRegion": "us-east-1"

Amazon S3 Put Sample Event
{

"Records": [
{
"eventVersion": "2.0",
"eventTime": "1970-01-01T00:00:00.000Z",
"requestParameters": {
"sourceIPAddress": "127.0.0.1"
},
"s3": {
"configurationId": "testConfigRule",
"object": {
"eTag": "0123456789abcdef0123456789abcdef",
"sequencer": "0A1B2C3D4E5F678901",
"key": "HappyFace.jpg",
"size": 1024
},
"bucket": {
"arn": bucketarn,
"name": "sourcebucket",
"ownerIdentity": {
"principalId": "EXAMPLE"
}
},
"s3SchemaVersion": "1.0"
},
"responseElements": {
"x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/
mnopqrstuvwxyzABCDEFGH",
"x-amz-request-id": "EXAMPLE123456789"
},
"awsRegion": "us-east-1",
"eventName": "ObjectCreated:Put",
"userIdentity": {
"principalId": "EXAMPLE"
},
"eventSource": "aws:s3"
}
]
}

Amazon S3 Delete Sample Event

{
"Records": [
{
"eventVersion": "2.0",
"eventTime": "1970-01-01T00:00:00.000Z",
"requestParameters": {
"sourceIPAddress": "127.0.0.1"
},
"s3": {
"configurationId": "testConfigRule",

85

AWS Lambda Developer Guide
Sample Event Data
"object": {
"sequencer": "0A1B2C3D4E5F678901",
"key": "HappyFace.jpg"
},
"bucket": {
"arn": bucketarn,
"name": "sourcebucket",
"ownerIdentity": {
"principalId": "EXAMPLE"
}
},
"s3SchemaVersion": "1.0"

},
"responseElements": {
"x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/
mnopqrstuvwxyzABCDEFGH",
"x-amz-request-id": "EXAMPLE123456789"
},
"awsRegion": "us-east-1",
"eventName": "ObjectRemoved:Delete",
"userIdentity": {
"principalId": "EXAMPLE"
},
"eventSource": "aws:s3"
}
]
}

Amazon Lex Sample Event
{

"messageVersion": "1.0",
"invocationSource": "FulfillmentCodeHook or DialogCodeHook",
"userId": "user-id specified in the POST request to Amazon Lex.",
"sessionAttributes": {
"key1": "value1",
"key2": "value2",
},
"bot": {
"name": "bot-name",
"alias": "bot-alias",
"version": "bot-version"
},
"outputDialogMode": "Text or Voice, based on ContentType request header in runtime
API request",
"currentIntent": {
"name": "intent-name",
"slots": {
"slot-name": "value",
"slot-name": "value",
"slot-name": "value"
},
"confirmationStatus": "None, Confirmed, or Denied
(intent confirmation, if configured)"
}

}

API Gateway Proxy Request Event
{

"path": "/test/hello",

86

AWS Lambda Developer Guide
Sample Event Data
"headers": {
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/
*;q=0.8",
"Accept-Encoding": "gzip, deflate, lzma, sdch, br",
"Accept-Language": "en-US,en;q=0.8",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Desktop-Viewer": "true",
"CloudFront-Is-Mobile-Viewer": "false",
"CloudFront-Is-SmartTV-Viewer": "false",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Viewer-Country": "US",
"Host": "wt6mne2s9k.execute-api.us-west-2.amazonaws.com",
"Upgrade-Insecure-Requests": "1",
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/52.0.2743.82 Safari/537.36 OPR/39.0.2256.48",
"Via": "1.1 fb7cca60f0ecd82ce07790c9c5eef16c.cloudfront.net (CloudFront)",
"X-Amz-Cf-Id": "nBsWBOrSHMgnaROZJK1wGCZ9PcRcSpq_oSXZNQwQ10OTZL4cimZo3g==",
"X-Forwarded-For": "192.168.100.1, 192.168.1.1",
"X-Forwarded-Port": "443",
"X-Forwarded-Proto": "https"
},
"pathParameters": {
"proxy": "hello"
},
"requestContext": {
"accountId": "123456789012",
"resourceId": "us4z18",
"stage": "test",
"requestId": "41b45ea3-70b5-11e6-b7bd-69b5aaebc7d9",
"identity": {
"cognitoIdentityPoolId": "",
"accountId": "",
"cognitoIdentityId": "",
"caller": "",
"apiKey": "",
"sourceIp": "192.168.100.1",
"cognitoAuthenticationType": "",
"cognitoAuthenticationProvider": "",
"userArn": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/52.0.2743.82 Safari/537.36 OPR/39.0.2256.48",
"user": ""
},
"resourcePath": "/{proxy+}",
"httpMethod": "GET",
"apiId": "wt6mne2s9k"
},
"resource": "/{proxy+}",
"httpMethod": "GET",
"queryStringParameters": {
"name": "me"
},
"stageVariables": {
"stageVarName": "stageVarValue"
}
}

Amazon SQS Event

{

"Records": [
{
"messageId": "c80e8021-a70a-42c7-a470-796e1186f753",

87

AWS Lambda Developer Guide
Sample Event Data

"receiptHandle": "AQEBJQ+/u6NsnT5t8Q/
VbVxgdUl4TMKZ5FqhksRdIQvLBhwNvADoBxYSOVeCBXdnS9P
+erlTtwEALHsnBXynkfPLH3BOUqmgzP25U8kl8eHzq6RAlzrSOfTO8ox9dcp6GLmW33YjO3zkq5VRYyQlJgLCiAZUpY2D4UQcE5
+xtVaOctYeINjaQJ1u3mWx9T7tork3uAlOe1uyFjCWU5aPX/1OHhWCGi2EPPZj6vchNqDOJC/
Y2k1gkivqCjz1CZl6FlZ7UVPOx3AMoszPuOYZ
+Nuqpx2uCE2MHTtMHD8PVjlsWirt56oUr6JPp9aRGo6bitPIOmi4dX0FmuMKD6u/JnuZCp+AXtJVTmSHS8IXt/
twsKU7A+fiMK01NtD5msNgVPoe9JbFtlGwvTQ==",
"body": "{\"foo\":\"bar\"}",
"attributes": {
"ApproximateReceiveCount": "3",
"SentTimestamp": "1529104986221",
"SenderId": "594035263019",
"ApproximateFirstReceiveTimestamp": "1529104986230"
},
"messageAttributes": {},
"md5OfBody": "9bb58f26192e4ba00f01e2e7b136bbd8",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-west-2:594035263019:NOTFIFOQUEUE",
"awsRegion": "us-west-2"
}
]
}

API Gateway Proxy Response Event
{

"statusCode": 200,
"headers": {
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/
*;q=0.8",
"Accept-Encoding": "gzip, deflate, lzma, sdch, br",
"Accept-Language": "en-US,en;q=0.8",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Desktop-Viewer": "true",
"CloudFront-Is-Mobile-Viewer": "false",
"CloudFront-Is-SmartTV-Viewer": "false",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Viewer-Country": "US",
"Host": "wt6mne2s9k.execute-api.us-west-2.amazonaws.com",
"Upgrade-Insecure-Requests": "1",
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/52.0.2743.82 Safari/537.36 OPR/39.0.2256.48",
"Via": "1.1 fb7cca60f0ecd82ce07790c9c5eef16c.cloudfront.net (CloudFront)",
"X-Amz-Cf-Id": "nBsWBOrSHMgnaROZJK1wGCZ9PcRcSpq_oSXZNQwQ10OTZL4cimZo3g==",
"X-Forwarded-For": "192.168.100.1, 192.168.1.1",
"X-Forwarded-Port": "443",
"X-Forwarded-Proto": "https"
},
"body": "Hello World"
}

CloudFront Event
{

"Records": [
{
"cf": {
"config": {
"distributionId": "EDFDVBD6EXAMPLE"
},
"request": {
"clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334",
"method": "GET",

88

AWS Lambda Developer Guide
Sample Event Data

}

]

}

}

}

"uri": "/picture.jpg",
"headers": {
"host": [
{
"key": "Host",
"value": "d111111abcdef8.cloudfront.net"
}
],
"user-agent": [
{
"key": "User-Agent",
"value": "curl/7.51.0"
}
]
}

AWS Conﬁg Event
{

"invokingEvent": "{\"configurationItem\":{\"configurationItemCaptureTime
\":\"2016-02-17T01:36:34.043Z\",\"awsAccountId\":\"000000000000\",
\"configurationItemStatus\":\"OK\",\"resourceId\":\"i-00000000\",\"ARN
\":\"arn:aws:ec2:us-east-1:000000000000:instance/i-00000000\",\"awsRegion
\":\"us-east-1\",\"availabilityZone\":\"us-east-1a\",\"resourceType\":
\"AWS::EC2::Instance\",\"tags\":{\"Foo\":\"Bar\"},\"relationships\":[{\"resourceId
\":\"eipalloc-00000000\",\"resourceType\":\"AWS::EC2::EIP\",\"name\":\"Is
attached to ElasticIp\"}],\"configuration\":{\"foo\":\"bar\"}},\"messageType\":
\"ConfigurationItemChangeNotification\"}",
"ruleParameters": "{\"myParameterKey\":\"myParameterValue\"}",
"resultToken": "myResultToken",
"eventLeftScope": false,
"executionRoleArn": "arn:aws:iam::012345678912:role/config-role",
"configRuleArn": "arn:aws:config:us-east-1:012345678912:config-rule/configrule-0123456",
"configRuleName": "change-triggered-config-rule",
"configRuleId": "config-rule-0123456",
"accountId": "012345678912",
"version": "1.0"
}

AWS IoT Button Event
{

}

"serialNumber": "ABCDEFG12345",
"clickType": "SINGLE",
"batteryVoltage": "2000 mV"

Kinesis Data Firehose Event
{

"invocationId": "invoked123",
"deliveryStreamArn": "aws:lambda:events",
"region": "us-west-2",

89

AWS Lambda Developer Guide
Sample Event Data

}

"records": [
{
"data": "SGVsbG8gV29ybGQ=",
"recordId": "record1",
"approximateArrivalTimestamp": 1510772160000,
"kinesisRecordMetadata": {
"shardId": "shardId-000000000000",
"partitionKey": "4d1ad2b9-24f8-4b9d-a088-76e9947c317a",
"approximateArrivalTimestamp": "2012-04-23T18:25:43.511Z",
"sequenceNumber": "49546986683135544286507457936321625675700192471156785154",
"subsequenceNumber": ""
}
},
{
"data": "SGVsbG8gV29ybGQ=",
"recordId": "record2",
"approximateArrivalTimestamp": 151077216000,
"kinesisRecordMetadata": {
"shardId": "shardId-000000000001",
"partitionKey": "4d1ad2b9-24f8-4b9d-a088-76e9947c318a",
"approximateArrivalTimestamp": "2012-04-23T19:25:43.511Z",
"sequenceNumber": "49546986683135544286507457936321625675700192471156785155",
"subsequenceNumber": ""
}
}
]

90

AWS Lambda Developer Guide

AWS Lambda Runtimes
AWS Lambda supports multiple languages through the use of runtimes. You choose a runtime when
you create a function, and you can change runtimes by updating your function's conﬁguration. The
underlying execution environment (p. 92), which is shared by all runtimes, provides additional libraries
and environment variables that you can access from your function code.
When your function is invoked, Lambda attempts to re-use the execution environment from a previous
invocation if one is available. This saves time preparing the execution environment, and allows you to
save resources like database connections and temporary ﬁles in the execution context (p. 93) to avoid
creating them every time your function runs.
A runtime can support a single version of a language, multiple versions of a language, or multiple
languages. Runtimes speciﬁc to a language or framework version are deprecated (p. 94) when the
version reaches end of life.
To use other languages in Lambda, you can implement a custom runtime (p. 95). The Lambda
execution environment provides a runtime interface (p. 97) for getting invocation events and sending
responses. You can deploy a custom runtime alongside your function code, or in a layer (p. 47).

Node.js Runtimes
Name

Identiﬁer

Node.js 8.10

nodejs8.10

Node.js 6.10

nodejs6.10

Python Runtimes
Name

Identiﬁer

Python 3.6

python3.6

Python 3.7

python3.7

Python 2.7

python2.7

Ruby Runtimes
Name

Identiﬁer

Ruby 2.5

ruby2.5

Java Runtimes
Name

Identiﬁer

JDK

Java 8

java8

java-1.8.0-openjdk

91

AWS Lambda Developer Guide
Execution Environment

Go Runtimes
Name

Identiﬁer

Go 1.x

go1.x

.NET Runtimes
Name

Identiﬁer

Languages

.NET Core 2.1

dotnetcore2.1

C#
PowerShell Core 6.0

.NET Core 2.0

dotnetcore2.0

C#

.NET Core 1.0

dotnetcore1.0

C#

Topics
• Lambda Execution Environment and Available Libraries (p. 92)
• AWS Lambda Execution Context (p. 93)
• Runtime Support Policy (p. 94)
• Custom AWS Lambda Runtimes (p. 95)
• AWS Lambda Runtime Interface (p. 97)
• Tutorial – Publishing a Custom Runtime (p. 99)

Lambda Execution Environment and Available
Libraries
The underlying AWS Lambda execution environment includes the following software and libraries.
• Operating system – Amazon Linux
• AMI – amzn-ami-hvm-2017.03.1.20170812-x86_64-gp2
• Linux kernel – 4.14.77-70.59.amzn1.x86_64
• AWS SDK for JavaScript – 2.290.0
• SDK for Python (Boto 3) – 3-1.7.74 botocore-1.10.74
Not all runtime languages are available on the Amazon Linux AMI or its yum repositories. If you use
Amazon Linux for development, you might need to download and install them manually from their
respective public sites.

Environment Variables Available to Lambda
Functions
The following is a list of environment variables that are part of the AWS Lambda execution environment
and made available to Lambda functions. The table below indicates which ones are reserved by AWS
Lambda and can't be changed, as well as which ones you can set when creating your Lambda function.

92

AWS Lambda Developer Guide
Execution Context

For more information on using environment variables with your Lambda function, see AWS Lambda
Environment Variables (p. 23).

Lambda Environment Variables
Key

Reserved Value

_HANDLER

Yes

The handler location conﬁgured on the function.

AWS_REGION

Yes

The AWS region where the Lambda function is executed.

AWS_EXECUTION_ENV

Yes

The runtime identiﬁer (p. 91), preﬁxed by AWS_Lambda_.
For example, AWS_Lambda_java8.

AWS_LAMBDA_FUNCTION_NAME Yes

The name of the function.

AWS_LAMBDA_FUNCTION_MEMORY_SIZE
Yes
The amount of memory available to the function in MB.
AWS_LAMBDA_FUNCTION_VERSION
Yes

The version of the function being executed.

AWS_LAMBDA_LOG_GROUP_NAMEYes

The name of the Amazon CloudWatch Logs group and
stream for the function.

AWS_LAMBDA_LOG_STREAM_NAME
Yes

Access keys obtained from the function's execution
role (p. 222).

LANG

No

en_US.UTF-8. This is the locale of the runtime.

TZ

Yes

The environment's timezone (UTC). The execution
environment uses NTP to synchronize the system clock.

LAMBDA_TASK_ROOT

Yes

The path to your Lambda function code.

LAMBDA_RUNTIME_DIR

Yes

The path to runtime libraries.

PATH

No

/usr/local/bin:/usr/bin/:/bin:/opt/bin

LD_LIBRARY_PATH

No

/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:
$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:
$LAMBDA_TASK_ROOT/lib:/opt/lib

NODE_PATH

No

(Node.js) /opt/nodejs/node8/node_modules/:/
opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/
node_modules

PYTHONPATH

No

(Python) $LAMBDA_RUNTIME_DIR.

AWS_LAMBDA_RUNTIME_API

Yes

(custom runtime) The host and port of the runtime
API (p. 97).

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

AWS Lambda Execution Context
When AWS Lambda executes your Lambda function, it provisions and manages the resources needed to
run your Lambda function. When you create a Lambda function, you specify conﬁguration information,
such as the amount of memory and maximum execution time that you want to allow for your Lambda

93

AWS Lambda Developer Guide
Runtime Support Policy

function. When a Lambda function is invoked, AWS Lambda launches an execution context based on
the conﬁguration settings you provide. The execution context is a temporary runtime environment that
initializes any external dependencies of your Lambda function code, such as database connections or
HTTP endpoints. This aﬀords subsequent invocations better performance because there is no need to
"cold-start" or initialize those external dependencies, as explained below.
It takes time to set up an execution context and do the necessary "bootstrapping", which adds some
latency each time the Lambda function is invoked. You typically see this latency when a Lambda
function is invoked for the ﬁrst time or after it has been updated because AWS Lambda tries to reuse the
execution context for subsequent invocations of the Lambda function.
After a Lambda function is executed, AWS Lambda maintains the execution context for some time in
anticipation of another Lambda function invocation. In eﬀect, the service freezes the execution context
after a Lambda function completes, and thaws the context for reuse, if AWS Lambda chooses to reuse
the context when the Lambda function is invoked again. This execution context reuse approach has the
following implications:
• Any declarations in your Lambda function code (outside the handler code, see Programming
Model (p. 18)) remains initialized, providing additional optimization when the function is invoked
again. For example, if your Lambda function establishes a database connection, instead of
reestablishing the connection, the original connection is used in subsequent invocations. We suggest
adding logic in your code to check if a connection exists before creating one.
• Each execution context provides 500MB of additional disk space in the /tmp directory. The directory
content remains when the execution context is frozen, providing transient cache that can be used for
multiple invocations. You can add extra code to check if the cache has the data that you stored. For
information on deployment limits, see AWS Lambda Limits (p. 249).
• Background processes or callbacks initiated by your Lambda function that did not complete when the
function ended resume if AWS Lambda chooses to reuse the execution context. You should make sure
any background processes or callbacks (in case of Node.js) in your code are complete before the code
exits.
When you write your Lambda function code, do not assume that AWS Lambda automatically reuses
the execution context for subsequent function invocations. Other factors may dictate a need for AWS
Lambda to create a new execution context, which can lead to unexpected results, such as database
connection failures.

Runtime Support Policy
AWS Lambda will only deprecate runtime versions that are marked as EOL (End of Life) at the end of
their maintenance window. Versions that are marked deprecated will stop supporting creation of new
functions and updates of existing functions authored in the deprecated runtime (unless re-conﬁgured to
use a supported runtime version). AWS Lambda will also not provide security updates, technical support
or hotﬁxes for deprecated runtimes and reserves the right to disable invocations of functions conﬁgured
to run on a deprecated runtime at any time.

Deprecated Node.js Runtimes
Name

Identiﬁer

End of Life

Node.js 0.10

nodejs

2016-10-31

Node.js 4.3

nodejs4.3

2018-04-30

nodejs4.3-edge

94

AWS Lambda Developer Guide
Custom Runtimes

Custom AWS Lambda Runtimes
You can implement an AWS Lambda runtime in any programming language. A runtime is a program that
runs a Lambda function's handler method when the function is invoked. You can include a runtime in
your function's deployment package in the form of an executable ﬁle named bootstrap.
A runtime is responsible for running the function's setup code, reading the handler name from an
environment variable, and reading invocation events from the Lambda runtime API. The runtime passes
the event data to the function handler, and posts the response from the handler back to Lambda.
Your custom runtime runs in the standard Lambda execution environment (p. 92). It can be a shell
script, a script in a language that's included in Amazon Linux, or a binary executable ﬁle that's compiled
in Amazon Linux.
To get started with custom runtimes, see Tutorial – Publishing a Custom Runtime (p. 99). You can also
explore a custom runtime implemented in C++ at awslabs/aws-lambda-cpp on GitHub.
Topics
• Using a Custom Runtime (p. 95)
• Building a Custom Runtime (p. 95)

Using a Custom Runtime
To use a custom runtime, set your function's runtime to provided. The runtime can be included in your
function's deployment package, or in a layer (p. 47).

Example function.zip
.
### bootstrap
### function.sh

If there's a ﬁle named bootstrap in your deployment package, Lambda executes that ﬁle. If not,
Lambda looks for a runtime in the function's layers. If the bootstrap ﬁle isn't found or isn't executable,
your function returns an error upon invocation.

Building a Custom Runtime
A custom runtime's entry point is an executable ﬁle named bootstrap. The bootstrap ﬁle can be the
runtime, or it can invoke another ﬁle that creates the runtime. The following example uses a bundled
version of Node.js to execute a JavaScript runtime in a separate ﬁle named runtime.js.

Example bootstrap
#!/bin/sh
cd $LAMBDA_TASK_ROOT
./node-v11.1.0-linux-x64/bin/node runtime.js

Your runtime code is responsible for completing some initialization tasks. Then it processes
invocation events in a loop until it's terminated. The initialization tasks run once per instance of the
function (p. 93) to prepare the environment to handle invocations.

Initialization Tasks
• Retrieve settings – Read environment variables to get details about the function and environment.

95

AWS Lambda Developer Guide
Building a Custom Runtime

• _HANDLER – The location to the handler, from the function's conﬁguration. The standard format is
file.method, where file is the name of the ﬁle without an extension, and method is the name of
a method or function that's deﬁned in the ﬁle.
• LAMBDA_TASK_ROOT – The directory that contains the function code.
• AWS_LAMBDA_RUNTIME_API – The host and port of the runtime API.
See Environment Variables Available to Lambda Functions (p. 92) for a full list of available variables.
• Initialize the function – Load the handler ﬁle and run any global or static code that it contains.
Functions should create static resources like SDK clients and database connections once, and reuse
them for multiple invocations.
• Handle errors – If an error occurs, call the initialization error (p. 99) API and exit immediately.
Initialization counts towards billed execution time and timeout. When an execution triggers the
initialization of a new instance of your function, you can see the initialization time in the logs and AWS
X-Ray trace (p. 214).

Example Log
REPORT RequestId: f8ac1208... Init Duration: 48.26 ms
Duration: 237.17 ms
Duration: 300 ms
Memory Size: 128 MB
Max Memory Used: 26 MB

Billed

While it runs, a runtime uses the Lambda runtime interface (p. 97) to manage incoming events and
report errors. After completing initialization tasks, the runtime processes incoming events in a loop.

Processing Tasks
• Get an event – Call the next invocation (p. 97) API to get the next event. The response body
contains the event data. Response headers contain the request ID and other information.
• Propagate the tracing header – Get the X-Ray tracing header from the Lambda-Runtime-Trace-Id
header in the API response. Set the _X_AMZN_TRACE_ID environment variable with the same value for
the X-Ray SDK to use.
• Create a context object – Create an object with context information from environment variables and
headers in the API response.
• Invoke the function handler – Pass the event and context object to the handler.
• Handle the response – Call the invocation response (p. 98) API to post the response from the
handler.

96

AWS Lambda Developer Guide
Runtime Interface

• Handle errors – If an error occurs, call the invocation error (p. 98) API.
• Cleanup – Release unused resources, send data to other services, or perform additional tasks before
getting the next event.
You can include the runtime in your function's deployment package, or distribute the runtime separately
in a function layer. For an example walkthrough, see ??? (p. 99).

AWS Lambda Runtime Interface
AWS Lambda provides an HTTP API for custom runtimes (p. 95) to receive invocation events from
Lambda and send response data back within the Lambda execution environment (p. 92).
The OpenAPI speciﬁcation for the runtime API version 2018-06-01 is available here: runtime-api.zip
Runtimes get an endpoint from the AWS_LAMBDA_RUNTIME_API environment variable, add the API
version, and use the following resource paths to interact with the API.

Example Request
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

Resources
• Next Invocation (p. 97)
• Invocation Response (p. 98)
• Invocation Error (p. 98)
• Initialization Error (p. 99)

Next Invocation
Path – /runtime/invocation/next
Method – GET
Retrieves an invocation event. The response body contains the payload from the invocation, which is
a JSON document that contains event data from the function trigger. The response headers contain
additional data about the invocation.

Response Headers
• Lambda-Runtime-Aws-Request-Id – The request ID, which identiﬁes the request that triggered the
function invocation.
For example, 8476a536-e9f4-11e8-9739-2dfe598c3fcd.
• Lambda-Runtime-Deadline-Ms – The date that the function times out in Unix time milliseconds.
For example, 1542409706888.
• Lambda-Runtime-Invoked-Function-Arn – The ARN of the Lambda function, version, or alias
that's speciﬁed in the invocation.
For example, arn:aws:lambda:us-east-2:123456789012:function:custom-runtime.
• Lambda-Runtime-Trace-Id – The AWS X-Ray tracing header.
97

AWS Lambda Developer Guide
Invocation Response

For example, Root=1-5bef4de7ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1.
• Lambda-Runtime-Client-Context – For invocations from the AWS Mobile SDK, data about the
client application and device.
• Lambda-Runtime-Cognito-Identity – For invocations from the AWS Mobile SDK, data about the
Amazon Cognito identity provider.
The request ID tracks the invocation within Lambda. Use it to specify the invocation when you send the
response.
The tracing header contains the trace ID, parent ID, and sampling decision. If the request is
sampled, the request was sampled by Lambda or an upstream service. The runtime should set the
_X_AMZN_TRACE_ID with the value of the header. The X-Ray SDK reads this to get the IDs and
determine whether to trace the request.

Invocation Response
Path – /runtime/invocation/AwsRequestId/response
Method – POST
Sends an invocation response to Lambda. After the runtime invokes the function handler, it posts the
response from the function to the invocation response path. For synchronous invocations, Lambda then
sends the response back to the client.

Example Success Request
REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/
response" -d "SUCCESS"

Invocation Error
Path – /runtime/invocation/AwsRequestId/error
Method – POST
If the function returns an error, the runtime formats the error into a JSON document, and posts it to the
invocation error path.

Example Request Body
{
}

"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException"

Example Error Request
REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" :
\"InvalidEventDataException\"}"
curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/
error" -d "$ERROR"

98

AWS Lambda Developer Guide
Initialization Error

Initialization Error
Path – /runtime/init/error
Method – POST
If the runtime encounters an error during initialization, it posts an error message to the initialization
error path.

Example Initialization Error Request
ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" :
\"InvalidFunctionException\"}"
curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error"

-d "$ERROR"

Tutorial – Publishing a Custom Runtime
In this tutorial, you create a Lambda function with a custom runtime. You start by including the runtime
in the function's deployment package. Then you migrate it to a layer that you manage independently
from the function. Finally, you share the runtime layer with the world by updating its resource-based
permissions policy.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.
You need an IAM role to create a Lambda function. The role needs permission to send logs to
CloudWatch Logs and access the AWS services that your function uses. If you don't have a role for
function development, create one now.

To create an execution role
1.

Open the roles page in the IAM console.

2.

Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – Lambda.
• Permissions – AWSLambdaBasicExecutionRole.

99

AWS Lambda Developer Guide
Create a Function

• Role name – lambda-role.
The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write
logs to CloudWatch Logs.

Create a Function
Create a Lambda function with a custom runtime. This example includes two ﬁles, a runtime bootstrap
ﬁle, and a function handler. Both are implemented in Bash.
The runtime loads a function script from the deployment package. It uses two variables to locate the
script. LAMBDA_TASK_ROOT tells it where the package was extracted, and _HANDLER includes the name
of the script.

Example bootstrap
#!/bin/sh
set -euo pipefail
# Initialization - load function handler
source $LAMBDA_TASK_ROOT/"$(echo $_HANDLER | cut -d. -f1).sh"
# Processing
while true
do
HEADERS="$(mktemp)"
# Get an event
EVENT_DATA=$(curl -sS -LD "$HEADERS" -X GET "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/
runtime/invocation/next")
REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS" | tr -d '[:space:]' | cut
-d: -f2)
# Execute the handler function from the script
RESPONSE=$($(echo "$_HANDLER" | cut -d. -f2) "$EVENT_DATA")
# Send the response
curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/
response" -d "$RESPONSE"
done

After loading the script, the runtime processes events in a loop. It uses the runtime API to retrieve an
invocation event from Lambda, passes the event to the handler, and posts the response back to Lambda.
To get the request ID, the runtime saves the headers from the API response to a temporary ﬁle, and
reads the Lambda-Runtime-Aws-Request-Id header from the ﬁle.

Note

Runtimes have additional responsibilities, including error handling, and providing context
information to the handler. For details, see Building a Custom Runtime (p. 95).
The script deﬁnes a handler function that takes event data, logs it to stderr, and returns it.

Example function.sh
function handler () {
EVENT_DATA=$1
echo "$EVENT_DATA" 1>&2;
RESPONSE="Echoing request: '$EVENT_DATA'"

100

AWS Lambda Developer Guide
Create a Layer

}

echo $RESPONSE

Save both ﬁles in a project directory named runtime-tutorial.
runtime-tutorial
# bootstrap
# function.sh

Make the ﬁles executable and add them to a ZIP archive.
runtime-tutorial$ chmod 755 function.sh bootstrap
runtime-tutorial$ zip function.zip function.sh bootstrap
adding: function.sh (deflated 24%)
adding: bootstrap (deflated 39%)

Create a function named bash-runtime.
runtime-tutorial$ aws lambda create-function --function-name bash-runtime \
--zip-file fileb://function.zip --handler function.handler --runtime provided \
--role arn:aws:iam::123456789012:role/lambda-role
{
"FunctionName": "bash-runtime",
"FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:bash-runtime",
"Runtime": "provided",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "function.handler",
"CodeSize": 831,
"Description": "",
"Timeout": 3,
"MemorySize": 128,
"LastModified": "2018-11-28T06:57:31.095+0000",
"CodeSha256": "mv/xRv84LPCxdpcbKvmwuuFzwo7sLwUO1VxcUv3wKlM=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "PassThrough"
},
"RevisionId": "2e1d51b0-6144-4763-8e5c-7d5672a01713"
}

Invoke the function and verify the response.
runtime-tutorial$ aws lambda invoke --function-name bash-runtime --payload
'{"text":"Hello"}' response.txt
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
runtime-tutorial$ cat response.txt
Echoing request: '{"text":"Hello"}'

Create a Layer
To separate the runtime code from the function code, create a layer that only contains the runtime.
Layers let you develop your function's dependencies independently, and can reduce storage usage when
you use the same layer with multiple functions.
Create a layer archive that contains the bootstrap ﬁle.

101

AWS Lambda Developer Guide
Update the Function

runtime-tutorial$ zip runtime.zip bootstrap
adding: bootstrap (deflated 39%)

Create a layer with the publish-layer-version command.
runtime-tutorial$ aws lambda publish-layer-version --layer-name bash-runtime --zip-file
fileb://runtime.zip
{
"Content": {
"Location": "https://awslambda-us-west-2-layers.s3.us-west-2.amazonaws.com/
snapshots/123456789012/bash-runtime-018c209b...",
"CodeSha256": "bXVLhHi+D3H1QbDARUVPrDwlC7bssPxySQqt1QZqusE=",
"CodeSize": 584,
"UncompressedCodeSize": 0
},
"LayerArn": "arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime",
"LayerVersionArn": "arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:1",
"Description": "",
"CreatedDate": "2018-11-28T07:49:14.476+0000",
"Version": 1
}

This creates the ﬁrst version of the layer.

Update the Function
To use the runtime layer with the function, conﬁgure the function to use the layer, and remove the
runtime code from the function.
Update the function conﬁguration to pull in the layer.
runtime-tutorial$ aws lambda update-function-configuration --function-name bash-runtime \
--layers arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:1
{
"FunctionName": "bash-runtime",
"Layers": [
{
"Arn": "arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:1",
"CodeSize": 584,
"UncompressedCodeSize": 679
}
]
...
}

This adds the runtime to the function in the /opt directory. Lambda uses this runtime, but only if you
remove it from the function's deployment package. Update the function code to only include the handler
script.
runtime-tutorial$ zip function-only.zip function.sh
adding: function.sh (deflated 24%)
runtime-tutorial$ aws lambda update-function-code --function-name bash-runtime --zip-file
fileb://function-only.zip
{
"FunctionName": "bash-runtime",
"CodeSize": 270,
"Layers": [
{
"Arn": "arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:7",

102

AWS Lambda Developer Guide
Update the Runtime

}

}

]
...

"CodeSize": 584,
"UncompressedCodeSize": 679

Invoke the function to verify that it works with the runtime layer.
runtime-tutorial$ aws lambda invoke --function-name bash-runtime --payload
'{"text":"Hello"}' response.txt
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
runtime-tutorial$ cat response.txt
Echoing request: '{"text":"Hello"}'

Update the Runtime
To log information about the execution environment, update the runtime script to output environment
variables.

Example bootstrap
#!/bin/sh
set -euo pipefail
echo "##
env

Environment variables:"

# Initialization - load function handler
source $LAMBDA_TASK_ROOT/"$(echo $_HANDLER | cut -d. -f1).sh"
...

Create a second version of the layer with the new code.
runtime-tutorial$ zip runtime.zip bootstrap
updating: bootstrap (deflated 39%)
runtime-tutorial$ aws lambda publish-layer-version --layer-name bash-runtime --zip-file
fileb://runtime.zip

Conﬁgure the function to use the new version of the layer.
runtime-tutorial$ aws lambda update-function-configuration --function-name bash-runtime \
--layers arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:2

Share the Layer
Add a permission statement to your runtime layer to share it with other accounts.
runtime-tutorial$ aws lambda add-layer-version-permission --layer-name bash-runtime -version-number 2 \
--principal "*" --statement-id publish --action lambda:GetLayerVersion
{

103

AWS Lambda Developer Guide
Clean Up
"Statement": "{\"Sid\":\"publish\",\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":
\"lambda:GetLayerVersion\",\"Resource\":\"arn:aws:lambda:us-west-2:123456789012:layer:bashruntime:2\"}",
"RevisionId": "9d5fe08e-2a1e-4981-b783-37ab551247ff"
}

You can add multiple statements that each grant permission to a single account, accounts in an
organization, or all accounts.

Clean Up
Delete each version of the layer.
runtime-tutorial$ aws lambda delete-layer-version --layer-name bash-runtime --versionnumber 1
runtime-tutorial$ aws lambda delete-layer-version --layer-name bash-runtime --versionnumber 2

Because the function holds a reference to version 2 of the layer, it still exists in Lambda. The function
continues to work, but functions can no longer be conﬁgured to use the deleted version. If you then
modify the list of layers on the function, you must specify a new version or omit the deleted layer.
Delete the tutorial function with the delete-function command.
runtime-tutorial$ aws lambda delete-function --function-name bash-runtime

104

AWS Lambda Developer Guide
Manage Applications

AWS Lambda Applications
An AWS Lambda application is a combination of Lambda functions, event sources, and other resources
that work together to perform tasks. You can use AWS CloudFormation and other tools to collect your
application's components into a single package that can be deployed and managed as one resource.
Applications make your Lambda projects portable and enable you to integrate with additional developer
tools, such as AWS CodePipeline, AWS CodeBuild, and the AWS Serverless Application Model command
line interface (SAM CLI).
The AWS Serverless Application Repository provides a collection of Lambda applications that you
can deploy in your account with a few clicks. The repository includes both ready-to-use applications
and samples that you can use as a starting point for your own projects. You can also submit your own
projects for inclusion.
AWS CloudFormation enables you to create a template that deﬁnes your application's resources and lets
you manage the application as a stack. You can more safely add or modify resources in your application
stack. If any part of an update fails, AWS CloudFormation automatically rolls back to the previous
conﬁguration. With AWS CloudFormation parameters, you can create multiple environments for your
application from the same template.
The AWS Serverless Application Model (p. 108) (AWS SAM) is an extension for the AWS CloudFormation
template language that lets you deﬁne serverless applications at a higher level. It abstracts away
common tasks such as function role creation, which makes it easier to write templates. AWS SAM is
supported directly by AWS CloudFormation, and includes additional functionality through the AWS CLI
and AWS SAM CLI.
The AWS CLI and AWS SAM CLI are command line tools for managing Lambda application stacks. In
addition to commands for managing application stacks with the AWS CloudFormation API, the AWS CLI
supports higher-level commands that simplify tasks like uploading deployment packages and updating
templates. The AWS SAM CLI provides additional functionality, including validating templates and
testing locally.
Topics
• Managing Applications in the AWS Lambda Console (p. 105)
• Using the AWS Serverless Application Model (AWS SAM) (p. 108)
• Building a Pipeline for Your Serverless Application (p. 108)

Managing Applications in the AWS Lambda
Console
The AWS Lambda console helps you monitor and manage your Lambda applications (p. 105). The
Applications menu lists AWS CloudFormation stacks with Lambda functions. The menu includes stacks
that you launch in AWS CloudFormation by using the AWS CloudFormation console, the AWS Serverless
Application Repository, the AWS CLI, or the AWS SAM CLI.

To view a Lambda application
1.

Open the Lambda console.

2.

Choose Applications.

105

AWS Lambda Developer Guide
Monitoring Applications

3.

Choose an application.

The overview shows the following information about your application.
• AWS CloudFormation template or SAM template – The template that deﬁnes your application.
• Resources – The AWS resources that are deﬁned in your application's template. To manage your
application's Lambda functions, choose a function name from the list.

Monitoring Applications
The Monitoring tab shows an Amazon CloudWatch dashboard with aggregate metrics for the resources
in your application.

To monitor a Lambda application
1.

Open the Lambda console.

2.

Choose Applications.

3.

Choose Monitoring.

By default, the Lambda console shows a basic dashboard. You can customize this page by deﬁning
custom dashboards in your application template. When your template includes one or more dashboards,
the page shows your dashboards instead of the default dashboard. You can switch between dashboards
with the drop-down menu on the top right of the page.

Custom Monitoring Dashboards
Customize your application monitoring page by adding one or more Amazon CloudWatch dashboards to
your application template with the AWS::CloudWatch::Dashboard resource type. The following example
creates a dashboard with a single widget that graphs the number of invocations of a function named
my-function.

Example Function Dashboard Template
Resources:
MyDashboard:
Type: AWS::CloudWatch::Dashboard
Properties:
DashboardName: my-dashboard
DashboardBody: |
{
"widgets": [
{
"type": "metric",

106

AWS Lambda Developer Guide
Custom Monitoring Dashboards

}

]

}

"width": 12,
"height": 6,
"properties": {
"metrics": [
[
"AWS/Lambda",
"Invocations",
"FunctionName",
"my-function",
{
"stat": "Sum",
"label": "MyFunction"
}
],
[
{
"expression": "SUM(METRICS())",
"label": "Total Invocations"
}
]
],
"region": "us-east-1",
"title": "Invocations",
"view": "timeSeries",
"stacked": false
}

You can get the deﬁnition for any of the widgets in the default monitoring dashboard from the
CloudWatch console.

To view a widget deﬁnition
1.

Open the Lambda console.

2.
3.

Choose Applications.
Choose an application that has the standard dashboard.

4.
5.

Choose Monitoring.
On any widget, choose View in metrics from the drop-down menu.

6.

Choose Source.

For more information about authoring CloudWatch dashboards and widgets, see Dashboard Body
Structure and Syntax in the Amazon CloudWatch API Reference.

107

AWS Lambda Developer Guide
AWS SAM

Using the AWS Serverless Application Model (AWS
SAM)
The AWS Serverless Application Model (AWS SAM) is an open-source framework you can use to build
serverless applications on AWS. It consists of the AWS SAM template speciﬁcation that you use to deﬁne
your serverless applications, and the AWS SAM command line interface (AWS SAM CLI) that you use to
build, test and deploy your serverless applications.
For more information about AWS SAM, see What Is AWS SAM?.
For more information about AWS SAM templates, see AWS SAM Template Basics.
For more information about locally testing Lambda functions, see Testing and Debugging Serverless
Applications.
For more information about automating deployments of serverless applications, see Deploying
Serverless Applications.

Building a Pipeline for Your Serverless Application
In the following tutorial, you create an AWS CodePipeline that automates the deployment of your
serverless application. First, you need to set up a source stage to trigger your pipeline. For the purposes
of this tutorial:
• We're using GitHub. For instructions on how to create a GitHub repository, see Create a Repository in
GitHub.
• You need to create an AWS CloudFormation role and add the AWSLambdaExecute policy to that role,
as outlined in the following steps:
1.

Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.

2.

Follow the steps in Creating a Role to Delegate Permissions to an AWS Service in the IAM User
Guide to create an IAM role (execution role). Then go to the To create a role for an AWS service
section. As you follow the steps to create a role, note the following:
• In Select Role Type, choose AWS Service Roles, and then choose CloudFormation. Choose
Next: Permissions.
• In Attach permissions policies, use the search bar to ﬁnd and then choose
AWSLambdaExecute. Choose Next: Review.
• In Role Name, use a name that's unique within your AWS account (for example,
cloudformation-lambda-execution-role), and then choose Create role.
• Open the role you just created. Under the Permissions tab, choose Add inline policy.
• In Create Policy, choose the JSON tab and enter the following:

Note

Make sure to replace the region and id placeholders with your Region and account ID.
{

"Statement": [
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion",
"s3:GetBucketVersioning"

108

AWS Lambda Developer Guide
Building a Pipeline for Your Serverless Application
],
"Resource": "*",
"Effect": "Allow"
},
{
"Action": [
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::codepipeline*"
],
"Effect": "Allow"
},
{
"Action": [
"lambda:*"
],
"Resource": [
"arn:aws:lambda:region:id:function:*"
],
"Effect": "Allow"
},
{
"Action": [
"apigateway:*"
],
"Resource": [
"arn:aws:apigateway:region::*"
],
"Effect": "Allow"
},
{
"Action": [
"iam:GetRole",
"iam:CreateRole",
"iam:DeleteRole",
"iam:PutRolePolicy"
],
"Resource": [
"arn:aws:iam::id:role/*"
],
"Effect": "Allow"
},
{
"Action": [
"iam:AttachRolePolicy",
"iam:DeleteRolePolicy",
"iam:DetachRolePolicy"
],
"Resource": [
"arn:aws:iam::id:role/*"
],
"Effect": "Allow"
},
{
"Action": [
"iam:PassRole"
],
"Resource": [
"*"
],
"Effect": "Allow"
},
{
"Action": [
"cloudformation:CreateChangeSet"

109

AWS Lambda Developer Guide
Step 1: Set Up Your Repository

}

],
"Resource": [
"arn:aws:cloudformation:region:aws:transform/Serverless-2016-10-31"
],
"Effect": "Allow"
},
{
"Action": [
"codedeploy:CreateApplication",
"codedeploy:DeleteApplication",
"codedeploy:RegisterApplicationRevision"
],
"Resource": [
"arn:aws:codedeploy:region:id:application:*"
],
"Effect": "Allow"
},
{
"Action": [
"codedeploy:CreateDeploymentGroup",
"codedeploy:CreateDeployment",
"codedeploy:GetDeployment"
],
"Resource": [
"arn:aws:codedeploy:region:id:deploymentgroup:*"
],
"Effect": "Allow"
},
{
"Action": [
"codedeploy:GetDeploymentConfig"
],
"Resource": [
"arn:aws:codedeploy:region:id:deploymentconfig:*"
],
"Effect": "Allow"
}
],
"Version": "2012-10-17"

• Choose Validate Policy and then choose Apply Policy.

Step 1: Set Up Your Repository
You can use any of the Lambda supported runtimes when you set up a repository. The following example
uses Node.js.
To set up your repository, do the following:
• Add an index.js ﬁle that contains the following code:

var time = require('time');
exports.handler = (event, context, callback) => {
var currentTime = new time.Date();
currentTime.setTimezone("America/Los_Angeles");
callback(null, {
statusCode: '200',
body: 'The time in Los Angeles is: ' + currentTime.toString(),
});
};

110

AWS Lambda Developer Guide
Step 2: Create Your Pipeline

• Add a samTemplate.yaml ﬁle that contains the following content. This is for the AWS SAM template
that deﬁnes the resources in your application. This AWS SAM template deﬁnes a Lambda function
that's triggered by API Gateway. Note that the runtime parameter uses nodejs6.10, but you can
also specify nodejs8.10. For more information about AWS SAM, see AWS Serverless Application
Model.
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Outputs the time
Resources:
TimeFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: nodejs6.10
CodeUri: ./
Events:
MyTimeApi:
Type: Api
Properties:
Path: /TimeResource
Method: GET

• Add a buildspec.yml ﬁle. A build spec is a collection of build commands and related settings, in
YAML format, that AWS CodeBuild uses to run a build. For more information, see Build Speciﬁcation
Reference for AWS CodeBuild. In this example, the build action is the following:
• Use npm to install the time package.
• Run the Package command to prepare your deployment package for subsequent deployment steps
in your pipeline. For more information on the package command, see Uploading Local Artifacts to an
S3 Bucket.
version: 0.2
phases:
install:
commands:
- npm install time
- aws cloudformation package --template-file samTemplate.yaml --kms-key-id kmskey-id --s3-bucket bucket-name
--output-template-file outputSamTemplate.yaml
artifacts:
type: zip
files:
- samTemplate.yaml
- outputSamTemplate.yaml

Step 2: Create Your Pipeline
Follow these steps to create your AWS CodePipeline.
1.
2.
3.
4.
5.

Sign in to the AWS Management Console and open the AWS CodePipeline console.
Choose Get Started Now.
In Pipeline name, enter a name for your pipeline, and then choose Next step.
In Source provider, choose GitHub.
Choose Connect to GitHub, and then choose the Repository and Branch that you want to connect
to. Every git push to the branch you select triggers your pipeline. Choose Next step.

111

AWS Lambda Developer Guide
Step 3: Update the Generated Service Policy

6.

Choose AWS CodeBuild as your Build provider.

7.

Choose Create a new build project and enter a project name.

8.

Choose Ubuntu as the operating system.

9.

Choose Node.js as the runtime.

10. In Version, choose aws/codebuild/nodejs:version.
11. In Build speciﬁcation, choose Use the buildspec.yml in the source code root
directory.
12. Choose Save build project.

Note

A service role for AWS CodeBuild is automatically created on your behalf.
Choose Next step.
13. In Deployment provider, choose AWS CloudFormation.
When you choose this option, AWS CloudFormation commands are used to deploy the AWS SAM
template. For more information, see AWS SAM Template Basics in the AWS Serverless Application
Model Developer Guide.
14. In Action mode, choose Create or replace a change set.
15. In Stack name, enter MyBetaStack.
16. In Change set name, enter MyChangeSet.
17. In Template ﬁle, enter outputSamTemplate.yaml.
18. In Capabilities, choose CAPABILITY_IAM.
19. In Role, select the AWS CloudFormation role that you created at the beginning of this tutorial and
then choose Next step.
20. Choose Create role, choose Next, choose Allow, and then choose Next step.
21. Review your pipeline and then choose Create pipeline.

Step 3: Update the Generated Service Policy
Complete the following steps to allow AWS CodeBuild to upload build artifacts to your Amazon S3
bucket.
1.

Go to the IAM console.

2.

Choose Roles.

3.

Open the service role that was generated for your project—typically code-build-project-nameservice-role.

4.

Under the Permissions tab, choose Add inline policy.

5.

In service, choose Choose a service.

6.

In Select a service below, choose S3.

7.

In Actions, choose Select actions.

8.

Expand Write under Access level groups, and then choose PutObject.

9.

Choose Resources, and then select the Any check box.

10. Choose Review policy.
11. Enter a Name, and then choose Create policy. Then return to the pipeline you created in the
previous section.
112

AWS Lambda Developer Guide
Step 4: Complete Your Beta Deployment Stage

Step 4: Complete Your Beta Deployment Stage
Use the following steps to complete your beta stage.
1.
2.

Choose Edit.
Choose the + icon next to MyBetaStack.

3.

In Action category, if it's not already selected, choose Deploy.

4.
5.

6.

In Deployment provider, if it's not already selected, choose AWS CloudFormation.
In Action mode, choose Execute a change set. CreateChangeSet transforms the AWS SAM
template to the full AWS CloudFormation format, and deployChangeSet deploys the AWS
CloudFormation template.
In Stack name, enter or choose MyBetaStack.

7.

In Change set name, enter MyChangeSet.

8.

Choose Add action.

9.

Choose Save pipeline changes.

10. Choose Save and continue.
Your pipeline is ready. Any git push to the branch that you connected to this pipeline is going to
trigger a deployment. To test your pipeline and deploy your application for the ﬁrst time, do one of the
following:
• Perform a git push to the branch that's connected to your pipeline.
• Go the AWS CodePipeline console, choose the name of the pipeline you created, and then choose
Release change.

113

AWS Lambda Developer Guide
Amazon S3

Using AWS Lambda With Other
Services
The use cases for AWS Lambda can be grouped into the following categories:
• Using AWS Lambda with AWS services as event sources – Event sources publish events that cause the
Lambda function to be invoked. These can be AWS services such as Amazon S3. For more information
and tutorials, see the following topics:
Using AWS Lambda with Amazon S3 (p. 114)
Using AWS Lambda with Amazon Kinesis (p. 129)
Using AWS Lambda with Amazon SQS (p. 141)
Using AWS Lambda with Amazon DynamoDB (p. 150)
Using AWS Lambda with AWS CloudTrail (p. 161)
Using AWS Lambda with Amazon SNS from Diﬀerent Accounts (p. 168)
• On-demand Lambda function invocation over HTTPS (Amazon API Gateway) – In addition to
invoking Lambda functions using event sources, you can also invoke your Lambda function over
HTTPS. You can do this by deﬁning a custom REST API and endpoint using API Gateway. For more
information and a tutorial, see Using AWS Lambda with Amazon API Gateway (p. 173).
• On-demand Lambda function invocation (build your own event sources using custom apps) –
User applications such as client, mobile, or web applications can publish events and invoke Lambda
functions using the AWS SDKs or AWS Mobile SDKs, such as the AWS Mobile SDK for Android. For more
information and a tutorial, see Getting Started with AWS Lambda (p. 3) and Using AWS Lambda as an
Android Mobile Application Backend (p. 187)
• Scheduled events – You can also set up AWS Lambda to invoke your code on a regular, scheduled
basis using the AWS Lambda console. You can specify a ﬁxed rate (number of hours, days, or weeks)
or you can specify a cron expression. For more information and a tutorial, see Using AWS Lambda with
Amazon CloudWatch Events (p. 195).
In addition, you also can use a Lambda State Machine. For more information, see Using a State Machine.

Using AWS Lambda with Amazon S3
Amazon S3 can publish events (for example, when an object is created in a bucket) to AWS Lambda and
invoke your Lambda function by passing the event data as a parameter. This integration enables you
to write Lambda functions that process Amazon S3 events. In Amazon S3, you add bucket notiﬁcation
conﬁguration that identiﬁes the type of event that you want Amazon S3 to publish and the Lambda
function that you want to invoke.

Important

If your Lambda function uses the same bucket that triggers it, it could cause the function to
execute in a loop. For example, if the bucket triggers a function each time an object is uploaded,
114

AWS Lambda Developer Guide
Amazon S3

and the function uploads an object to the bucket, then the function indirectly triggers itself. To
avoid this, use two buckets, or conﬁgure the trigger to only apply to a preﬁx used for incoming
objects.
Note the following about how the Amazon S3 and AWS Lambda integration works:
• Non-stream based (async) model – This is a model (see AWS Lambda Event Source Mapping (p. 64)),
where Amazon S3 monitors a bucket and invokes the Lambda function by passing the event data as a
parameter. In a push model, you maintain event source mapping within Amazon S3 using the bucket
notiﬁcation conﬁguration. In the conﬁguration, you specify the event types that you want Amazon S3
to monitor and which AWS Lambda function you want Amazon S3 to invoke. For more information,
see Conﬁguring Amazon S3 Event Notiﬁcations in the Amazon Simple Storage Service Developer Guide.
• Asynchronous invocation – AWS Lambda invokes a Lambda function using the Event invocation type
(asynchronous invocation). For more information about invocation types, see Invocation Types (p. 63).
• Event structure – The event your Lambda function receives is for a single object and it provides
information, such as the bucket name and object key name.
Note that there are two types of permissions policies that you work with when you set up the end-to-end
experience:
• Permissions for your Lambda function – Regardless of what invokes a Lambda function, AWS Lambda
executes the function by assuming the IAM role (execution role) that you specify at the time you
create the Lambda function. Using the permissions policy associated with this role, you grant your
Lambda function the permissions that it needs. For example, if your Lambda function needs to read an
object, you grant permissions for the relevant Amazon S3 actions in the permissions policy. For more
information, see AWS Lambda Execution Role (p. 222).
• Permissions for Amazon S3 to invoke your Lambda function – Amazon S3 cannot invoke your
Lambda function without your permission. You grant this permission via the permissions policy
associated with the Lambda function.
The following diagram summarizes the ﬂow:

1. User uploads an object to an S3 bucket (object-created event).
2. Amazon S3 detects the object-created event.
3. Amazon S3 invokes a Lambda function that is speciﬁed in the bucket notiﬁcation conﬁguration.
4. AWS Lambda executes the Lambda function by assuming the execution role that you speciﬁed at the
time you created the Lambda function.

115

AWS Lambda Developer Guide
Tutorial

5. The Lambda function executes.
Topics
• Tutorial: Using AWS Lambda with Amazon S3 (p. 116)
• Sample Amazon Simple Storage Service Function Code (p. 122)
• AWS SAM Template for an Amazon S3 Application (p. 129)

Tutorial: Using AWS Lambda with Amazon S3
Suppose you want to create a thumbnail for each image ﬁle that is uploaded to a bucket. You can create
a Lambda function (CreateThumbnail) that Amazon S3 can invoke when objects are created. Then, the
Lambda function can read the image object from the source bucket and create a thumbnail image target
bucket.
Upon completing this tutorial, you will have the following Amazon S3, Lambda, and IAM resources in
your account:

Lambda Resources
• A Lambda function.
• An access policy associated with your Lambda function that grants Amazon S3 permission to invoke
the Lambda function.

IAM Resources
• An execution role that grants permissions that your Lambda function needs through the permissions
policy associated with this role.

Amazon S3 Resources
• A source bucket with a notiﬁcation conﬁguration that invokes the Lambda function.
• A target bucket where the function saves resized images.

116

AWS Lambda Developer Guide
Tutorial

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.

Open the roles page in the IAM console.

2.

Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – AWS Lambda.
• Permissions – AWSLambdaExecute.
• Role name – lambda-s3-role.

The AWSLambdaExecute policy has the permissions that the function needs to manage objects in
Amazon S3 and write logs to CloudWatch Logs.

Create Buckets and Upload a Sample Object
Follow the steps to create buckets and upload an object.
1. Open the Amazon S3 console.
2. Create two buckets. The target bucket name must be source followed by resized, where
source is the name of the bucket you want to use for the source. For example, mybucket and
mybucketresized.
3. In the source bucket, upload a .jpg object, HappyFace.jpg.
When you invoke the Lambda function manually before you connect to Amazon S3, you pass sample
event data to the function that speciﬁes the source bucket and HappyFace.jpg as the newly created
object so you need to create this sample object ﬁrst.

Create the Function
The following example code receives an Amazon S3 event input and processes the message that it
contains. It resizes an image in the source bucket and saves the output to the target bucket.

117

AWS Lambda Developer Guide
Tutorial

Note

For sample code in other languages, see Sample Amazon Simple Storage Service Function
Code (p. 122).

Example index.js
// dependencies
var async = require('async');
var AWS = require('aws-sdk');
var gm = require('gm')
.subClass({ imageMagick: true }); // Enable ImageMagick integration.
var util = require('util');
// constants
var MAX_WIDTH = 100;
var MAX_HEIGHT = 100;
// get reference to S3 client
var s3 = new AWS.S3();
exports.handler = function(event, context, callback) {
// Read options from the event.
console.log("Reading options from event:\n", util.inspect(event, {depth: 5}));
var srcBucket = event.Records[0].s3.bucket.name;
// Object key may have spaces or unicode non-ASCII characters.
var srcKey
=
decodeURIComponent(event.Records[0].s3.object.key.replace(/\+/g, " "));
var dstBucket = srcBucket + "resized";
var dstKey
= "resized-" + srcKey;
// Sanity check: validate that source and destination are different buckets.
if (srcBucket == dstBucket) {
callback("Source and destination buckets are the same.");
return;
}
// Infer the image type.
var typeMatch = srcKey.match(/\.([^.]*)$/);
if (!typeMatch) {
callback("Could not determine the image type.");
return;
}
var imageType = typeMatch[1];
if (imageType != "jpg" && imageType != "png") {
callback('Unsupported image type: ${imageType}');
return;
}
// Download the image from S3, transform, and upload to a different S3 bucket.
async.waterfall([
function download(next) {
// Download the image from S3 into a buffer.
s3.getObject({
Bucket: srcBucket,
Key: srcKey
},
next);
},
function transform(response, next) {
gm(response.Body).size(function(err, size) {
// Infer the scaling factor to avoid stretching the image unnaturally.
var scalingFactor = Math.min(
MAX_WIDTH / size.width,
MAX_HEIGHT / size.height
);

118

AWS Lambda Developer Guide
Tutorial
var width = scalingFactor * size.width;
var height = scalingFactor * size.height;
// Transform the image buffer in memory.
this.resize(width, height)
.toBuffer(imageType, function(err, buffer) {
if (err) {
next(err);
} else {
next(null, response.ContentType, buffer);
}
});

});
},
function upload(contentType, data, next) {
// Stream the transformed image to a different S3 bucket.
s3.putObject({
Bucket: dstBucket,
Key: dstKey,
Body: data,
ContentType: contentType
},
next);
}
], function (err) {
if (err) {
console.error(
'Unable to resize ' + srcBucket + '/' + srcKey +
' and upload to ' + dstBucket + '/' + dstKey +
' due to an error: ' + err
);
} else {
console.log(
'Successfully resized ' + srcBucket + '/' + srcKey +
' and uploaded to ' + dstBucket + '/' + dstKey
);
}

};

);

}

callback(null, "message");

The deployment package is a .zip ﬁle containing your Lambda function code and dependencies.

To create a deployment package
1.

Create a folder (examplefolder), and then create a subfolder (node_modules).

2.

Install the Node.js platform. For more information, see the Node.js website.

3.

Install dependencies. The code examples use the following libraries:
• AWS SDK for JavaScript in Node.js
• gm, GraphicsMagick for node.js
• Async utility module
The AWS Lambda runtime already has the AWS SDK for JavaScript in Node.js, so you only need to
install the other libraries. Open a command prompt, navigate to the examplefolder, and install
the libraries using the npm command, which is part of Node.js.
npm install async gm

119

AWS Lambda Developer Guide
Tutorial

4.

Save the sample code to a ﬁle named index.js.

5.

Review the preceding code and note the following:
• The function knows the source bucket name and the key name of the object from the event data
it receives as parameters. If the object is a .jpg, the code creates a thumbnail and saves it to the
target bucket.
• The code assumes that the destination bucket exists and its name is a concatenation of the source
bucket name followed by the string resized. For example, if the source bucket identiﬁed in
the event data is examplebucket, the code assumes you have an examplebucketresized
destination bucket.
• For the thumbnail it creates, the code derives its key name as the concatenation of the string
resized- followed by the source object key name. For example, if the source object key is
sample.jpg, the code creates a thumbnail object that has the key resized-sample.jpg.

6.

Save the ﬁle as index.js in examplefolder. After you complete this step, you will have the
following folder structure:

index.js
/node_modules/gm
/node_modules/async

7.

Zip the index.js ﬁle and the node_modules folder as function.zip.

To create the function
•

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name CreateThumbnail \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 \
--timeout 10 --memory-size 1024 \
--role arn:aws:iam::123456789012:role/lambda-s3-role

The preceding command speciﬁes a 10-second timeout value as the function conﬁguration. Depending
on the size of objects you upload, you might need to increase the timeout value using the following AWS
CLI command.
$ aws lambda update-function-configuration --function-name CreateThumbnail --timeout 30

Test the Lambda Function
In this step, you invoke the Lambda function manually using sample Amazon S3 event data.

To test the Lambda function
1.

Save the following Amazon S3 sample event data in a ﬁle and save it as inputFile.txt. You need
to update the JSON by providing your sourcebucket name and a .jpg object key.
{

"Records":[
{
"eventVersion":"2.0",
"eventSource":"aws:s3",
"awsRegion":"us-west-2",
"eventTime":"1970-01-01T00:00:00.000Z",

120

AWS Lambda Developer Guide
Tutorial
"eventName":"ObjectCreated:Put",
"userIdentity":{
"principalId":"AIDAJDPLRKLG7UEXAMPLE"
},
"requestParameters":{
"sourceIPAddress":"127.0.0.1"
},
"responseElements":{
"x-amz-request-id":"C3D13FE58DE4C810",
"x-amz-id-2":"FMyUVURIY8/IgAtTv8xRjskZQpcIZ9KG4V5Wp6S7S/
JRWeUWerMUE5JgHvANOjpD"
},
"s3":{
"s3SchemaVersion":"1.0",
"configurationId":"testConfigRule",
"bucket":{
"name":"sourcebucket",
"ownerIdentity":{
"principalId":"A3NL1KOZZKExample"
},
"arn":"arn:aws:s3:::sourcebucket"
},
"object":{
"key":"HappyFace.jpg",
"size":1024,
"eTag":"d41d8cd98f00b204e9800998ecf8427e",
"versionId":"096fKKXTRTtl3on89fVO.nfljtsv6qko"
}
}
}
]
}

2.

Run the following Lambda CLI invoke command to invoke the function. Note that the command
requests asynchronous execution. You can optionally invoke it synchronously by specifying
RequestResponse as the invocation-type parameter value.
$ aws lambda invoke --function-name CreateThumbnail --invocation-type Event \
--payload file://inputfile.txt outputfile.txt

3.

Verify that the thumbnail was created in the target bucket.

Conﬁgure Amazon S3 to Publish Events
In this step, you add the remaining conﬁguration so that Amazon S3 can publish object-created events to
AWS Lambda and invoke your Lambda function. You do the following in this step:
• Add permissions to the Lambda function access policy to allow Amazon S3 to invoke the function.
• Add notiﬁcation conﬁguration to your source bucket. In the notiﬁcation conﬁguration, you provide the
following:
• Event type for which you want Amazon S3 to publish events. For this tutorial, you specify the
s3:ObjectCreated:* event type so that Amazon S3 publishes events when objects are created.
• Lambda function to invoke.

To add permissions to the function policy
1.

Run the following Lambda CLI add-permission command to grant Amazon S3 service principal
(s3.amazonaws.com) permissions to perform the lambda:InvokeFunction action. Note that
permission is granted to Amazon S3 to invoke the function only if the following conditions are met:
121

AWS Lambda Developer Guide
Sample Code

• An object-created event is detected on a speciﬁc bucket.
• The bucket is owned by a speciﬁc AWS account. If a bucket owner deletes a bucket, some other
AWS account can create a bucket with the same name. This condition ensures that only a speciﬁc
AWS account can invoke your Lambda function.

$ aws lambda add-permission --function-name CreateThumbnail --principal
s3.amazonaws.com \
--statement-id some-unique-id --action "lambda:InvokeFunction" \
--source-arn arn:aws:s3:::sourcebucket \
--source-account bucket-owner-account-id

2.

Verify the function's access policy by running the AWS CLI get-policy command.
$ aws lambda get-policy --function-name function-name

Add notiﬁcation conﬁguration on the source bucket to request Amazon S3 to publish object-created
events to Lambda.

To conﬁgure notiﬁcations
1.

Open the Amazon S3 console.

2.

Choose the source bucket.

3.

Choose Properties.

4.

Under Events, conﬁgure a notiﬁcation with the following settings.
• Name – lambda-trigger.
• Events – ObjectCreate (All).
• Send to – Lambda function.
• Lambda – CreateThumbnail.

For more information on event conﬁguration, see Enabling Event Notiﬁcations in the Amazon Simple
Storage Service Console User Guide.

Test the Setup
Now you can test the setup as follows:
1. Upload .jpg or .png objects to the source bucket using the Amazon S3 console.
2. Verify that the thumbnail was created in the target bucket using the CreateThumbnail function.
3. View logs in the CloudWatch console.

Sample Amazon Simple Storage Service Function
Code
Sample code is available for the following languages.
Topics
• Node.js 8 (p. 123)

122

AWS Lambda Developer Guide
Sample Code

• Java 8 (p. 125)
• Python 3 (p. 128)

Node.js 8
The following example code receives an Amazon S3 event input and processes the message that it
contains. It resizes an image in the source bucket and saves the output to the target bucket.

Example index.js
// dependencies
var async = require('async');
var AWS = require('aws-sdk');
var gm = require('gm')
.subClass({ imageMagick: true }); // Enable ImageMagick integration.
var util = require('util');
// constants
var MAX_WIDTH = 100;
var MAX_HEIGHT = 100;
// get reference to S3 client
var s3 = new AWS.S3();
exports.handler = function(event, context, callback) {
// Read options from the event.
console.log("Reading options from event:\n", util.inspect(event, {depth: 5}));
var srcBucket = event.Records[0].s3.bucket.name;
// Object key may have spaces or unicode non-ASCII characters.
var srcKey
=
decodeURIComponent(event.Records[0].s3.object.key.replace(/\+/g, " "));
var dstBucket = srcBucket + "resized";
var dstKey
= "resized-" + srcKey;
// Sanity check: validate that source and destination are different buckets.
if (srcBucket == dstBucket) {
callback("Source and destination buckets are the same.");
return;
}
// Infer the image type.
var typeMatch = srcKey.match(/\.([^.]*)$/);
if (!typeMatch) {
callback("Could not determine the image type.");
return;
}
var imageType = typeMatch[1];
if (imageType != "jpg" && imageType != "png") {
callback('Unsupported image type: ${imageType}');
return;
}
// Download the image from S3, transform, and upload to a different S3 bucket.
async.waterfall([
function download(next) {
// Download the image from S3 into a buffer.
s3.getObject({
Bucket: srcBucket,
Key: srcKey
},
next);
},

123

AWS Lambda Developer Guide
Sample Code
function transform(response, next) {
gm(response.Body).size(function(err, size) {
// Infer the scaling factor to avoid stretching the image unnaturally.
var scalingFactor = Math.min(
MAX_WIDTH / size.width,
MAX_HEIGHT / size.height
);
var width = scalingFactor * size.width;
var height = scalingFactor * size.height;
// Transform the image buffer in memory.
this.resize(width, height)
.toBuffer(imageType, function(err, buffer) {
if (err) {
next(err);
} else {
next(null, response.ContentType, buffer);
}
});

});
},
function upload(contentType, data, next) {
// Stream the transformed image to a different S3 bucket.
s3.putObject({
Bucket: dstBucket,
Key: dstKey,
Body: data,
ContentType: contentType
},
next);
}
], function (err) {
if (err) {
console.error(
'Unable to resize ' + srcBucket + '/' + srcKey +
' and upload to ' + dstBucket + '/' + dstKey +
' due to an error: ' + err
);
} else {
console.log(
'Successfully resized ' + srcBucket + '/' + srcKey +
' and uploaded to ' + dstBucket + '/' + dstKey
);
}

};

);

}

callback(null, "message");

The deployment package is a .zip ﬁle containing your Lambda function code and dependencies.

To create a deployment package
1.

Create a folder (examplefolder), and then create a subfolder (node_modules).

2.

Install the Node.js platform. For more information, see the Node.js website.

3.

Install dependencies. The code examples use the following libraries:
• AWS SDK for JavaScript in Node.js
• gm, GraphicsMagick for node.js
• Async utility module

124

AWS Lambda Developer Guide
Sample Code

The AWS Lambda runtime already has the AWS SDK for JavaScript in Node.js, so you only need to
install the other libraries. Open a command prompt, navigate to the examplefolder, and install
the libraries using the npm command, which is part of Node.js.
npm install async gm

4.

Save the sample code to a ﬁle named index.js.

5.

Review the preceding code and note the following:
• The function knows the source bucket name and the key name of the object from the event data
it receives as parameters. If the object is a .jpg, the code creates a thumbnail and saves it to the
target bucket.
• The code assumes that the destination bucket exists and its name is a concatenation of the source
bucket name followed by the string resized. For example, if the source bucket identiﬁed in
the event data is examplebucket, the code assumes you have an examplebucketresized
destination bucket.
• For the thumbnail it creates, the code derives its key name as the concatenation of the string
resized- followed by the source object key name. For example, if the source object key is
sample.jpg, the code creates a thumbnail object that has the key resized-sample.jpg.

6.

Save the ﬁle as index.js in examplefolder. After you complete this step, you will have the
following folder structure:

index.js
/node_modules/gm
/node_modules/async

7.

Zip the index.js ﬁle and the node_modules folder as CreateThumbnail.zip.

Java 8
The following is example Java code that reads incoming Amazon S3 events and creates a thumbnail.
Note that it implements the RequestHandler interface provided in the aws-lambda-java-core
library. Therefore, at the time you create a Lambda function you specify the class as the handler (that
is, example.S3EventProcessorCreateThumbnail). For more information about using interfaces to
provide a handler, see Leveraging Predeﬁned Interfaces for Creating Handler (Java) (p. 289).
The S3Event type that the handler uses as the input type is one of the predeﬁned classes in the awslambda-java-events library that provides methods for you to easily read information from the
incoming Amazon S3 event. The handler returns a string as output.

Example S3EventProcessorCreateThumbnail.java
package example;
import
import
import
import
import
import
import
import
import
import

java.awt.Color;
java.awt.Graphics2D;
java.awt.RenderingHints;
java.awt.image.BufferedImage;
java.io.ByteArrayInputStream;
java.io.ByteArrayOutputStream;
java.io.IOException;
java.io.InputStream;
java.net.URLDecoder;
java.util.regex.Matcher;

125

AWS Lambda Developer Guide
Sample Code
import java.util.regex.Pattern;
import javax.imageio.ImageIO;
import
import
import
import
import
import
import
import
import

com.amazonaws.services.lambda.runtime.Context;
com.amazonaws.services.lambda.runtime.RequestHandler;
com.amazonaws.services.lambda.runtime.events.S3Event;
com.amazonaws.services.s3.AmazonS3;
com.amazonaws.services.s3.AmazonS3Client;
com.amazonaws.services.s3.event.S3EventNotification.S3EventNotificationRecord;
com.amazonaws.services.s3.model.GetObjectRequest;
com.amazonaws.services.s3.model.ObjectMetadata;
com.amazonaws.services.s3.model.S3Object;

public class S3EventProcessorCreateThumbnail implements
RequestHandler {
private static final float MAX_WIDTH = 100;
private static final float MAX_HEIGHT = 100;
private final String JPG_TYPE = (String) "jpg";
private final String JPG_MIME = (String) "image/jpeg";
private final String PNG_TYPE = (String) "png";
private final String PNG_MIME = (String) "image/png";
public String handleRequest(S3Event s3event, Context context) {
try {
S3EventNotificationRecord record = s3event.getRecords().get(0);
String srcBucket = record.getS3().getBucket().getName();
// Object key may have spaces or unicode non-ASCII characters.
String srcKey = record.getS3().getObject().getKey()
.replace('+', ' ');
srcKey = URLDecoder.decode(srcKey, "UTF-8");
String dstBucket = srcBucket + "resized";
String dstKey = "resized-" + srcKey;
// Sanity check: validate that source and destination are different
// buckets.
if (srcBucket.equals(dstBucket)) {
System.out
.println("Destination bucket must not match source bucket.");
return "";
}
// Infer the image type.
Matcher matcher = Pattern.compile(".*\\.([^\\.]*)").matcher(srcKey);
if (!matcher.matches()) {
System.out.println("Unable to infer image type for key "
+ srcKey);
return "";
}
String imageType = matcher.group(1);
if (!(JPG_TYPE.equals(imageType)) && !(PNG_TYPE.equals(imageType))) {
System.out.println("Skipping non-image " + srcKey);
return "";
}
// Download the image from S3 into a stream
AmazonS3 s3Client = new AmazonS3Client();
S3Object s3Object = s3Client.getObject(new GetObjectRequest(
srcBucket, srcKey));
InputStream objectData = s3Object.getObjectContent();
// Read the source image
BufferedImage srcImage = ImageIO.read(objectData);
int srcHeight = srcImage.getHeight();

126

AWS Lambda Developer Guide
Sample Code
int srcWidth = srcImage.getWidth();
// Infer the scaling factor to avoid stretching the image
// unnaturally
float scalingFactor = Math.min(MAX_WIDTH / srcWidth, MAX_HEIGHT
/ srcHeight);
int width = (int) (scalingFactor * srcWidth);
int height = (int) (scalingFactor * srcHeight);
BufferedImage resizedImage = new BufferedImage(width, height,
BufferedImage.TYPE_INT_RGB);
Graphics2D g = resizedImage.createGraphics();
// Fill with white before applying semi-transparent (alpha) images
g.setPaint(Color.white);
g.fillRect(0, 0, width, height);
// Simple bilinear resize
// If you want higher quality algorithms, check this link:
// https://today.java.net/pub/a/today/2007/04/03/perils-of-imagegetscaledinstance.html
g.setRenderingHint(RenderingHints.KEY_INTERPOLATION,
RenderingHints.VALUE_INTERPOLATION_BILINEAR);
g.drawImage(srcImage, 0, 0, width, height, null);
g.dispose();
// Re-encode image to target format
ByteArrayOutputStream os = new ByteArrayOutputStream();
ImageIO.write(resizedImage, imageType, os);
InputStream is = new ByteArrayInputStream(os.toByteArray());
// Set Content-Length and Content-Type
ObjectMetadata meta = new ObjectMetadata();
meta.setContentLength(os.size());
if (JPG_TYPE.equals(imageType)) {
meta.setContentType(JPG_MIME);
}
if (PNG_TYPE.equals(imageType)) {
meta.setContentType(PNG_MIME);
}

}

}

// Uploading to S3 destination bucket
System.out.println("Writing to: " + dstBucket + "/" + dstKey);
s3Client.putObject(dstBucket, dstKey, is, meta);
System.out.println("Successfully resized " + srcBucket + "/"
+ srcKey + " and uploaded to " + dstBucket + "/" + dstKey);
return "Ok";
} catch (IOException e) {
throw new RuntimeException(e);
}

Amazon S3 invokes your Lambda function using the Event invocation type, where AWS Lambda
executes the code asynchronously. What you return does not matter. However, in this case we are
implementing an interface that requires us to specify a return type, so in this example the handler uses
String as the return type.

Dependencies
• aws-lambda-java-core
• aws-lambda-java-events
• aws-java-sdk-s3
Build the code with the Lambda library dependencies to create a deployment package. For instructions,
see AWS Lambda Deployment Package in Java (p. 276).

127

AWS Lambda Developer Guide
Sample Code

Python 3
The following example code receives an Amazon S3 event input and processes the message that it
contains. It resizes an image in the source bucket and saves the output to the target bucket.

Example CreateThumbnail.py
from __future__ import print_function
import boto3
import os
import sys
import uuid
from PIL import Image
import PIL.Image
s3_client = boto3.client('s3')
def resize_image(image_path, resized_path):
with Image.open(image_path) as image:
image.thumbnail(tuple(x / 2 for x in image.size))
image.save(resized_path)
def handler(event, context):
for record in event['Records']:
bucket = record['s3']['bucket']['name']
key = record['s3']['object']['key']
download_path = '/tmp/{}{}'.format(uuid.uuid4(), key)
upload_path = '/tmp/resized-{}'.format(key)
s3_client.download_file(bucket, key, download_path)
resize_image(download_path, upload_path)
s3_client.upload_file(upload_path, '{}resized'.format(bucket), key)

To create a deployment package
1.

Copy the sample code into a ﬁle named CreateThumbnail.py.

2.

Create a virtual environment.
virtualenv ~/shrink_venv
source ~/shrink_venv/bin/activate

3.

Install libraries in the virtual environment
pip install Pillow
pip install boto3

Note

AWS Lambda includes the AWS SDK for Python (Boto 3), so you don't need to include it in
your deployment package, but you can optionally include it for local testing.
4.

Add the contents of lib and lib64 site-packages to your .zip ﬁle.
cd $VIRTUAL_ENV/lib/python3.7/site-packages
zip -r9 ~/CreateThumbnail.zip .

5.

Add your python code to the .zip ﬁle
cd ~
zip -g CreateThumbnail.zip CreateThumbnail.py
128

AWS Lambda Developer Guide
Sample Template

AWS SAM Template for an Amazon S3 Application
You can build this application using AWS SAM. To learn more about creating AWS SAM templates, see
AWS SAM Template Basics in the AWS Serverless Application Model Developer Guide.
Below is a sample AWS SAM template for the Lambda application from the tutorial (p. 116). Copy
the text below to a .yaml ﬁle and save it next to the ZIP package you created previously. Note that
the Handler and Runtime parameter values should match the ones you used when you created the
function in the previous section.

Example template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
CreateThumbnail:
Type: AWS::Serverless::Function
Properties:
Handler: handler
Runtime: runtime
Timeout: 60
Policies: AWSLambdaExecute
Events:
CreateThumbnailEvent:
Type: S3
Properties:
Bucket: !Ref SrcBucket
Events: s3:ObjectCreated:*
SrcBucket:
Type: AWS::S3::Bucket

For information on how to package and deploy your serverless application using the package and deploy
commands, see Deploying Serverless Applications in the AWS Serverless Application Model Developer
Guide.

Using AWS Lambda with Amazon Kinesis
You can use an AWS Lambda function to process records in an Amazon Kinesis data stream. With Kinesis,
you can collect data from many sources and process them with multiple consumers. Lambda supports
standard data stream iterators and HTTP/2 stream consumers.
Lambda reads records from the data stream and invokes your function synchronously (p. 63) with an
event that contains stream records. Lambda reads records in batches and invokes your function to
process records from the batch.

Example Kinesis Record Event
{

"Records": [
{
"kinesis": {
"kinesisSchemaVersion": "1.0",
"partitionKey": "1",
"sequenceNumber":
"49590338271490256608559692538361571095921575989136588898",
"data": "SGVsbG8sIHRoaXMgaXMgYSB0ZXN0Lg==",
"approximateArrivalTimestamp": 1545084650.987
},

129

AWS Lambda Developer Guide
Conﬁguring Your Data Stream and Function
"eventSource": "aws:kinesis",
"eventVersion": "1.0",
"eventID":
"shardId-000000000006:49590338271490256608559692538361571095921575989136588898",
"eventName": "aws:kinesis:record",
"invokeIdentityArn": "arn:aws:iam::123456789012:role/lambda-role",
"awsRegion": "us-east-2",
"eventSourceARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream"
},
{
"kinesis": {
"kinesisSchemaVersion": "1.0",
"partitionKey": "1",
"sequenceNumber":
"49590338271490256608559692540925702759324208523137515618",
"data": "VGhpcyBpcyBvbmx5IGEgdGVzdC4=",
"approximateArrivalTimestamp": 1545084711.166
},
"eventSource": "aws:kinesis",
"eventVersion": "1.0",
"eventID":
"shardId-000000000006:49590338271490256608559692540925702759324208523137515618",
"eventName": "aws:kinesis:record",
"invokeIdentityArn": "arn:aws:iam::123456789012:role/lambda-role",
"awsRegion": "us-east-2",
"eventSourceARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream"
}
]

}

If you have multiple applications that are reading records from the same stream, you can use Kinesis
stream consumers instead of standard iterators. Consumers have dedicated read throughput so they
don't have to compete with other consumers of the same data. With consumers, Kinesis pushes records
to Lambda over an HTTP/2 connection, which can also reduce latency between adding a record and
function invocation.
If your function returns an error, Lambda retries the batch until processing succeeds or the data expires.
Until the issue is resolved, no data in the shard is processed. To avoid stalled shards and potential data
loss, make sure to handle and record processing errors in your code.
Topics
• Conﬁguring Your Data Stream and Function (p. 130)
• Creating an Event Source Mapping (p. 131)
• Event Source Mapping API (p. 132)
• Execution Role Permissions (p. 133)
• Amazon CloudWatch Metrics (p. 133)
• Tutorial: Using AWS Lambda with Amazon Kinesis (p. 133)
• Sample Function Code (p. 137)
• AWS SAM Template for a Kinesis Application (p. 140)

Conﬁguring Your Data Stream and Function
Your Lambda function is a consumer application for your data stream. It processes one batch of records
at a time from each shard. You can map a Lambda function to a data stream (standard iterator), or to a
consumer of a stream (enhanced fan-out).
For standard iterators, Lambda polls each shard in your Kinesis stream for records at a base rate of once
per second. When more records are available, Lambda keeps processing batches until it receives a batch

130

AWS Lambda Developer Guide
Creating an Event Source Mapping

that's smaller than the conﬁgured maximum batch size. The function shares read throughput with other
consumers of the shard.
To minimize latency and maximize read throughput, create a data stream consumer. Stream consumers
get a dedicated connection to each shard that doesn't impact other applications reading from the
stream. The dedicated throughput can help if you have many applications reading the same data, or if
you're reprocessing a stream with large records.
Stream consumers use HTTP/2 to reduce latency by pushing records to Lambda over a long-lived
connection and compressing request headers. You can create a stream consumer with the Kinesis
RegisterStreamConsumer API.
$ aws kinesis register-stream-consumer --consumer-name con1 \
--stream-arn arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream
{
"Consumer": {
"ConsumerName": "con1",
"ConsumerARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream/
consumer/con1:1540591608",
"ConsumerStatus": "CREATING",
"ConsumerCreationTimestamp": 1540591608.0
}
}

To increase the speed at which your function processes records, add shards to your data stream. Lambda
processes records in each shard in order, and stops processing additional records in a shard if your
function returns an error. With more shards, there are more batches being processed at once, which
lowers the impact of errors on concurrency.

Note

If the total size of the records in a batch exceeds the payload limit (p. 249), Lambda splits it
into smaller batches for processing.
If your function can't scale up to handle one concurrent execution per shard, request a limit
increase (p. 249) or reserve concurrency (p. 241) for your function. The concurrency available to your
function should match or exceed the number of shards in your Kinesis data stream.

Creating an Event Source Mapping
Create an event source mapping to tell Lambda to send records from your data stream to a Lambda
function. You can create multiple event source mappings to process the same data with multiple Lambda
functions, or process items from multiple data streams with a single function.
To conﬁgure your function to read from Kinesis in the Lambda console, create a Kinesis trigger.

To create a trigger
1.
2.

Open the Lambda console Functions page.
Choose a function.

3.
4.
5.

Under Designer, choose a trigger type to add a trigger to your function.
Under Conﬁgure triggers, conﬁgure the event source options and then choose Add.
Choose Save.

Lambda supports the following options for Kinesis event sources.

Event Source Options
• Kinesis stream – The Kinesis stream to read records from.

131

AWS Lambda Developer Guide
Event Source Mapping API

• Consumer (optional) – Use a stream consumer to read from the stream over a dedicated connection.
• Batch size – The number of records to read from a shard in each batch, up to 10,000. Lambda passes
all of the records in the batch to the function in a single call, as long as the total size of the events
doesn't exceed the payload limit of 6 MB.
• Starting position – Process only new records, all existing records, or records created after a certain
date.
• Latest – Process new records that are added to the stream.
• Trim horizon – Process all records in the stream.
• At timestamp – Process records starting from a speciﬁc time.
After processing any existing records, the function is caught up and continues to process new records.
• Enabled – Disable the event source to stop processing records. Lambda keeps track of the last record
processed and resumes processing from that point when it's re-enabled.
To manage the event source conﬁguration later, choose the trigger in the designer.

Event Source Mapping API
To create the event source mapping with the AWS CLI, use the CreateEventSourceMapping (p. 364)
API. The following example uses the AWS CLI to map a function named my-function to a Kinesis
data stream. The data stream is speciﬁed by an Amazon Resource Name (ARN), with a batch size of 500
hundred, starting from the timestamp in Unix time.
$ aws lambda create-event-source-mapping --function-name my-function --no-enabled \
--batch-size 500 --starting-position AT_TIMESTAMP --starting-position-timestamp 1541139109
\
--event-source-arn arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream
{
"UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284",
"BatchSize": 500,
"EventSourceArn": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"LastModified": 1541139209.351,
"LastProcessingResult": "No records processed",
"State": "Creating",
"StateTransitionReason": "User action"
}

To use a consumer, specify the consumer's ARN instead of the stream's ARN. The --no-enabled option
creates the event source mapping without enabling it. To enable it, use update-event-sourcemapping.
$ aws lambda update-event-source-mapping --uuid 2b733gdc-8ac3-cdf5-af3a-1827b3b1128 -enabled
{
"UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b1128",
"BatchSize": 500,
"EventSourceArn": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"LastModified": 1541190239.996,
"LastProcessingResult": "No records processed",
"State": "Enabling",
"StateTransitionReason": "User action"
}

To delete the event source mapping, use delete-event-source-mapping.
132

AWS Lambda Developer Guide
Execution Role Permissions

$ aws lambda delete-event-source-mapping --uuid 2b733gdc-8ac3-cdf5-af3a-1827b3b11284
{
"UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284",
"BatchSize": 500,
"EventSourceArn": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"LastModified": 1541190240.0,
"LastProcessingResult": "No records processed",
"State": "Deleting",
"StateTransitionReason": "User action"
}

Execution Role Permissions
Lambda needs the following permissions to manage resources that are related to your Kinesis data
stream. Add them to your function's execution role (p. 222).
• kinesis:DescribeStream
• kinesis:DescribeStreamSummary
• kinesis:GetRecords
• kinesis:GetShardIterator
• kinesis:ListShards
• kinesis:ListStreams
• kinesis:SubscribeToShard
The AWSLambdaKinesisExecutionRole managed policy includes these permissions. For more
information, see AWS Lambda Execution Role (p. 222).

Amazon CloudWatch Metrics
Lambda emits the IteratorAge metric when your function ﬁnishes processing a batch of records. The
metric indicates how old the last record in the batch was when processing ﬁnished. If your function is
processing new events, you can use the iterator age to estimate the latency between when a record is
added, and when the function processes it.
An increasing trend in iterator age can indicate issues with your function. For more information, see
Using Amazon CloudWatch (p. 208).

Tutorial: Using AWS Lambda with Amazon Kinesis
In this tutorial, you create a Lambda function to consume events from a Kinesis stream. The following
diagram illustrates the application ﬂow:

133

AWS Lambda Developer Guide
Tutorial

1. Custom app writes records to the stream.
2. AWS Lambda polls the stream and, when it detects new records in the stream, invokes your Lambda
function.
3. AWS Lambda executes the Lambda function by assuming the execution role you speciﬁed at the time
you created the Lambda function.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.
2.

Open the roles page in the IAM console.
Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – AWS Lambda.
• Permissions – AWSLambdaKinesisExecutionRole.
• Role name – lambda-kinesis-role.

The AWSLambdaKinesisExecutionRole policy has the permissions that the function needs to read items
from Kinesis and write logs to CloudWatch Logs.

134

AWS Lambda Developer Guide
Tutorial

Create the Function
The following example code receives a Kinesis event input and processes the messages that it contains.
For illustration, the code writes some of the incoming event data to CloudWatch Logs.

Note

For sample code in other languages, see Sample Function Code (p. 137).

Example index.js
console.log('Loading function');
exports.handler = function(event, context) {
//console.log(JSON.stringify(event, null, 2));
event.Records.forEach(function(record) {
// Kinesis data is base64 encoded so decode here
var payload = new Buffer(record.kinesis.data, 'base64').toString('ascii');
console.log('Decoded payload:', payload);
});
};

To create the function
1.

Copy the sample code into a ﬁle named index.js.

2.

Create a deployment package.
$ zip function.zip index.js

3.

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name ProcessKinesisRecord \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 \
--role arn:aws:iam::123456789012:role/lambda-kinesis-role

Test the Lambda Function
Invoke your Lambda function manually using the invoke AWS Lambda CLI command and a sample
Kinesis event.

To test the Lambda function
1.

Copy the following JSON into a ﬁle and save it as input.txt.
{

"Records": [
{
"kinesis": {
"kinesisSchemaVersion": "1.0",
"partitionKey": "1",
"sequenceNumber":
"49590338271490256608559692538361571095921575989136588898",
"data": "SGVsbG8sIHRoaXMgaXMgYSB0ZXN0Lg==",
"approximateArrivalTimestamp": 1545084650.987
},
"eventSource": "aws:kinesis",
"eventVersion": "1.0",
"eventID":
"shardId-000000000006:49590338271490256608559692538361571095921575989136588898",

135

AWS Lambda Developer Guide
Tutorial

stream"
}

2.

]

"eventName": "aws:kinesis:record",
"invokeIdentityArn": "arn:aws:iam::123456789012:role/lambda-kinesis-role",
"awsRegion": "us-east-2",
"eventSourceARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda}

Use the invoke command to send the event to the function.
$ aws lambda invoke --function-name ProcessKinesisRecords --payload file://input.txt
out.txt

The response is saved to out.txt.

Create a Kinesis Stream
Use the create-stream command to create a stream.
$ aws kinesis create-stream --stream-name lambda-stream --shard-count 1

Run the following describe-stream command to get the stream ARN.
$ aws kinesis describe-stream --stream-name lambda-stream
{
"StreamDescription": {
"Shards": [
{
"ShardId": "shardId-000000000000",
"HashKeyRange": {
"StartingHashKey": "0",
"EndingHashKey": "340282366920746074317682119384634633455"
},
"SequenceNumberRange": {
"StartingSequenceNumber":
"49591073947768692513481539594623130411957558361251844610"
}
}
],
"StreamARN": "arn:aws:kinesis:us-west-2:123456789012:stream/lambda-stream",
"StreamName": "lambda-stream",
"StreamStatus": "ACTIVE",
"RetentionPeriodHours": 24,
"EnhancedMonitoring": [
{
"ShardLevelMetrics": []
}
],
"EncryptionType": "NONE",
"KeyId": null,
"StreamCreationTimestamp": 1544828156.0
}
}

You use the stream ARN in the next step to associate the stream with your Lambda function.

Add an Event Source in AWS Lambda
Run the following AWS CLI add-event-source command.

136

AWS Lambda Developer Guide
Sample Code

$ aws lambda create-event-source-mapping --function-name ProcessKinesisRecords \
--event-source arn:aws:kinesis:us-west-2:123456789012:stream/lambda-stream \
--batch-size 100 --starting-position LATEST

Note the mapping ID for later use. You can get a list of event source mappings by running the listevent-source-mappings command.
$ aws lambda list-event-source-mappings --function-name ProcessKinesisRecords \
--event-source arn:aws:kinesis:us-west-2:123456789012:stream/lambda-stream

In the response, you can verify the status value is enabled. Event source mappings can be disabled to
pause polling temporarily losing any records.

Test the Setup
To test the event source mapping, add event records to your Kinesis stream. The --data value is a
base64-encoded value of the "Hello, this is a test." string. You can run the same command
more than once to add multiple records to the stream.
$ aws kinesis put-record --stream-name lambda-stream --partition-key 1 \
--data "SGVsbG8sIHRoaXMgaXMgYSB0ZXN0Lg=="

Lambda uses the execution role to read records from the stream. Then it invokes your Lambda function,
passing in batches of records. The function decodes data from each record and logs it, sending the
output to CloudWatch Logs. View the logs in the CloudWatch console.

Sample Function Code
Sample code is available for the following languages.
Topics
• Node.js 8 (p. 137)
• Java 8 (p. 138)
• C# (p. 138)
• Python 3 (p. 139)
• Go (p. 140)

Node.js 8
The following example code receives a Kinesis event input and processes the messages that it contains.
For illustration, the code writes some of the incoming event data to CloudWatch Logs.

Example index.js
console.log('Loading function');
exports.handler = function(event, context) {
//console.log(JSON.stringify(event, null, 2));
event.Records.forEach(function(record) {
// Kinesis data is base64 encoded so decode here
var payload = new Buffer(record.kinesis.data, 'base64').toString('ascii');

137

AWS Lambda Developer Guide
Sample Code

};

console.log('Decoded payload:', payload);

});

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Node.js (p. 250).

Java 8
The following is example Java code that receives Kinesis event record data as input and processes it. For
illustration, the code writes some of the incoming event data to CloudWatch Logs.
In the code, recordHandler is the handler. The handler uses the predeﬁned KinesisEvent class that
is deﬁned in the aws-lambda-java-events library.

Example ProcessKinesisEvents.java
package example;
import
import
import
import

com.amazonaws.services.lambda.runtime.Context;
com.amazonaws.services.lambda.runtime.RequestHandler;
com.amazonaws.services.lambda.runtime.events.KinesisEvent;
com.amazonaws.services.lambda.runtime.events.KinesisEvent.KinesisEventRecord;

public class ProcessKinesisRecords implements RequestHandler{
@Override
public Void recordHandler(KinesisEvent event, Context context)
{
for(KinesisEventRecord rec : event.getRecords()) {
System.out.println(new String(rec.getKinesis().getData().array()));
}
return null;
}
}

If the handler returns normally without exceptions, Lambda considers the input batch of records as
processed successfully and begins reading new records in the stream. If the handler throws an exception,
Lambda considers the input batch of records as not processed and invokes the function with the same
batch of records again.

Dependencies
• aws-lambda-java-core
• aws-lambda-java-events
• aws-java-sdk-s3
Build the code with the Lambda library dependencies to create a deployment package. For instructions,
see AWS Lambda Deployment Package in Java (p. 276).

C#
The following is example C# code that receives Kinesis event record data as input and processes it. For
illustration, the code writes some of the incoming event data to CloudWatch Logs.
In the code, HandleKinesisRecord is the handler. The handler uses the predeﬁned KinesisEvent
class that is deﬁned in the Amazon.Lambda.KinesisEvents library.

138

AWS Lambda Developer Guide
Sample Code

Example ProcessingKinesisEvents.cs
using System;
using System.IO;
using System.Text;
using Amazon.Lambda.Core;
using Amazon.Lambda.KinesisEvents;
namespace KinesisStreams
{
public class KinesisSample
{
[LambdaSerializer(typeof(JsonSerializer))]
public void HandleKinesisRecord(KinesisEvent kinesisEvent)
{
Console.WriteLine($"Beginning to process {kinesisEvent.Records.Count}
records...");
foreach (var record in kinesisEvent.Records)
{
Console.WriteLine($"Event ID: {record.EventId}");
Console.WriteLine($"Event Name: {record.EventName}");
string recordData = GetRecordContents(record.Kinesis);
Console.WriteLine($"Record Data:");
Console.WriteLine(recordData);

}

}

}

}
Console.WriteLine("Stream processing complete.");

private string GetRecordContents(KinesisEvent.Record streamRecord)
{
using (var reader = new StreamReader(streamRecord.Data, Encoding.ASCII))
{
return reader.ReadToEnd();
}
}

Replace the Program.cs in a .NET Core project with the above sample. For instructions, see .NET Core
CLI (p. 317).

Python 3
The following is example Python code that receives Kinesis event record data as input and processes it.
For illustration, the code writes to some of the incoming event data to CloudWatch Logs.

Example ProcessKinesisRecords.py
from __future__ import print_function
#import json
import base64
def lambda_handler(event, context):
for record in event['Records']:
#Kinesis data is base64 encoded so decode here
payload=base64.b64decode(record["kinesis"]["data"])
print("Decoded payload: " + str(payload))

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Python (p. 262).

139

AWS Lambda Developer Guide
Sample Template

Go
The following is example Go code that receives Kinesis event record data as input and processes it. For
illustration, the code writes to some of the incoming event data to CloudWatch Logs.

Example ProcessKinesisRecords.go
import (
"strings"
"github.com/aws/aws-lambda-go/events"
)
func handler(ctx context.Context, kinesisEvent events.KinesisEvent) {
for _, record := range kinesisEvent.Records {
kinesisRecord := record.Kinesis
dataBytes := kinesisRecord.Data
dataText := string(dataBytes)

}

}

fmt.Printf("%s Data = %s \n", record.EventName, dataText)

Build the executable with go build and create a deployment package. For instructions, see AWS
Lambda Deployment Package in Go (p. 304).

AWS SAM Template for a Kinesis Application
You can build this application using AWS SAM. To learn more about creating AWS SAM templates, see
AWS SAM Template Basics in the AWS Serverless Application Model Developer Guide.
Below is a sample AWS SAM template for the Lambda application from the tutorial (p. 133). The
function and handler in the template are for the Node.js code. If you use a diﬀerent code sample, update
the values accordingly.

Example template.yaml - Kinesis Stream
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
LambdaFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: nodejs8.10
Timeout: 10
Tracing: Active
Events:
Stream:
Type: Kinesis
Properties:
Stream: !GetAtt KinesisStream.Arn
BatchSize: 100
StartingPosition: LATEST
KinesisStream:
Type: AWS::Kinesis::Stream
Properties:
ShardCount: 1
Outputs:
FunctionName:
Description: "Function name"

140

AWS Lambda Developer Guide
Amazon SQS
Value: !Ref LambdaFunction
StreamARN:
Description: "Stream ARN"
Value: !GetAtt KinesisStream.Arn

The template creates a Lambda function, a Kinesis stream, and an event source mapping. The event
source mapping reads from the stream and invokes the function.
To use an HTTP/2 stream consumer (p. 130), create the consumer in the template and conﬁgure the
event source mapping to read from the consumer instead of from the stream.

Example template.yaml - Kinesis Stream Consumer
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: A function that processes data from a Kinesis stream.
Resources:
kinesisprocessrecordpython:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: nodejs8.10
Timeout: 10
Tracing: Active
Events:
Stream:
Type: Kinesis
Properties:
Stream: !GetAtt StreamConsumer.ConsumerARN
StartingPosition: LATEST
BatchSize: 100
KinesisStream:
Type: "AWS::Kinesis::Stream"
Properties:
ShardCount: 1
StreamConsumer:
Type: "AWS::Kinesis::StreamConsumer"
Properties:
StreamARN: !GetAtt KinesisStream.Arn
ConsumerName: "TestConsumer"
Outputs:
FunctionName:
Description: "Function name"
Value: !Ref LambdaFunction
StreamARN:
Description: "Stream ARN"
Value: !GetAtt KinesisStream.Arn
ConsumerARN:
Description: "Stream consumer ARN"
Value: !GetAtt StreamConsumer.ConsumerARN

For information on how to package and deploy your serverless application using the package and deploy
commands, see Deploying Serverless Applications in the AWS Serverless Application Model Developer
Guide.

Using AWS Lambda with Amazon SQS
You can use an AWS Lambda function to process messages in a standard Amazon Simple Queue Service
(Amazon SQS) queue. With Amazon SQS, you can oﬄoad tasks from one component of your application
by sending them to a queue and processing them asynchronously.

141

AWS Lambda Developer Guide
Amazon SQS

Lambda polls the queue and invokes your function synchronously (p. 63) with an event that contains
queue messages. Lambda reads messages in batches and invokes your function once for each batch.
When your function successfully processes a batch, Lambda deletes its messages from the queue.

Example Amazon SQS Message Event
{

}

"Records": [
{
"messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
"receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
"body": "test",
"attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "1545082649183",
"SenderId": "AIDAIENQZJOLO23YVJ4VO",
"ApproximateFirstReceiveTimestamp": "1545082649185"
},
"messageAttributes": {},
"md5OfBody": "098f6bcd4621d373cade4e832627b4f6",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
"awsRegion": "us-east-2"
},
{
"messageId": "2e1424d4-f796-459a-8184-9c92662be6da",
"receiptHandle": "AQEBzWwaftRI0KuVm4tP+/7q1rGgNqicHq...",
"body": "test",
"attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "1545082650636",
"SenderId": "AIDAIENQZJOLO23YVJ4VO",
"ApproximateFirstReceiveTimestamp": "1545082650649"
},
"messageAttributes": {},
"md5OfBody": "098f6bcd4621d373cade4e832627b4f6",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
"awsRegion": "us-east-2"
}
]

Lambda uses long polling to poll a queue until it becomes active. When messages are available, Lambda
increases the rate at which it reads batches, and invokes your function until it reaches a concurrency
limit. For more information on how Lambda scales to process messages in your Amazon SQS queue, see
Understanding Scaling Behavior (p. 68).
When Lambda reads a message from the queue, it stays in the queue but becomes hidden until Lambda
deletes it. If your function returns an error, or doesn't ﬁnish processing before the queue's visibility
timeout, it becomes visible again. Then Lambda sends it to your Lambda function again. All messages
in a failed batch return to the queue, so your function code must be able to process the same message
multiple times without side eﬀects.
Sections
• Conﬁguring a Queue for Use With Lambda (p. 143)
• Conﬁguring a Queue as an Event Source (p. 143)
• Execution Role Permissions (p. 143)
• Tutorial: Using AWS Lambda with Amazon Simple Queue Service (p. 144)
• Sample Amazon SQS Function Code (p. 147)

142

AWS Lambda Developer Guide
Conﬁguring a Queue for Use With Lambda

• AWS SAM Template for an Amazon SQS Application (p. 150)

Conﬁguring a Queue for Use With Lambda
Create a standard Amazon SQS queue to serve as an event source for your Lambda function. Then
conﬁgure the queue to allow time for your Lambda function to process each batch of events—and for
Lambda to retry in response to throttling errors as it scales up.
To allow your function time to process each batch of records, set the source queue's visibility timeout
to at least 6 times the timeout (p. 22) that you conﬁgure on your function. The extra time allows for
Lambda to retry if your function execution is throttled while your function is processing a previous batch.
If a message fails processing multiple times, Amazon SQS can send it to a dead letter queue. Conﬁgure
a dead letter queue on your source queue to retain messages that failed processing for troubleshooting.
Set the maxReceiveCount on the queue's redrive policy to at least 5 to avoid sending messages to the
dead letter queue due to throttling.

Conﬁguring a Queue as an Event Source
Create an event source mapping to tell Lambda to send items from your queue to a Lambda function.
You can create multiple event source mappings to process items from multiple queues with a single
function. When Lambda invokes the target function, the event can contain multiple items, up to a
conﬁgurable maximum batch size.

To add an event source mapping for an Amazon SQS queue
1.

Open the Lambda console Functions page.

2.

Choose a function.

3.

Under Add triggers, choose SQS.

4.

Under Conﬁgure triggers, conﬁgure the event source.
• SQS queue – Specify the source queue.
• Batch size – Specify the maximum number of items to read from the queue and send to your
function, in a single invocation.
• Enabled – Clear the check box to disable the event source.

5.

Choose Add.

6.

Choose Save.

Conﬁgure your function timeout to allow enough time to process an entire batch of items. If items take a
long time to process, choose a smaller batch size. A large batch size can improve eﬃciency for workloads
that are very fast or have a lot of overhead. However, if your function returns an error, all items in the
batch return to the queue. If you conﬁgure reserved concurrency (p. 242) on your function, set a
minimum of 5 concurrent executions to reduce the chance of throttling errors when Lambda invokes
your function.
To conﬁgure an event source with the Lambda API or the AWS SDK, use the
CreateEventSourceMapping (p. 364) and UpdateEventSourceMapping (p. 462) actions.

Execution Role Permissions
Lambda needs the following permissions to manage messages in your Amazon SQS queue. Add them to
your function's execution role (p. 222).
143

AWS Lambda Developer Guide
Tutorial

• sqs:ReceiveMessage
• sqs:DeleteMessage
• sqs:GetQueueAttributes
For more information, see AWS Lambda Execution Role (p. 222).

Tutorial: Using AWS Lambda with Amazon Simple
Queue Service
In this tutorial, you create a Lambda function to consume messages from an Amazon SQS queue.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.

Open the roles page in the IAM console.

2.

Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – AWS Lambda.
• Permissions – AWSLambdaSQSQueueExecutionRole.
• Role name – lambda-sqs-role.

The AWSLambdaSQSQueueExecutionRole policy has the permissions that the function needs to read
items from Amazon SQS and write logs to CloudWatch Logs.

Create the Function
The following example code receives an Amazon SQS event input and processes the messages that it
contains. For illustration, the code writes some of the incoming event data to CloudWatch Logs.
144

AWS Lambda Developer Guide
Tutorial

Note

For sample code in other languages, see Sample Amazon SQS Function Code (p. 147).

Example index.js
exports.handler = async function(event, context) {
event.Records.forEach(record => {
const { body } = record;
console.log(body);
});
return {};
}

To create the function
1.

Copy the sample code into a ﬁle named index.js.

2.

Create a deployment package.
$ zip function.zip index.js

3.

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name ProcessSQSRecord \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 \
--role arn:aws:iam::123456789012:role/lambda-sqs-role

Test the Function
Invoke your Lambda function manually using the invoke AWS Lambda CLI command and a sample
Amazon Simple Queue Service event.
If the handler returns normally without exceptions, Lambda considers the message processed
successfully and begins reading new messages in the queue. Once a message is processed successfully, it
is automatically deleted from the queue. If the handler throws an exception, Lambda considers the input
of messages as not processed and invokes the function with the same batch of messages.
1.

Copy the following JSON into a ﬁle and save it as input.txt.
{

}

"Records": [
{
"messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
"receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
"body": "test",
"attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "1545082649183",
"SenderId": "AIDAIENQZJOLO23YVJ4VO",
"ApproximateFirstReceiveTimestamp": "1545082649185"
},
"messageAttributes": {},
"md5OfBody": "098f6bcd4621d373cade4e832627b4f6",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
"awsRegion": "us-east-2"
}
]

145

AWS Lambda Developer Guide
Tutorial

2.

Execute the following invoke command.
$ aws lambda invoke --invocation-type RequestResponse --function-name ProcessSQSRecord
\
--payload file://input.txt outputfile.txt

The invoke command speciﬁes RequestResponse as the invocation type, which requests
synchronous execution. For more information, see Invocation Types (p. 63).
3.

Verify the output in the outputfile.txt ﬁle.

Create an Amazon SQS Queue
Create an Amazon SQS queue that the Lambda function can use as an event source.

To create a queue
1.

Sign in to the AWS Management Console and open the Amazon SQS console at https://
console.aws.amazon.com/sqs/.

2.

In the Amazon SQS console, create a queue.

3.

Write down or otherwise record the identifying queue ARN (Amazon Resource Name). You need this
in the next step when you associate the queue with your Lambda function.

Create an event source mapping in AWS Lambda. This event source mapping associates the Amazon
SQS queue with your Lambda function. After you create this event source mapping, AWS Lambda starts
polling the queue.
Test the end-to-end experience. As you perform queue updates, Amazon Simple Queue Service writes
messages to the queue. AWS Lambda polls the queue, detects new records and executes your Lambda
function on your behalf by passing events, in this case Amazon SQS messages, to the function.

Conﬁgure the Event Source
To create a mapping between the speciﬁed Amazon SQS queue and the Lambda function, run the
following AWS CLI create-event-source-mapping command. After the command executes, write
down or otherwise record the UUID. You'll need this UUID to refer to the event source mapping in any
other commands, for example, if you choose to delete the event source mapping.
$ aws lambda create-event-source-mapping --function-name ProcessSQSRecord
\
--event-source SQS-queue-arn

--batch-size 10

You can get the list of event source mappings by running the following command.
$ aws lambda list-event-source-mappings --function-name ProcessSQSRecord \
--event-source SQS-queue-arn

The list returns all of the event source mappings you created, and for each mapping it shows the
LastProcessingResult, among other things. This ﬁeld is used to provide an informative message if
there are any problems. Values such as No records processed (indicates that AWS Lambda has not
started polling or that there are no records in the queue) and OK (indicates AWS Lambda successfully
read records from the queue and invoked your Lambda function) indicate that there no issues. If there
are issues, you receive an error message.
146

AWS Lambda Developer Guide
Sample Code

Test the Setup
Now you can test the setup as follows:
1. In the Amazon SQS console, send messsages to the queue. Amazon SQS writes records of these
actions to the queue.
2. AWS Lambda polls the queue and when it detects updates, it invokes your Lambda function by
passing in the event data it ﬁnds in the queue.
3. Your function executes and creates logs in Amazon CloudWatch. You can verify the logs reported in
the Amazon CloudWatch console.

Sample Amazon SQS Function Code
Sample code is available for the following languages.
Topics
• Node.js (p. 147)
• Java (p. 147)
• C# (p. 148)
• Go (p. 149)
• Python (p. 149)

Node.js
The following is example code that receives an Amazon SQS event message as input and processes it. For
illustration, the code writes some of the incoming event data to CloudWatch Logs.

Example index.js (Node.js 8)
exports.handler = async function(event, context) {
event.Records.forEach(record => {
const { body } = record;
console.log(body);
});
return {};
}

Example index.js (Node.js 6)
event.Records.forEach(function(record) {
var body = record.body;
console.log(body);
});
callback(null, "message");
};

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Node.js (p. 250).

Java
The following is example Java code that receives an Amazon SQS event message as input and processes
it. For illustration, the code writes some of the incoming event data to CloudWatch Logs.

147

AWS Lambda Developer Guide
Sample Code

In the code, handleRequest is the handler. The handler uses the predeﬁned SQSEvent class that is
deﬁned in the aws-lambda-java-events library.

Example ProcessSQSRecord.java
import
import
import
import

com.amazonaws.services.lambda.runtime.Context;
com.amazonaws.services.lambda.runtime.RequestHandler;
com.amazonaws.services.lambda.runtime.events.SQSEvent;
com.amazonaws.services.lambda.runtime.events.SQSEvent.SQSMessage;

public class ProcessSQSEvents implements RequestHandler{
@Override
public Void handleRequest(SQSEvent event, Context context)
{
for(SQSMessage msg : event.getRecords()){
System.out.println(new String(msg.getSQS().getBody()));
}
return null;
}
}

Dependencies
• aws-lambda-java-core
• aws-lambda-java-events
Build the code with the Lambda library dependencies to create a deployment package. For instructions,
see AWS Lambda Deployment Package in Java (p. 276).

C#
The following is example C# code that receives an Amazon SQS event message as input and processes it.
For illustration, the code writes some of the incoming event data to the console.
In the code, handleRequest is the handler. The handler uses the predeﬁned SQSEvent class that is
deﬁned in the AWS.Lambda.SQSEvents library.

Example ProcessingSQSRecords.cs
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.Json.JsonSerializer))]
namespace SQSLambdaFunction
{
public class SQSLambdaFunction
{
public string HandleSQSEvent(SQSEvent sqsEvent, ILambdaContext context)
{
Console.WriteLine($"Beginning to process {sqsEvent.Records.Count} records...");
foreach (var record in sqsEvent.Records)
{
Console.WriteLine($"Message ID: {record.MessageId}");
Console.WriteLine($"Event Source: {record.EventSource}");

}

Console.WriteLine($"Record Body:");
Console.WriteLine(record.Body);

Console.WriteLine("Processing complete.");

148

AWS Lambda Developer Guide
Sample Code

}

}

return $"Processed {sqsEvent.Records.Count} records.";

}

Replace the Program.cs in a .NET Core project with the above sample. For instructions, see .NET Core
CLI (p. 317).

Go
The following is example Go code that receives an Amazon SQS event message as input and processes it.
For illustration, the code writes some of the incoming event data to CloudWatch Logs.
In the code, handler is the handler. The handler uses the predeﬁned SQSEvent class that is deﬁned in
the aws-lambda-go-events library.

Example ProcessSQSRecords.go
package main
import (
"context"
"fmt"

)

"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"

func handler(ctx context.Context, sqsEvent events.SQSEvent) error {
for _, message := range sqsEvent.Records {
fmt.Printf("The message %s for event source %s = %s \n", message.MessageId,
message.EventSource, message.Body)
}
}

return nil

func main() {
lambda.Start(handler)
}

Build the executable with go build and create a deployment package. For instructions, see AWS
Lambda Deployment Package in Go (p. 304).

Python
The following is example Python code that accepts an Amazon SQS record as input and processes it. For
illustration, the code writes to some of the incoming event data to CloudWatch Logs.
Follow the instructions to create a AWS Lambda function deployment package.

Example ProcessSQSRecords.py
from __future__ import print_function
def lambda_handler(event, context):
for record in event['Records']:
print ("test")
payload=record["body"]

149

AWS Lambda Developer Guide
Sample Template
print(str(payload))

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Python (p. 262).

AWS SAM Template for an Amazon SQS Application
You can build this application using AWS SAM. To learn more about creating AWS SAM templates, see
AWS SAM Template Basics in the AWS Serverless Application Model Developer Guide.
Below is a sample AWS SAM template for the Lambda application from the tutorial (p. 144). Copy
the text below to a .yaml ﬁle and save it next to the ZIP package you created previously. Note that
the Handler and Runtime parameter values should match the ones you used when you created the
function in the previous section.
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Example of processing messages on an SQS queue with Lambda
Resources:
MySQSQueueFunction:
Type: AWS::Serverless::Function
Properties:
Handler: handler
Runtime: runtime
Events:
MySQSEvent:
Type: SQS
Properties:
Queue: !GetAtt MySqsQueue.Arn
BatchSize: 10
MySqsQueue:
Type: AWS::SQS::Queue

For information on how to package and deploy your serverless application using the package and deploy
commands, see Deploying Serverless Applications in the AWS Serverless Application Model Developer
Guide.

Using AWS Lambda with Amazon DynamoDB
You can use a AWS Lambda function to process records in a Amazon DynamoDB Streams stream.
With DynamoDB Streams, you can trigger a Lambda function to perform additional work each time a
DynamoDB table is updated.
Lambda reads records from the stream and invokes your function synchronously (p. 63) with an event
that contains stream records. Lambda reads records in batches and invokes your function to process
records from the batch.

Example DynamoDB Streams Record Event
{

"Records": [
{
"eventID": "1",
"eventVersion": "1.0",
"dynamodb": {
"Keys": {
"Id": {
"N": "101"

150

AWS Lambda Developer Guide
Amazon DynamoDB
}
},
"NewImage": {
"Message": {
"S": "New item!"
},
"Id": {
"N": "101"
}
},
"StreamViewType": "NEW_AND_OLD_IMAGES",
"SequenceNumber": "111",
"SizeBytes": 26

},
"awsRegion": "us-west-2",
"eventName": "INSERT",
"eventSourceARN": eventsourcearn,
"eventSource": "aws:dynamodb"

},
{

}

"eventID": "2",
"eventVersion": "1.0",
"dynamodb": {
"OldImage": {
"Message": {
"S": "New item!"
},
"Id": {
"N": "101"
}
},
"SequenceNumber": "222",
"Keys": {
"Id": {
"N": "101"
}
},
"SizeBytes": 59,
"NewImage": {
"Message": {
"S": "This item has changed"
},
"Id": {
"N": "101"
}
},
"StreamViewType": "NEW_AND_OLD_IMAGES"
},
"awsRegion": "us-west-2",
"eventName": "MODIFY",
"eventSourceARN": sourcearn,
"eventSource": "aws:dynamodb"

Lambda polls shards in your DynamoDB Streams stream for records at a base rate of 4 times per
second. When records are available, Lambda invokes your function and waits for the result. If processing
succeeds, Lambda resumes polling until it receives more records.
If your function returns an error, Lambda retries the batch until processing succeeds or the data expires.
Until the issue is resolved, no data in the shard is processed. Handle any record processing errors in your
code to avoid stalled shards and potential data loss.
Topics
• Creating an Event Source Mapping (p. 152)

151

AWS Lambda Developer Guide
Creating an Event Source Mapping

• Execution Role Permissions (p. 152)
• Tutorial: Using AWS Lambda with Amazon DynamoDB Streams (p. 153)
• Sample Function Code (p. 157)
• AWS SAM Template for a DynamoDB Application (p. 160)

Creating an Event Source Mapping
Create an event source mapping to tell Lambda to send records from your stream to a Lambda function.
You can create multiple event source mappings to process the same data with multiple Lambda
functions, or process items from multiple streams with a single function.
To conﬁgure your function to read from DynamoDB Streams in the Lambda console, create a DynamoDB
trigger.

To create a trigger
1.

Open the Lambda console Functions page.

2.

Choose a function.

3.

Under Designer, choose a trigger type to add a trigger to your function.

4.

Under Conﬁgure triggers, conﬁgure the required options and then choose Add.

5.

Choose Save.

Event Source Options
• DynamoDB table – The DynamoDB table from which to read records.
• Batch size – The number of records to read from a shard in each batch, up to 1,000. Lambda passes all
of the records in the batch to the function in a single call, as long as the total size of the events doesn't
exceed the payload limit of 6 MB.
• Starting position – Process only new records, or all existing records.
• Latest – Process new records added to the stream.
• Trim horizon – Process all records in the stream.
After processing any existing records, the function is caught up and continues to process new records.
• Enabled – Disable the event source to stop processing records. Lambda keeps track of the last record
processed and resumes processing from that point when re-enabled.
To manage the event source conﬁguration later, choose the trigger in the designer.

Execution Role Permissions
Lambda needs the following permissions to manage resources related to your DynamoDB Streams
stream. Add them to your function's execution role (p. 222).
• dynamodb:DescribeStream
• dynamodb:GetRecords
• dynamodb:GetShardIterator
• dynamodb:ListStreams
The AWSLambdaDynamoDBExecutionRole managed policy includes these permissions. For more
information, see AWS Lambda Execution Role (p. 222).

152

AWS Lambda Developer Guide
Tutorial

Tutorial: Using AWS Lambda with Amazon
DynamoDB Streams
In this tutorial, you create a Lambda function to consume events from an Amazon DynamoDB stream.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.

Open the roles page in the IAM console.

2.

Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – Lambda.
• Permissions – AWSLambdaDynamoDBExecutionRole.
• Role name – lambda-dynamodb-role.

The AWSLambdaDynamoDBExecutionRole has the permissions that the function needs to read items
from DynamoDB and write logs to CloudWatch Logs.

Create the Function
The following example code receives a DynamoDB event input and processes the messages that it
contains. For illustration, the code writes some of the incoming event data to CloudWatch Logs.

Note

For sample code in other languages, see Sample Function Code (p. 157).

Example index.js
console.log('Loading function');
exports.handler = function(event, context, callback) {

153

AWS Lambda Developer Guide
Tutorial

};

console.log(JSON.stringify(event, null, 2));
event.Records.forEach(function(record) {
console.log(record.eventID);
console.log(record.eventName);
console.log('DynamoDB Record: %j', record.dynamodb);
});
callback(null, "message");

To create the function
1.
2.

Copy the sample code into a ﬁle named index.js.
Create a deployment package.
$ zip function.zip index.js

3.

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name ProcessDynamoDBRecords \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 \
--role arn:aws:iam::123456789012:role/lambda-dynamodb-role

Test the Lambda Function
In this step, you invoke your Lambda function manually using the invoke AWS Lambda CLI command
and the following sample DynamoDB event.

Example input.txt
{

"Records":[
{
"eventID":"1",
"eventName":"INSERT",
"eventVersion":"1.0",
"eventSource":"aws:dynamodb",
"awsRegion":"us-east-1",
"dynamodb":{
"Keys":{
"Id":{
"N":"101"
}
},
"NewImage":{
"Message":{
"S":"New item!"
},
"Id":{
"N":"101"
}
},
"SequenceNumber":"111",
"SizeBytes":26,
"StreamViewType":"NEW_AND_OLD_IMAGES"
},
"eventSourceARN":"stream-ARN"
},
{
"eventID":"2",
"eventName":"MODIFY",

154

AWS Lambda Developer Guide
Tutorial

},
{

}

]

}

"eventVersion":"1.0",
"eventSource":"aws:dynamodb",
"awsRegion":"us-east-1",
"dynamodb":{
"Keys":{
"Id":{
"N":"101"
}
},
"NewImage":{
"Message":{
"S":"This item has changed"
},
"Id":{
"N":"101"
}
},
"OldImage":{
"Message":{
"S":"New item!"
},
"Id":{
"N":"101"
}
},
"SequenceNumber":"222",
"SizeBytes":59,
"StreamViewType":"NEW_AND_OLD_IMAGES"
},
"eventSourceARN":"stream-ARN"
"eventID":"3",
"eventName":"REMOVE",
"eventVersion":"1.0",
"eventSource":"aws:dynamodb",
"awsRegion":"us-east-1",
"dynamodb":{
"Keys":{
"Id":{
"N":"101"
}
},
"OldImage":{
"Message":{
"S":"This item has changed"
},
"Id":{
"N":"101"
}
},
"SequenceNumber":"333",
"SizeBytes":38,
"StreamViewType":"NEW_AND_OLD_IMAGES"
},
"eventSourceARN":"stream-ARN"

Execute the following invoke command.
$ aws lambda invoke --function-name ProcessDynamoDBRecords --payload file://input.txt
outputfile.txt

155

AWS Lambda Developer Guide
Tutorial

The function returns the string message (message in the context.succeed() in the code) in the
response body.
Verify the output in the outputfile.txt ﬁle.

Create a DynamoDB Table with a Stream Enabled
Create an Amazon DynamoDB table with a stream enabled.

To create a DynamoDB table
1.

Open the DynamoDB console.

2.

Choose Create table.

3.

Create a table with the following settings.
• Table name – lambda-dynamodb-stream
• Primary key – id (string)

4.

Choose Create.

To enable streams
1.

Open the DynamoDB console.

2.

Choose Tables.

3.

Choose the lambda-dynamodb-stream table.

4.

Under Overview, choose Manage stream.

5.

Choose Enable.

Write down the stream ARN. You need this in the next step when you associate the stream with
your Lambda function. For more information on enabling streams, see Capturing Table Activity with
DynamoDB Streams.

Add an Event Source in AWS Lambda
Create an event source mapping in AWS Lambda. This event source mapping associates the DynamoDB
stream with your Lambda function. After you create this event source mapping, AWS Lambda starts
polling the stream.
Run the following AWS CLI create-event-source-mapping command. After the command executes,
note down the UUID. You'll need this UUID to refer to the event source mapping in any commands, for
example, when deleting the event source mapping.
$ aws lambda create-event-source-mapping --function-name ProcessDynamoDBRecords \
--batch-size 100 --starting-position LATEST --event-source DynamoDB-stream-arn

This creates a mapping between the speciﬁed DynamoDB stream and the Lambda function. You can
associate a DynamoDB stream with multiple Lambda functions, and associate the same Lambda function
with multiple streams. However, the Lambda functions will share the read throughput for the stream
they share.
You can get the list of event source mappings by running the following command.
$ aws lambda list-event-source-mappings

156

AWS Lambda Developer Guide
Sample Code

The list returns all of the event source mappings you created, and for each mapping it shows the
LastProcessingResult, among other things. This ﬁeld is used to provide an informative message if
there are any problems. Values such as No records processed (indicates that AWS Lambda has not
started polling or that there are no records in the stream) and OK (indicates AWS Lambda successfully
read records from the stream and invoked your Lambda function) indicate that there no issues. If there
are issues, you receive an error message.
If you have a lot of event source mappings, use the function name parameter to narrow down the results.
$ aws lambda list-event-source-mappings --function-name ProcessDynamoDBRecords

Test the Setup
Test the end-to-end experience. As you perform table updates, DynamoDB writes event records to the
stream. As AWS Lambda polls the stream, it detects new records in the stream and executes your Lambda
function on your behalf by passing events to the function.
1. In the DynamoDB console, add, update, delete items to the table. DynamoDB writes records of these
actions to the stream.
2. AWS Lambda polls the stream and when it detects updates to the stream, it invokes your Lambda
function by passing in the event data it ﬁnds in the stream.
3. Your function executes and creates logs in Amazon CloudWatch. You can verify the logs reported in
the Amazon CloudWatch console.

Sample Function Code
Sample code is available for the following languages.
Topics
• Node.js (p. 157)
• Java 8 (p. 158)
• C# (p. 158)
• Python 3 (p. 159)
• Go (p. 159)

Node.js
The following example processes messages from DynamoDB, and logs their contents.

Example ProcessDynamoDBStream.js
console.log('Loading function');
exports.lambda_handler = function(event, context, callback) {
console.log(JSON.stringify(event, null, 2));
event.Records.forEach(function(record) {
console.log(record.eventID);
console.log(record.eventName);
console.log('DynamoDB Record: %j', record.dynamodb);
});
callback(null, "message");
};

157

AWS Lambda Developer Guide
Sample Code

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Node.js (p. 250).

Java 8
The following example processes messages from DynamoDB, and logs their contents. handleRequest
is the handler that AWS Lambda invokes and provides event data. The handler uses the predeﬁned
DynamodbEvent class, which is deﬁned in the aws-lambda-java-events library.

Example DDBEventProcessor.java
package example;
import
import
import
import
import

com.amazonaws.services.lambda.runtime.Context;
com.amazonaws.services.lambda.runtime.LambdaLogger;
com.amazonaws.services.lambda.runtime.RequestHandler;
com.amazonaws.services.lambda.runtime.events.DynamodbEvent;
com.amazonaws.services.lambda.runtime.events.DynamodbEvent.DynamodbStreamRecord;

public class DDBEventProcessor implements
RequestHandler {
public String handleRequest(DynamodbEvent ddbEvent, Context context) {
for (DynamodbStreamRecord record : ddbEvent.getRecords()){
System.out.println(record.getEventID());
System.out.println(record.getEventName());
System.out.println(record.getDynamodb().toString());

}

}

}
return "Successfully processed " + ddbEvent.getRecords().size() + " records.";

If the handler returns normally without exceptions, Lambda considers the input batch of records as
processed successfully and begins reading new records in the stream. If the handler throws an exception,
Lambda considers the input batch of records as not processed and invokes the function with the same
batch of records again.

Dependencies
• aws-lambda-java-core
• aws-lambda-java-events
Build the code with the Lambda library dependencies to create a deployment package. For instructions,
see AWS Lambda Deployment Package in Java (p. 276).

C#
The following example processes messages from DynamoDB, and logs their contents.
ProcessDynamoEvent is the handler that AWS Lambda invokes and provides event data. The handler
uses the predeﬁned DynamoDbEvent class, which is deﬁned in the Amazon.Lambda.DynamoDBEvents
library.

Example ProcessingDynamoDBStreams.cs
using
using
using
using

System;
System.IO;
System.Text;
Amazon.Lambda.Core;

158

AWS Lambda Developer Guide
Sample Code
using Amazon.Lambda.DynamoDBEvents;
using Amazon.Lambda.Serialization.Json;
namespace DynamoDBStreams
{
public class DdbSample
{
private static readonly JsonSerializer _jsonSerializer = new JsonSerializer();
public void ProcessDynamoEvent(DynamoDBEvent dynamoEvent)
{
Console.WriteLine($"Beginning to process {dynamoEvent.Records.Count}
records...");
foreach (var record in dynamoEvent.Records)
{
Console.WriteLine($"Event ID: {record.EventID}");
Console.WriteLine($"Event Name: {record.EventName}");

}
}

}

}

string streamRecordJson = SerializeObject(record.Dynamodb);
Console.WriteLine($"DynamoDB Record:");
Console.WriteLine(streamRecordJson);

Console.WriteLine("Stream processing complete.");

private string SerializeObject(object streamRecord)
{
using (var ms = new MemoryStream())
{
_jsonSerializer.Serialize(streamRecord, ms);
return Encoding.UTF8.GetString(ms.ToArray());
}
}

Replace the Program.cs in a .NET Core project with the above sample. For instructions, see .NET Core
CLI (p. 317).

Python 3
The following example processes messages from DynamoDB, and logs their contents.

Example ProcessDynamoDBStream.py
from __future__ import print_function
def lambda_handler(event, context):
for record in event['Records']:
print(record['eventID'])
print(record['eventName'])
print('Successfully processed %s records.' % str(len(event['Records'])))

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Python (p. 262).

Go
The following example processes messages from DynamoDB, and logs their contents.

159

AWS Lambda Developer Guide
Sample Template

Example
import (
"strings"
"github.com/aws/aws-lambda-go/events"

)

func handleRequest(ctx context.Context, e events.DynamoDBEvent) {
for _, record := range e.Records {
fmt.Printf("Processing request data for event ID %s, type %s.\n", record.EventID,
record.EventName)

}

}

// Print new values for attributes of type String
for name, value := range record.Change.NewImage {
if value.DataType() == events.DataTypeString {
fmt.Printf("Attribute name: %s, value: %s\n", name, value.String())
}
}

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Python (p. 262).

AWS SAM Template for a DynamoDB Application
You can build this application using AWS SAM. To learn more about creating AWS SAM templates, see
AWS SAM Template Basics in the AWS Serverless Application Model Developer Guide.
Below is a sample AWS SAM template for the tutorial application (p. 153). Copy the text below to
a .yaml ﬁle and save it next to the ZIP package you created previously. Note that the Handler and
Runtime parameter values should match the ones you used when you created the function in the
previous section.

Example template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
ProcessDynamoDBStream:
Type: AWS::Serverless::Function
Properties:
Handler: handler
Runtime: runtime
Policies: AWSLambdaDynamoDBExecutionRole
Events:
Stream:
Type: DynamoDB
Properties:
Stream: !GetAtt DynamoDBTable.StreamArn
BatchSize: 100
StartingPosition: TRIM_HORIZON
DynamoDBTable:
Type: AWS::DynamoDB::Table
Properties:
AttributeDefinitions:
- AttributeName: id
AttributeType: S
KeySchema:

160

AWS Lambda Developer Guide
AWS CloudTrail
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
StreamSpecification:
StreamViewType: NEW_IMAGE

For information on how to package and deploy your serverless application using the package and deploy
commands, see Deploying Serverless Applications in the AWS Serverless Application Model Developer
Guide.

Using AWS Lambda with AWS CloudTrail
AWS CloudTrail is a service that provides a record of actions taken by a user, role, or an AWS service.
CloudTrail captures API calls as events. For an ongoing record of events in your AWS account, you create
a trail. A trail enables CloudTrail to deliver log ﬁles of events to an Amazon S3 bucket.
You can take advantage of Amazon S3's bucket notiﬁcation feature and direct Amazon S3 to publish
object-created events to AWS Lambda. Whenever CloudTrail writes logs to your S3 bucket, Amazon S3
can then invoke your Lambda function by passing the Amazon S3 object-created event as a parameter.
The S3 event provides information, including the bucket name and key name of the log object that
CloudTrail created. Your Lambda function code can read the log object and process the access records
logged by CloudTrail. For example, you might write Lambda function code to notify you if speciﬁc API
call was made in your account.
In this scenario, CloudTrail writes access logs to your S3 bucket. As for AWS Lambda, Amazon S3 is the
event source so Amazon S3 publishes events to AWS Lambda and invokes your Lambda function.
For detailed information about how to conﬁgure Amazon S3 as the event source, see Using AWS Lambda
with Amazon S3 (p. 114).
The following diagram summarizes the ﬂow:

1. AWS CloudTrail saves logs to an S3 bucket (object-created event).
2. Amazon S3 detects the object-created event.
3. Amazon S3 publishes the s3:ObjectCreated:* event to AWS Lambda by invoking the Lambda
function, as speciﬁed in the bucket notiﬁcation conﬁguration. Because the Lambda function's access

161

AWS Lambda Developer Guide
Tutorial

permissions policy includes permissions for Amazon S3 to invoke the function, Amazon S3 can invoke
the function.
4. AWS Lambda executes the Lambda function by assuming the execution role that you speciﬁed at the
time you created the Lambda function.
5. The Lambda function reads the Amazon S3 event it receives as a parameter, determines where the
CloudTrail object is, reads the CloudTrail object, and then it processes the log records in the CloudTrail
object.
6. If the log includes a record with speciﬁc eventType and eventSource values, it publishes the
event to your Amazon SNS topic. In Tutorial: Using AWS Lambda with AWS CloudTrail (p. 162), you
subscribe to the SNS topic using the email protocol, so you get email notiﬁcations.
Topics
• Tutorial: Using AWS Lambda with AWS CloudTrail (p. 162)
• Sample Function Code (p. 166)

Tutorial: Using AWS Lambda with AWS CloudTrail
In this scenario, AWS CloudTrail will maintain records (logs) of AWS API calls made on your account and
notify you anytime an API call is made to create an SNS topic. As API calls are made in your account,
CloudTrail writes logs to an Amazon S3 bucket that you conﬁgured. In this scenario, you want Amazon
S3 to publish the object-created events to AWS Lambda and invoke your Lambda function as CloudTrail
creates log objects.
When Amazon S3 invokes your Lambda function, it passes an S3 event identifying, among other things,
the bucket name and key name of the object that CloudTrail created. Your Lambda function can read the
log object, and it knows the API calls that were reported in the log.
Each object CloudTrail creates in your S3 bucket is a JSON object, with one or more event records. Each
record, among other things, provides eventSource and eventName.
{

"Records":[
{

},
{

}

"eventVersion":"1.02",
"userIdentity":{
...
},
"eventTime":"2014-12-16T19:17:43Z",
"eventSource":"sns.amazonaws.com",
"eventName":"CreateTopic",
"awsRegion":"us-west-2",
"sourceIPAddress":"72.21.198.64",
...
...

},
...

For illustration, the Lambda function notiﬁes you by email if an API call to create an Amazon SNS topic
is reported in the log. That is, when your Lambda function parses the log, it looks for records with the
following:
• eventSource = "sns.amazonaws.com"

162

AWS Lambda Developer Guide
Tutorial

• eventName = "CreateTopic"
If found, it publishes the event to your Amazon SNS topic (you conﬁgure this topic to notify you by
email).
Your Lambda function uses an S3 event that provides the bucket name and key name of the object
CloudTrail created. Your Lambda function then reads that object to process CloudTrail records.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Turn on CloudTrail
In the AWS CloudTrail console, turn on the trail in your account by specifying examplebucket in
the us-west-2 region for CloudTrail to save logs. When conﬁguring the trail, do not enable SNS
notiﬁcations.
For instructions, see Creating and Updating Your Trail in the AWS CloudTrail User Guide.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.

Open the roles page in the IAM console.

2.

Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – AWS Lambda.
• Role name – lambda-cloudtrail-role.
• Permissions – Custom policy.
{

"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:*"

163

AWS Lambda Developer Guide
Tutorial
],
"Resource": "arn:aws:logs:*:*:*"

},
{

"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::examplebucket/*"

},
{

}

]

}

"Effect": "Allow",
"Action": [
"sns:Publish"
],
"Resource": "your sns topic ARN"

The policy has the permissions that the function needs to read items from Amazon S3 and write logs to
CloudWatch Logs.

Create the Function
The following example processes CloudTrail logs, and sends a notiﬁcation when an Amazon SNS topic
was created.

Example index.js
var aws = require('aws-sdk');
var zlib = require('zlib');
var async = require('async');
var
var
var
var

EVENT_SOURCE_TO_TRACK
EVENT_NAME_TO_TRACK
DEFAULT_SNS_REGION =
SNS_TOPIC_ARN
=

= /sns.amazonaws.com/;
= /CreateTopic/;
'us-west-2';
'The ARN of your SNS topic';

var s3 = new aws.S3();
var sns = new aws.SNS({
apiVersion: '2010-03-31',
region: DEFAULT_SNS_REGION
});
exports.handler = function(event, context, callback) {
var srcBucket = event.Records[0].s3.bucket.name;
var srcKey = event.Records[0].s3.object.key;
async.waterfall([
function fetchLogFromS3(next){
console.log('Fetching compressed log from S3...');
s3.getObject({
Bucket: srcBucket,
Key: srcKey
},
next);
},
function uncompressLog(response, next){
console.log("Uncompressing log...");
zlib.gunzip(response.Body, next);
},

164

AWS Lambda Developer Guide
Tutorial
function publishNotifications(jsonBuffer, next) {
console.log('Filtering log...');
var json = jsonBuffer.toString();
console.log('CloudTrail JSON from S3:', json);
var records;
try {
records = JSON.parse(json);
} catch (err) {
next('Unable to parse CloudTrail JSON: ' + err);
return;
}
var matchingRecords = records
.Records
.filter(function(record) {
return record.eventSource.match(EVENT_SOURCE_TO_TRACK)
&& record.eventName.match(EVENT_NAME_TO_TRACK);
});
console.log('Publishing ' + matchingRecords.length + ' notification(s) in
parallel...');
async.each(
matchingRecords,
function(record, publishComplete) {
console.log('Publishing notification: ', record);
sns.publish({
Message:
'Alert... SNS topic created: \n TopicARN=' +
record.responseElements.topicArn + '\n\n' +
JSON.stringify(record),
TopicArn: SNS_TOPIC_ARN
}, publishComplete);
},
next
);
}
], function (err) {
if (err) {
console.error('Failed to publish notifications: ', err);
} else {
console.log('Successfully published all notifications.');
}
callback(null,"message");
});
};

To create the function
1.

Copy the sample code into a ﬁle named index.js in a folder named lambda-cloudtrail.

2.

Install async with npm.
~/lambda-cloudtrail$ npm install async

3.

Create a deployment package.
~/lambda-cloudtrail$ zip -r function.zip .

4.

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name CloudTrailEventProcessing \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 --timeout
10 --memory-size 1024 \
--role arn:aws:iam::123456789012:role/lambda-cloudtrail-role

165

AWS Lambda Developer Guide
Sample Code

Add Permissions to the Function Policy
Add permissions to the Lambda function's resource policy to allow Amazon S3 to invoke the function.
1.

Run the following add-permission command to grant Amazon S3 service principal
(s3.amazonaws.com) permissions to perform the lambda:InvokeFunction action. Note that
permission is granted to Amazon S3 to invoke the function only if the following conditions are met:
• An object-created event is detected on a speciﬁc bucket.
• The bucket is owned by a speciﬁc AWS account. If a bucket owner deletes a bucket, some other
AWS account can create a bucket with the same name. This condition ensures that only a speciﬁc
AWS account can invoke your Lambda function.

$ aws lambda add-permission --function-name CloudTrailEventProcessing \
--statement-id Id-1 --action "lambda:InvokeFunction" --principal s3.amazonaws.com \
--source-arn arn:aws:s3:::examplebucket \
--source-account examplebucket-owner-account-id

2.

Verify the function's access policy with the get-policy command.
$ aws lambda get-policy --function-name function-name

Conﬁgure Notiﬁcation on the Bucket
Add notiﬁcation conﬁguration on the examplebucket to request Amazon S3 to publish object-created
events to Lambda. In the conﬁguration, you specify the following:
• Event type – Any event types that create objects.
• Lambda function ARN – This is your Lambda function that you want Amazon S3 to invoke.
arn:aws:lambda:us-west-2:123456789012:function:CloudTrailEventProcessing

For instructions on adding notiﬁcation conﬁguration to a bucket, see Enabling Event Notiﬁcations in the
Amazon Simple Storage Service Console User Guide.

Test the Setup
Now you can test the setup as follows:
1. Create an Amazon SNS topic.
2. AWS CloudTrail creates a log object in your bucket.
3. Amazon S3 invokes your Lambda function by passing in the log object's location as event data.
4. Lambda executes your function. The function retrieves the log, ﬁnds a CreateTopic event, and sends
a notiﬁcation.

Sample Function Code
Sample code is available for the following languages.
Topics
166

AWS Lambda Developer Guide
Sample Code

• Node.js (p. 167)

Node.js
The following example processes CloudTrail logs, and sends a notiﬁcation when an Amazon SNS topic
was created.

Example index.js
var aws = require('aws-sdk');
var zlib = require('zlib');
var async = require('async');
var
var
var
var

EVENT_SOURCE_TO_TRACK
EVENT_NAME_TO_TRACK
DEFAULT_SNS_REGION =
SNS_TOPIC_ARN
=

= /sns.amazonaws.com/;
= /CreateTopic/;
'us-west-2';
'The ARN of your SNS topic';

var s3 = new aws.S3();
var sns = new aws.SNS({
apiVersion: '2010-03-31',
region: DEFAULT_SNS_REGION
});
exports.handler = function(event, context, callback) {
var srcBucket = event.Records[0].s3.bucket.name;
var srcKey = event.Records[0].s3.object.key;
async.waterfall([
function fetchLogFromS3(next){
console.log('Fetching compressed log from S3...');
s3.getObject({
Bucket: srcBucket,
Key: srcKey
},
next);
},
function uncompressLog(response, next){
console.log("Uncompressing log...");
zlib.gunzip(response.Body, next);
},
function publishNotifications(jsonBuffer, next) {
console.log('Filtering log...');
var json = jsonBuffer.toString();
console.log('CloudTrail JSON from S3:', json);
var records;
try {
records = JSON.parse(json);
} catch (err) {
next('Unable to parse CloudTrail JSON: ' + err);
return;
}
var matchingRecords = records
.Records
.filter(function(record) {
return record.eventSource.match(EVENT_SOURCE_TO_TRACK)
&& record.eventName.match(EVENT_NAME_TO_TRACK);
});
console.log('Publishing ' + matchingRecords.length + ' notification(s) in
parallel...');
async.each(
matchingRecords,

167

AWS Lambda Developer Guide
Amazon SNS
function(record, publishComplete) {
console.log('Publishing notification: ', record);
sns.publish({
Message:
'Alert... SNS topic created: \n TopicARN=' +
record.responseElements.topicArn + '\n\n' +
JSON.stringify(record),
TopicArn: SNS_TOPIC_ARN
}, publishComplete);
},
next
);
}
], function (err) {
if (err) {
console.error('Failed to publish notifications: ', err);
} else {
console.log('Successfully published all notifications.');
}
callback(null,"message");
});
};

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Node.js (p. 250).

Using AWS Lambda with Amazon SNS from
Diﬀerent Accounts
In order to perform cross account Amazon SNS deliveries to Lambda, you need to authorize your Lambda
function to be invoked from Amazon SNS. In turn, Amazon SNS needs to allow the Lambda account
to subscribe to the Amazon SNS topic. For example, if the Amazon SNS topic is in account A and the
Lambda function is in account B, both accounts must grant permissions to the other to access their
respective resources. Since not all the options for setting up cross-account permissions are available from
the AWS console, you use the AWS CLI to set up the entire process.
Topics
• Tutorial: Using AWS Lambda with Amazon Simple Notiﬁcation Service (p. 168)
• Sample Function Code (p. 171)

Tutorial: Using AWS Lambda with Amazon Simple
Notiﬁcation Service
You can use a Lambda function in one AWS account to subscribe to an Amazon SNS topic in a separate
AWS account. In this tutorial, you use the AWS Command Line Interface to perform AWS Lambda
operations such as creating a Lambda function, creating an Amazon SNS topic and granting permissions
to allow these two resources to access each other.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.

168

AWS Lambda Developer Guide
Tutorial

To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.
In the tutorial, you use two accounts. The AWS CLI commands illustrate this by using two named proﬁles,
each conﬁgured for use with a diﬀerent account. If you use proﬁles with diﬀerent names, or the default
proﬁle and one named proﬁle, modify the commands as needed.

Create an Amazon SNS Topic
From account A, create the source Amazon SNS topic.
$ aws sns create-topic --name lambda-x-account --profile accountA

Note the topic ARN that is returned by the command. You will need it when you add permissions to the
Lambda function to subscribe to the topic.

Create the Execution Role
From account B, create the execution role (p. 222) that gives your function permission to access AWS
resources.

To create an execution role
1.
2.

Open the roles page in the IAM console.
Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – AWS Lambda.
• Permissions – AWSLambdaBasicExecutionRole.
• Role name – lambda-sns-role.

The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write logs to
CloudWatch Logs.

Create a Lambda Function
From account B, create the function that processes events from Amazon SNS. The following example
code receives an Amazon SNS event input and processes the messages that it contains. For illustration,
the code writes some of the incoming event data to CloudWatch Logs.

Note

For sample code in other languages, see Sample Function Code (p. 171).

Example index.js
console.log('Loading function');

169

AWS Lambda Developer Guide
Tutorial
exports.handler = function(event, context, callback) {
// console.log('Received event:', JSON.stringify(event, null, 4));

};

var message = event.Records[0].Sns.Message;
console.log('Message received from SNS:', message);
callback(null, "Success");

To create the function
1.

Copy the sample code into a ﬁle named index.js.

2.

Create a deployment package.
$ zip function.zip index.js

3.

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name SNS-X-Account \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 \
--role arn:aws:iam::01234567891B:role/service-role/lambda-sns-execution-role \
--timeout 60 --profile accountB

Note the function ARN that is returned by the command. You will need it when you add permissions to
allow Amazon SNS to invoke your function.

Set Up Cross-Account Permissions
From account A, grant permission to account B to subscribe to the topic:
$ aws sns add-permission --label lambda-access --aws-account-id 12345678901B \
--topic-arn arn:aws:sns:us-east-2:12345678901A:lambda-x-account \
--action-name Subscribe ListSubscriptionsByTopic Receive --profile accountA

From account B, add the Lambda permission to allow invocation from Amazon SNS.
$ aws lambda add-permission --function-name SNS-X-Account \
--source-arn arn:aws:sns:us-east-2:12345678901A:lambda-x-account \
--statement-id sns-x-account --action "lambda:InvokeFunction" \
--principal sns.amazonaws.com --profile accountB
{
"Statement": "{\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:lambda:useast-2:12345678901B:function:SNS-X-Account\"}},\"Action\":[\"lambda:InvokeFunction\"],
\"Resource\":\"arn:aws:lambda:us-east-2:01234567891A:function:SNS-X-Account\",\"Effect\":
\"Allow\",\"Principal\":{\"Service\":\"sns.amazonaws.com\"},\"Sid\":\"sns-x-account1\"}"
}

Do not use the --source-account parameter to add a source account to the Lambda policy when
adding the policy. Source account is not supported for Amazon SNS event sources and will result in
access being denied.

Create a Subscription
From account B, subscribe the Lambda function to the topic. When a message is sent to the lambda-xaccount topic in account A, Amazon SNS invokes the SNS-X-Account function in account B.
$ aws sns subscribe --protocol lambda \

170

AWS Lambda Developer Guide
Sample Code
--topic-arn arn:aws:sns:us-east-2:12345678901A:lambda-x-account \
--notification-endpoint arn:aws:lambda:us-east-2:12345678901B:function:SNS-X-Account \
--profile accountB
{
"SubscriptionArn": "arn:aws:sns:us-east-2:12345678901A:lambda-xaccount:5d906xxxx-7c8x-45dx-a9dx-0484e31c98xx"
}

The output contains the ARN of the topic subscription.

Test Subscription
From account A, test the subscription. Type Hello World into a text ﬁle and save it as message.txt.
Then run the following command:
$ aws sns publish --message file://message.txt --subject Test \
--topic-arn arn:aws:sns:us-east-2:12345678901A:lambda-x-account \
--profile accountA

This will return a message id with a unique identiﬁer, indicating the message has been accepted by the
Amazon SNS service. Amazon SNS will then attempt to deliver it to the topic's subscribers. Alternatively,
you could supply a JSON string directly to the message parameter, but using a text ﬁle allows for line
breaks in the message.
To learn more about Amazon SNS, see What is Amazon Simple Notiﬁcation Service.

Sample Function Code
Sample code is available for the following languages.
Topics
• Node.js 8 (p. 171)
• Java 8 (p. 172)
• Go (p. 172)
• Python 3 (p. 173)

Node.js 8
The following example processes messages from Amazon SNS, and logs their contents.

Example index.js
console.log('Loading function');
exports.handler = function(event, context, callback) {
// console.log('Received event:', JSON.stringify(event, null, 4));

};

var message = event.Records[0].Sns.Message;
console.log('Message received from SNS:', message);
callback(null, "Success");

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Node.js (p. 250).

171

AWS Lambda Developer Guide
Sample Code

Java 8
The following example processes messages from Amazon SNS, and logs their contents.

Example LambdaWithSNS.java
package example;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.SNSEvent;
public class LogEvent implements RequestHandler {
public Object handleRequest(SNSEvent request, Context context){
String timeStamp = new SimpleDateFormat("yyyy-MMdd_HH:mm:ss").format(Calendar.getInstance().getTime());
context.getLogger().log("Invocation started: " + timeStamp);
context.getLogger().log(request.getRecords().get(0).getSNS().getMessage());
timeStamp = new SimpleDateFormat("yyyy-MMdd_HH:mm:ss").format(Calendar.getInstance().getTime());
context.getLogger().log("Invocation completed: " + timeStamp);
return null;
}
}

Dependencies
• aws-lambda-java-core
• aws-lambda-java-events
Build the code with the Lambda library dependencies to create a deployment package. For instructions,
see AWS Lambda Deployment Package in Java (p. 276).

Go
The following example processes messages from Amazon SNS, and logs their contents.

Example lambda_handler.go
package main
import (
"context"
"fmt"
"github.com/aws/aws-lambda-go/lambda"
"github.com/aws/aws-lambda-go/events"
)
func handler(ctx context.Context, snsEvent events.SNSEvent) {
for _, record := range snsEvent.Records {
snsRecord := record.SNS
fmt.Printf("[%s %s] Message = %s \n", record.EventSource, snsRecord.Timestamp,
snsRecord.Message)
}
}

172

AWS Lambda Developer Guide
Amazon API Gateway
func main() {
lambda.Start(handler)
}

Build the executable with go build and create a deployment package. For instructions, see AWS
Lambda Deployment Package in Go (p. 304).

Python 3
The following example processes messages from Amazon SNS, and logs their contents.

Example lambda_handler.py
from __future__ import print_function
import json
print('Loading function')
def lambda_handler(event, context):
#print("Received event: " + json.dumps(event, indent=2))
message = event['Records'][0]['Sns']['Message']
print("From SNS: " + message)
return message

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Python (p. 262).

Using AWS Lambda with Amazon API Gateway
You can invoke AWS Lambda functions over HTTPS. You can do this by deﬁning a custom REST API and
endpoint using Amazon API Gateway, and then mapping individual methods, such as GET and PUT,
to speciﬁc Lambda functions. Alternatively, you could add a special method named ANY to map all
supported methods (GET, POST, PATCH, DELETE) to your Lambda function. When you send an HTTPS
request to the API endpoint, the Amazon API Gateway service invokes the corresponding Lambda
function. For more information about the ANY method, see Create a Simple Microservice using Lambda
and API Gateway (p. 185).
Amazon API Gateway also adds a layer between your application users and your app logic that enables
the following:
• Ability to throttle individual users or requests.
• Protect against Distributed Denial of Service attacks.
• Provide a caching layer to cache response from your Lambda function.
Note the following about how the Amazon API Gateway and AWS Lambda integration works:
• Push-event model – This is a model (see AWS Lambda Event Source Mapping (p. 64)), where Amazon
API Gateway invokes the Lambda function by passing data in the request body as parameter to the
Lambda function.
• Synchronous invocation – The Amazon API Gateway can invoke the Lambda function and get a
response back in real time by specifying RequestResponse as the invocation type. For information
about invocation types, see Invocation Types (p. 63).
• Event structure – The event your Lambda function receives is the body from the HTTPS request that
Amazon API Gateway receives and your Lambda function is the custom code written to process the
speciﬁc event type.

173

AWS Lambda Developer Guide
Tutorial

Note that there are two types of permissions policies that you work with when you set up the end-to-end
experience:
• Permissions for your Lambda function – Regardless of what invokes a Lambda function, AWS Lambda
executes the function by assuming the IAM role (execution role) that you specify at the time you
create the Lambda function. Using the permissions policy associated with this role, you grant your
Lambda function the permissions that it needs. For example, if your Lambda function needs to read an
object, you grant permissions for the relevant Amazon S3 actions in the permissions policy. For more
information, see AWS Lambda Execution Role (p. 222).
• Permission for Amazon API Gateway to invoke your Lambda function – Amazon API Gateway cannot
invoke your Lambda function without your permission. You grant this permission via the permission
policy associated with the Lambda function.

Tutorial: Using AWS Lambda with Amazon API
Gateway
In this example you create a simple API using Amazon API Gateway. An Amazon API
Gateway is a collection of resources and methods. For this tutorial, you create one resource
(DynamoDBManager) and deﬁne one method (POST) on it. The method is backed by a Lambda function
(LambdaFunctionOverHttps). That is, when you call the API through an HTTPS endpoint, Amazon API
Gateway invokes the Lambda function.
The POST method on the DynamoDBManager resource supports the following DynamoDB operations:
• Create, update, and delete an item.
• Read an item.
• Scan an item.
• Other operations (echo, ping), not related to DynamoDB, that you can use for testing.
The request payload you send in the POST request identiﬁes the DynamoDB operation and provides
necessary data. For example:
• The following is a sample request payload for a DynamoDB create item operation:
{

}

"operation": "create",
"tableName": "lambda-apigateway",
"payload": {
"Item": {
"id": "1",
"name": "Bob"
}
}

• The following is a sample request payload for a DynamoDB read item operation:
{

"operation": "read",
"tableName": "lambda-apigateway",
"payload": {
"Key": {
"id": "1"
}
}

174

AWS Lambda Developer Guide
Tutorial
}

• The following is a sample request payload for an echo operation. You send an HTTP POST request to
the endpoint, using the following data in the request body.
{

}

"operation": "echo",
"payload": {
"somekey1": "somevalue1",
"somekey2": "somevalue2"
}

Note

API Gateway oﬀers advanced capabilities, such as:
• Pass through the entire request – A Lambda function can receive the entire HTTP request
(instead of just the request body) and set the HTTP response (instead of just the response
body) using the AWS_PROXY integration type.
• Catch-all methods – Map all methods of an API resource to a single Lambda function with a
single mapping, using the ANY catch-all method.
• Catch-all resources – Map all sub-paths of a resource to a Lambda function without any
additional conﬁguration using the new path parameter ({proxy+}).
To learn more about these API Gateway features, see Conﬁgure Proxy Integration for a Proxy
Resource.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.

Open the roles page in the IAM console.

2.

Choose Create role.

3.

Create a role with the following properties.

175

AWS Lambda Developer Guide
Tutorial

• Trusted entity – Lambda.
• Role name – lambda-apigateway-role.
• Permissions – Custom policy with permission to DynamoDB and CloudWatch Logs.
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1428341300017",
"Action": [
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:PutItem",
"dynamodb:Query",
"dynamodb:Scan",
"dynamodb:UpdateItem"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "",
"Resource": "*",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Effect": "Allow"
}
]

The custom policy has the permissions that the function needs to write data to DynamoDB and upload
logs. Note the Amazon Resource Name (ARN) of the role for later use.

Create the Function
The following example code receives a Kinesis event input and processes the messages that it contains.
For illustration, the code writes some of the incoming event data to CloudWatch Logs.

Note

For sample code in other languages, see Sample Function Code (p. 182).

Example index.js
console.log('Loading function');
var AWS = require('aws-sdk');
var dynamo = new AWS.DynamoDB.DocumentClient();
/**
* Provide an event that contains the following keys:
*
*
- operation: one of the operations in the switch statement below
*
- tableName: required for operations that interact with DynamoDB
*
- payload: a parameter to pass to the operation being performed
*/
exports.handler = function(event, context, callback) {

176

AWS Lambda Developer Guide
Tutorial
//console.log('Received event:', JSON.stringify(event, null, 2));
var operation = event.operation;
if (event.tableName) {
event.payload.TableName = event.tableName;
}

};

switch (operation) {
case 'create':
dynamo.put(event.payload, callback);
break;
case 'read':
dynamo.get(event.payload, callback);
break;
case 'update':
dynamo.update(event.payload, callback);
break;
case 'delete':
dynamo.delete(event.payload, callback);
break;
case 'list':
dynamo.scan(event.payload, callback);
break;
case 'echo':
callback(null, "Success");
break;
case 'ping':
callback(null, "pong");
break;
default:
callback('Unknown operation: ${operation}');
}

To create the function
1.

Copy the sample code into a ﬁle named index.js.

2.

Create a deployment package.
$ zip function.zip index.js

3.

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name LambdaFunctionOverHttps \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 \
--role arn:aws:iam::123456789012:role/service-role/lambda-apigateway-role

Test the Lambda Function
Invoke the function manually using the sample event data. We recommend that you invoke the function
using the console because the console UI provides a user-friendly interface for reviewing the execution
results, including the execution summary, logs written by your code, and the results returned by the
function (because the console always performs synchronous execution—invokes the Lambda function
using the RequestResponse invocation type).

To test the Lambda function
1.

Copy the following JSON into a ﬁle and save it as input.txt.

177

AWS Lambda Developer Guide
Tutorial

{

}

2.

"operation": "echo",
"payload": {
"somekey1": "somevalue1",
"somekey2": "somevalue2"
}

Execute the following invoke command:
$ aws lambda invoke --function-name LambdaFunctionOverHttps \
--payload fileb://input.txt outputfile.txt

Create an API Using Amazon API Gateway
In this step, you associate your Lambda function with a method in the API that you created using
Amazon API Gateway and test the end-to-end experience. That is, when an HTTP request is sent to an
API method, Amazon API Gateway invokes your Lambda function.
First, you create an API (DynamoDBOperations) using Amazon API Gateway with one resource
(DynamoDBManager) and one method (POST). You associate the POST method with your Lambda
function. Then, you test the end-to-end experience.

Create the API
Run the following create-rest-api command to create the DynamoDBOperations API for this
tutorial.
$ aws apigateway create-rest-api --name DynamoDBOperations
{
"id": "bs8fqo6bp0",
"name": "DynamoDBOperations",
"createdDate": 1539803980,
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"EDGE"
]
}
}

Save the API ID for use in further commands. You also need the ID of the API root resource. To get the ID,
run the get-resources command.
$ API=bs8fqo6bp0
$ aws apigateway get-resources --rest-api-id $API
{
"items": [
{
"path": "/",
"id": "e8kitthgdb"
}
]
}

At this time you only have the root resource, but you add more resources in the next step.

178

AWS Lambda Developer Guide
Tutorial

Create a Resource in the API
Run the following create-resource command to create a resource (DynamoDBManager) in the API
that you created in the preceding section.
$ aws apigateway create-resource --rest-api-id $API
--parent-id e8kitthgdb
{
"path": "/DynamoDBManager",
"pathPart": "DynamoDBManager",
"id": "resource-id",
"parentId": "e8kitthgdb"
}

--path-part DynamoDBManager \

Note the ID in the response. This is the ID of the DynamoDBManager resource that you created.

Create POST Method on the Resource
Run the following put-method command to create a POST method on the DynamoDBManager resource
in your API.
$ RESOURCE=iuig5w
$ aws apigateway put-method --rest-api-id $API --resource-id $RESOURCE \
--http-method POST --authorization-type NONE
{
"apiKeyRequired": false,
"httpMethod": "POST",
"authorizationType": "NONE"
}

We specify NONE for the --authorization-type parameter, which means that unauthenticated
requests for this method are supported. This is ﬁne for testing but in production you should use either
the key-based or role-base authentication.

Set the Lambda Function as the Destination for the POST Method
Run the following command to set the Lambda function as the integration point for the POST method.
This is the method Amazon API Gateway invokes when you make an HTTP request for the POST method
endpoint. This command and others use ARNs that include your account ID and region. Save these to
variables (you can ﬁnd your account ID in the role ARN that you used to create the function).
$ REGION=us-east-2
$ ACCOUNT=123456789012
$ aws apigateway put-integration --rest-api-id $API --resource-id $RESOURCE \
--http-method POST --type AWS --integration-http-method POST \
--uri arn:aws:apigateway:$REGION:lambda:path/2015-03-31/functions/arn:aws:lambda:$REGION:
$ACCOUNT:function:LambdaFunctionOverHttps/invocations
{
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/
arn:aws:lambda:us-east-2:123456789012:function:LambdaFunctionOverHttps/invocations",
"passthroughBehavior": "WHEN_NO_MATCH",
"timeoutInMillis": 29000,
"cacheNamespace": "iuig5w",
"cacheKeyParameters": []
}

--integration-http-method is the method that API Gateway uses to communicate with AWS
Lambda. --uri is unique identiﬁer for the endpoint to which Amazon API Gateway can send request.

179

AWS Lambda Developer Guide
Tutorial

Set content-type of the POST method response and integration response to JSON as follows:
• Run the following command to set the POST method response to JSON. This is the response type that
your API method returns.
$ aws apigateway put-method-response --rest-api-id $API \
--resource-id $RESOURCE --http-method POST \
--status-code 200 --response-models application/json=Empty
{
"statusCode": "200",
"responseModels": {
"application/json": "Empty"
}
}

• Run the following command to set the POST method integration response to JSON. This is the
response type that Lambda function returns.
$ aws apigateway put-integration-response --rest-api-id $API \
--resource-id $RESOURCE --http-method POST \
--status-code 200 --response-templates application/json=""
{
"statusCode": "200",
"responseTemplates": {
"application/json": null
}
}

Deploy the API
In this step, you deploy the API that you created to a stage called prod.
$ aws apigateway create-deployment --rest-api-id $API --stage-name prod
{
"id": "20vgsz",
"createdDate": 1539820012
}

Grant Invoke Permission to the API
Now that you have an API created using Amazon API Gateway and you've deployed it, you can test. First,
you need to add permissions so that Amazon API Gateway can invoke your Lambda function when you
send HTTP request to the POST method.
To do this, you need to add a permissions to the permissions policy associated with your Lambda
function. Run the following add-permission AWS Lambda command to grant the Amazon API
Gateway service principal (apigateway.amazonaws.com) permissions to invoke your Lambda function
(LambdaFunctionOverHttps).
$ aws lambda add-permission --function-name LambdaFunctionOverHttps \
--statement-id apigateway-test-2 --action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:$REGION:$ACCOUNT:$API/*/POST/DynamoDBManager"
{
"Statement": "{\"Sid\":\"apigateway-test-2\",\"Effect\":\"Allow\",\"Principal\":
{\"Service\":\"apigateway.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource
\":\"arn:aws:lambda:us-east-2:123456789012:function:LambdaFunctionOverHttps\",\"Condition
\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-2:123456789012:mnh1yprki7/
*/POST/DynamoDBManager\"}}}"

180

AWS Lambda Developer Guide
Tutorial
}

You must grant this permission to enable testing (if you go to the Amazon API Gateway and choose
Test to test the API method, you need this permission). Note the --source-arn speciﬁes a wildcard
character (*) as the stage value (indicates testing only). This allows you to test without deploying the API.
Now, run the same command again, but this time you grant to your deployed API permissions to invoke
the Lambda function.
$ aws lambda add-permission --function-name LambdaFunctionOverHttps \
--statement-id apigateway-prod-2 --action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:$REGION:$ACCOUNT:$API/prod/POST/DynamoDBManager"
{
"Statement": "{\"Sid\":\"apigateway-prod-2\",\"Effect\":\"Allow\",\"Principal\":
{\"Service\":\"apigateway.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource
\":\"arn:aws:lambda:us-east-2:123456789012:function:LambdaFunctionOverHttps\",\"Condition
\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-2:123456789012:mnh1yprki7/
prod/POST/DynamoDBManager\"}}}"
}

You grant this permission so that your deployed API has permissions to invoke the Lambda function.
Note that the --source-arn speciﬁes a prod which is the stage name we used when deploying the API.

Create a Amazon DynamoDB Table
Create the DynamoDB table that the Lambda function uses.

To create a DynamoDB table
1.

Open the DynamoDB console.

2.

Choose Create table.

3.

Create a table with the following settings.
• Table name – lambda-apigateway
• Primary key – id (string)

4.

Choose Create.

Trigger the Function with an HTTP Request
In this step, you are ready to send an HTTP request to the POST method endpoint. You can use either
Curl or a method (test-invoke-method) provided by Amazon API Gateway.
You can use Amazon API Gateway CLI commands to send an HTTP POST request to the resource
(DynamoDBManager) endpoint. Because you deployed your Amazon API Gateway, you can use Curl to
invoke the methods for the same operation.
The Lambda function supports using the create operation to create an item in your DynamoDB table.
To request this operation, use the following JSON:

Example create-item.json
{

"operation": "create",

181

AWS Lambda Developer Guide
Sample Code

}

"tableName": "lambda-apigateway",
"payload": {
"Item": {
"id": "1234ABCD",
"number": 5
}
}

Save the test input to a ﬁle named create-item.json. Run the test-invoke-method Amazon
API Gateway command to send an HTTP POST method request to the resource (DynamoDBManager)
endpoint.
$ aws apigateway test-invoke-method --rest-api-id $API \
--resource-id $RESOURCE --http-method POST --path-with-query-string "" \
--body file://create-item.json

Or, you can use the following Curl command:
$ curl -X POST -d "{\"operation\":\"create\",\"tableName\":\"lambda-apigateway\",
\"payload\":{\"Item\":{\"id\":\"1\",\"name\":\"Bob\"}}}" https://$API.execute-api.
$REGION.amazonaws.com/prod/DynamoDBManager

To send request for the echo operation that your Lambda function supports, you can use the following
request payload:

Example echo.json
{

}

"operation": "echo",
"payload": {
"somekey1": "somevalue1",
"somekey2": "somevalue2"
}

Save the test input to a ﬁle named echo.json. Run the test-invoke-method Amazon API Gateway
CLI command to send an HTTP POST method request to the resource (DynamoDBManager) endpoint
using the preceding JSON in the request body.
$ aws apigateway test-invoke-method --rest-api-id $API \
--resource-id $RESOURCE --http-method POST --path-with-query-string "" \
--body file://echo.json

Or, you can use the following Curl command:
$ curl -X POST -d "{\"operation\":\"echo\",\"payload\":{\"somekey1\":\"somevalue1\",
\"somekey2\":\"somevalue2\"}}" https://$API.execute-api.$REGION.amazonaws.com/prod/
DynamoDBManager

Sample Function Code
Sample code is available for the following languages.
Topics

182

AWS Lambda Developer Guide
Sample Code

• Node.js (p. 183)
• Python 3 (p. 184)
• Go (p. 184)

Node.js
The following example processes messages from API Gateway, and manages DynamoDB documents
based on the request method.

Example index.js
console.log('Loading function');
var AWS = require('aws-sdk');
var dynamo = new AWS.DynamoDB.DocumentClient();
/**
* Provide an event that contains the following keys:
*
*
- operation: one of the operations in the switch statement below
*
- tableName: required for operations that interact with DynamoDB
*
- payload: a parameter to pass to the operation being performed
*/
exports.handler = function(event, context, callback) {
//console.log('Received event:', JSON.stringify(event, null, 2));
var operation = event.operation;
if (event.tableName) {
event.payload.TableName = event.tableName;
}

};

switch (operation) {
case 'create':
dynamo.put(event.payload, callback);
break;
case 'read':
dynamo.get(event.payload, callback);
break;
case 'update':
dynamo.update(event.payload, callback);
break;
case 'delete':
dynamo.delete(event.payload, callback);
break;
case 'list':
dynamo.scan(event.payload, callback);
break;
case 'echo':
callback(null, "Success");
break;
case 'ping':
callback(null, "pong");
break;
default:
callback('Unknown operation: ${operation}');
}

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Node.js (p. 250).

183

AWS Lambda Developer Guide
Sample Code

Python 3
The following example processes messages from API Gateway, and manages DynamoDB documents
based on the request method.

Example LambdaFunctionOverHttps.py
from __future__ import print_function
import boto3
import json
print('Loading function')
def handler(event, context):
'''Provide an event that contains the following keys:
- operation: one of the operations in the operations dict below
- tableName: required for operations that interact with DynamoDB
- payload: a parameter to pass to the operation being performed
'''
#print("Received event: " + json.dumps(event, indent=2))
operation = event['operation']
if 'tableName' in event:
dynamo = boto3.resource('dynamodb').Table(event['tableName'])
operations = {
'create': lambda x: dynamo.put_item(**x),
'read': lambda x: dynamo.get_item(**x),
'update': lambda x: dynamo.update_item(**x),
'delete': lambda x: dynamo.delete_item(**x),
'list': lambda x: dynamo.scan(**x),
'echo': lambda x: x,
'ping': lambda x: 'pong'
}
if operation in operations:
return operations[operation](event.get('payload'))
else:
raise ValueError('Unrecognized operation "{}"'.format(operation))

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Python (p. 262).

Go
The following example processes messages from API Gateway, and logs information about the request.

Example LambdaFunctionOverHttps.go
import (
"strings"
"github.com/aws/aws-lambda-go/events"
)
func handleRequest(ctx context.Context, request events.APIGatewayProxyRequest)
(events.APIGatewayProxyResponse, error) {

184

AWS Lambda Developer Guide
Microservice Blueprint
fmt.Printf("Processing request data for request %s.\n",
request.RequestContext.RequestId)
fmt.Printf("Body size = %d.\n", len(request.Body))
fmt.Println("Headers:")
for key, value := range request.Headers {
fmt.Printf("
%s: %s\n", key, value)
}
}

return events.APIGatewayProxyResponse { Body: request.Body, StatusCode: 200 }, nil

Build the executable with go build and create a deployment package. For instructions, see AWS
Lambda Deployment Package in Go (p. 304).

Create a Simple Microservice using Lambda and API
Gateway
In this tutorial you will use the Lambda console to create a Lambda function, and an Amazon API
Gateway endpoint to trigger that function. You will be able to call the endpoint with any method (GET,
POST, PATCH, etc.) to trigger your Lambda function. When the endpoint is called, the entire request will
be passed through to your Lambda function. Your function action will depend on the method you call
your endpoint with:
• DELETE: delete an item from a DynamoDB table
• GET: scan table and return all items
• POST: Create an item
• PUT: Update an item

Create an API Using Amazon API Gateway
Follow the steps in this section to create a new Lambda function and an API Gateway endpoint to trigger
it:

To create an API
1.

Sign in to the AWS Management Console and open the AWS Lambda console.

2.

Choose Create Lambda function.

3.

Choose Blueprint.

4.

Enter microservice in the search bar. Choose the microservice-http-endpoint blueprint and then
choose Conﬁgure.

5.

Conﬁgure the following settings.
• Name – lambda-microservice.
• Role – Create a new role from one or more templates.
• Role name – lambda-apigateway-role.
• Policy templates – Simple microservice permissions.
• API – Create a new API.
• Security – Open.
Choose Create function.
185

AWS Lambda Developer Guide
Sample Template

When you complete the wizard and create your function, Lambda creates a proxy resource named
lambda-microservice under the API name you selected. For more information about proxy resources,
see Conﬁgure Proxy Integration for a Proxy Resource.
A proxy resource has an AWS_PROXY integration type and a catch-all method ANY. The AWS_PROXY
integration type applies a default mapping template to pass through the entire request to the Lambda
function and transforms the output from the Lambda function to HTTP responses. The ANY method
deﬁnes the same integration setup for all the supported methods, including GET, POST, PATCH, DELETE
and others.

Test Sending an HTTPS Request
In this step, you will use the console to test the Lambda function. In addition, you can run a curl
command to test the end-to-end experience. That is, send an HTTPS request to your API method and
have Amazon API Gateway invoke your Lambda function. In order to complete the steps, make sure you
have created a DynamoDB table and named it "MyTable". For more information, see Create a DynamoDB
Table with a Stream Enabled (p. 156)

To test the API
1.

With your MyLambdaMicroService function still open in the console, choose the Actions tab and
then choose Conﬁgure test event.

2.

Replace the existing text with the following:
{

"httpMethod": "GET",
"queryStringParameters": {
"TableName": "MyTable"
}

}

3.

After entering the text above choose Save and test.

AWS SAM Template for an API Gateway Application
You can build this application using AWS SAM. To learn more about creating AWS SAM templates, see
AWS SAM Template Basics in the AWS Serverless Application Model Developer Guide.
Below is a sample AWS SAM template for the Lambda application from the tutorial (p. 174). Copy
the text below to a .yaml ﬁle and save it next to the ZIP package you created previously. Note that
the Handler and Runtime parameter values should match the ones you used when you created the
function in the previous section.

Example template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
LambdaFunctionOverHttps:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: nodejs8.10
Policies: AmazonDynamoDBFullAccess
Events:
HttpPost:
Type: Api

186

AWS Lambda Developer Guide
Android App
Properties:
Path: '/DynamoDBOperations/DynamoDBManager'
Method: post

For information on how to package and deploy your serverless application using the package and deploy
commands, see Deploying Serverless Applications in the AWS Serverless Application Model Developer
Guide.

Using AWS Lambda as an Android Mobile
Application Backend
You can use AWS Lambda to host backend logic for mobile applications. That is, some of your mobile
app code can be run as Lambda functions. This allows you to put minimal logic in the mobile application
itself making it easy to scale and update (for example, you only apply code updates to the Lambda
function, instead of having to deploy code updates in your app clients).
After you create the Lambda function, you can invoke it from your mobile app using AWS Mobile SDKs,
such as the AWS SDK for Android. For more information, see Tools for Amazon Web Services.

Note

You can also invoke your Lambda function over HTTP using Amazon API Gateway, instead of
using the AWS SDK. Amazon API Gateway adds an additional layer between your mobile users
and your app logic that enable the following:
• Ability to throttle individual users or requests.
• Protect against Distributed Denial of Service attacks.
• Provide a caching layer to cache response from your Lambda function.
For more information, see Using AWS Lambda with Amazon API Gateway (p. 173).
Note the following about how the mobile application and AWS Lambda integration works:
• Push-event model – This is a model (see AWS Lambda Event Source Mapping (p. 64)), where the app
invokes the Lambda function by passing the event data as parameter.
• Synchronous or asynchronous invocation – The app can invoke the Lambda function and get a
response back in real time by specifying RequestResponse as the invocation type (or use the Event
invocation type for asynchronous invocation). For information about invocation types, see Invocation
Types (p. 63).
• Event structure – The event your Lambda function receives is deﬁned by your application, and your
Lambda function is the custom code written to process the speciﬁc event type.
There are two types of permissions policies that you work with in setting the end-to-end experience:
• Permissions for your Lambda function – Regardless of what invokes a Lambda function, AWS Lambda
executes the function by assuming the IAM role (execution role) that you specify at the time you
create the Lambda function. Using the permissions policy associated with this role, you grant your
Lambda function the permissions that it needs. For example, if your Lambda function needs to read an
object, you grant permissions for the relevant Amazon S3 actions in the permissions policy. For more
information, see AWS Lambda Execution Role (p. 222).
• Permissions for the mobile app to invoke your Lambda function – The application must have valid
security credentials and permissions to invoke a Lambda function. For mobile applications, you can use
the Amazon Cognito service to manage user identities, authentication, and permissions.

187

AWS Lambda Developer Guide
Tutorial

The following diagram illustrates the application ﬂow (the illustration assumes a mobile app using AWS
Mobile SDK for Android to make the API calls):

1. The mobile application retrieves AWS credentials from an Amazon Cognito identity pool. The role
associated with the identitiy pool gives the application permission to use AWS Lambda.
2. The mobile application invokes the Lambda function.
3. AWS Lambda returns results to the mobile application.
Topics
• Tutorial: Using AWS Lambda as Mobile Application Backend (p. 188)
• Sample Function Code (p. 194)

Tutorial: Using AWS Lambda as Mobile Application
Backend
In this tutorial, you create a simple Android mobile application. The primary purpose of this tutorial is
to show you how to hook up various components to enable an Android mobile application to invoke a
Lambda function and process response.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.

188

AWS Lambda Developer Guide
Tutorial

On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.

Open the roles page in the IAM console.

2.

Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – AWS Lambda.
• Permissions – AWSLambdaBasicExecutionRole.
• Role name – lambda-android-role.

The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write logs to
CloudWatch Logs.

Create the Function
The following example uses data to generate a string reponse.

Note

For sample code in other languages, see Sample Function Code (p. 194).

Example index.js
exports.handler = function(event, context, callback) {
console.log("Received event: ", event);
var data = {
"greetings": "Hello, " + event.firstName + " " + event.lastName + "."
};
callback(null, data);
}

To create the function
1.

Copy the sample code into a ﬁle named index.js.

2.

Create a deployment package.
$ zip function.zip index.js

3.

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name AndroidBackendLambdaFunction \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 \
--role arn:aws:iam::123456789012:role/lambda-android-role

Test the Lambda Function
Invoke the function manually using the sample event data.
189

AWS Lambda Developer Guide
Tutorial

To test the Lambda function (AWS CLI)
1.

Save the following sample event JSON in a ﬁle, input.txt.
{

2.

"firstName": "first-name",

"lastName": "last-name" }

Execute the following invoke command:
$ aws lambda invoke --function-name AndroidBackendLambdaFunction \
--payload file://file-path/input.txt outputfile.txt

Create an Amazon Cognito Identity Pool
In this section, you create an Amazon Cognito identity pool. The identity pool has two IAM
roles. You update the IAM role for unauthenticated users and grant permissions to execute the
AndroidBackendLambdaFunction Lambda function.
For more information about IAM roles, see IAM Roles in the IAM User Guide. For more information about
Amazon Cognito services, see the Amazon Cognito product detail page.

To create an identity pool
1.

Open the Amazon Cognito console.

2.

Create a new identity pool called JavaFunctionAndroidEventHandlerPool. Before you follow
the procedure to create an identity pool, note the following:
• The identity pool you are creating must allow access to unauthenticated identities because our
example mobile application does not require a user log in. Therefore, make sure to select the
Enable access to unauthenticated identities option.
• Add the following statement to the permission policy associated with the unauthenticated
identities.
{

"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:useast-1:123456789012:function:AndroidBackendLambdaFunction"
]
}

The resulting policy will be as follows:
{

"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"mobileanalytics:PutEvents",
"cognito-sync:*"
],
"Resource":[
"*"
]

190

AWS Lambda Developer Guide
Tutorial
},
{

"Effect":"Allow",
"Action":[
"lambda:invokefunction"
],
"Resource":[
"arn:aws:lambda:us-east-1:accountid:function:AndroidBackendLambdaFunction"
]
}
]
}

3.

For instructions about how to create an identity pool, log in to the Amazon Cognito console and
follow the New Identity Pool wizard.
Note the identity pool ID. You specify this ID in your mobile application you create in the next
section. The app uses this ID when it sends request to Amazon Cognito to request for temporary
security credentials.

Create an Android Application
Create a simple Android mobile application that generates events and invokes Lambda functions by
passing the event data as parameters.
The following instructions have been veriﬁed using Android studio.
1.

Create a new Android project called AndroidEventGenerator using the following conﬁguration:
• Select the Phone and Tablet platform.

2.

• Choose Blank Activity.
In the build.gradle (Module:app) ﬁle, add the following in the dependencies section:
compile 'com.amazonaws:aws-android-sdk-core:2.2.+'
compile 'com.amazonaws:aws-android-sdk-lambda:2.2.+'

3.
4.

Build the project so that the required dependencies are downloaded, as needed.
In the Android application manifest (AndroidManifest.xml), add the following permissions so
that your application can connect to the Internet. You can add them just before the 
end tag.



5.

In MainActivity, add the following imports:
import com.amazonaws.mobileconnectors.lambdainvoker.*;
import com.amazonaws.auth.CognitoCachingCredentialsProvider;
import com.amazonaws.regions.Regions;

6.

In the package section, add the following two classes (RequestClass and ResponseClass). Note
that the POJO is same as the POJO you created in your Lambda function in the preceding section.
• RequestClass. The instances of this class act as the POJO (Plain Old Java Object) for event data
which consists of ﬁrst and last name. If you are using Java example for your Lambda function
you created in the preceding section, this POJO is same as the POJO you created in your Lambda
function code.

191

AWS Lambda Developer Guide
Tutorial

package com.example....lambdaeventgenerator;
public class RequestClass {
String firstName;
String lastName;
public String getFirstName() {
return firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
return lastName;
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
public RequestClass(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}

}

public RequestClass() {
}

• ResponseClass
package com.example....lambdaeventgenerator;
public class ResponseClass {
String greetings;
public String getGreetings() {
return greetings;
}
public void setGreetings(String greetings) {
this.greetings = greetings;
}
public ResponseClass(String greetings) {
this.greetings = greetings;
}

}

7.

public ResponseClass() {
}

In the same package, create interface called MyInterface for invoking the
AndroidBackendLambdaFunction Lambda function.
package com.example.....lambdaeventgenerator;
import com.amazonaws.mobileconnectors.lambdainvoker.LambdaFunction;
public interface MyInterface {
/**
* Invoke the Lambda function "AndroidBackendLambdaFunction".
* The function name is the method name.
*/

192

AWS Lambda Developer Guide
Tutorial
@LambdaFunction
ResponseClass AndroidBackendLambdaFunction(RequestClass request);
}

The @LambdaFunction annotation in the code maps the speciﬁc client method to the same-name
Lambda function. For more information about this annotation, see AWS Lambda in the AWS Mobile
SDK for Android Developer Guide.
8.

To keep the application simple, we are going to add code to invoke the Lambda function in the
onCreate() event handler. In MainActivity, add the following code toward the end of the
onCreate() code.
// Create an instance of CognitoCachingCredentialsProvider
CognitoCachingCredentialsProvider cognitoProvider = new
CognitoCachingCredentialsProvider(
this.getApplicationContext(), "identity-pool-id", Regions.US_WEST_2);
// Create LambdaInvokerFactory, to be used to instantiate the Lambda proxy.
LambdaInvokerFactory factory = new LambdaInvokerFactory(this.getApplicationContext(),
Regions.US_WEST_2, cognitoProvider);
// Create the Lambda proxy object with a default Json data binder.
// You can provide your own data binder by implementing
// LambdaDataBinder.
final MyInterface myInterface = factory.build(MyInterface.class);
RequestClass request = new RequestClass("John", "Doe");
// The Lambda function invocation results in a network call.
// Make sure it is not called from the main thread.
new AsyncTask() {
@Override
protected ResponseClass doInBackground(RequestClass... params) {
// invoke "echo" method. In case it fails, it will throw a
// LambdaFunctionException.
try {
return myInterface.AndroidBackendLambdaFunction(params[0]);
} catch (LambdaFunctionException lfe) {
Log.e("Tag", "Failed to invoke echo", lfe);
return null;
}
}
@Override
protected void onPostExecute(ResponseClass result) {
if (result == null) {
return;
}
// Do a toast
Toast.makeText(MainActivity.this, result.getGreetings(),
Toast.LENGTH_LONG).show();
}
}.execute(request);

9.

Run the code and verify it as follows:
• The Toast.makeText() displays the response returned.
• Verify that CloudWatch Logs shows the log created by the Lambda function. It should show the
event data (ﬁrst name and last name). You can also verify this in the AWS Lambda console.

193

AWS Lambda Developer Guide
Sample Code

Sample Function Code
Sample code is available for the following languages.
Topics
• Node.js (p. 194)
• Java (p. 194)

Node.js
The following example uses data to generate a string reponse.

Example index.js
exports.handler = function(event, context, callback) {
console.log("Received event: ", event);
var data = {
"greetings": "Hello, " + event.firstName + " " + event.lastName + "."
};
callback(null, data);
}

Zip up the sample code to create a deployment package. For instructions, see AWS Lambda Deployment
Package in Node.js (p. 250).

Java
The following example uses data to generate a string reponse.
In the code, the handler (myHandler) uses the RequestClass and ResponseClass types for the
input and output. The code provides implementation for these types.

Example HelloPojo.java
package example;
import com.amazonaws.services.lambda.runtime.Context;
public class HelloPojo {
// Define two classes/POJOs for use with Lambda function.
public static class RequestClass {
String firstName;
String lastName;
public String getFirstName() {
return firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
return lastName;
}

194

AWS Lambda Developer Guide
CloudWatch Events
public void setLastName(String lastName) {
this.lastName = lastName;
}
public RequestClass(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}

}

public RequestClass() {
}

public static class ResponseClass {
String greetings;
public String getGreetings() {
return greetings;
}
public void setGreetings(String greetings) {
this.greetings = greetings;
}
public ResponseClass(String greetings) {
this.greetings = greetings;
}
public ResponseClass() {
}
}
public static ResponseClass myHandler(RequestClass request, Context context){
String greetingString = String.format("Hello %s, %s.", request.firstName,
request.lastName);
context.getLogger().log(greetingString);
return new ResponseClass(greetingString);
}

}

Dependencies
• aws-lambda-java-core
Build the code with the Lambda library dependencies to create a deployment package. For instructions,
see AWS Lambda Deployment Package in Java (p. 276).

Using AWS Lambda with Amazon CloudWatch
Events
You can create a Lambda function and direct AWS Lambda to execute it on a regular schedule. You
can specify a ﬁxed rate (for example, execute a Lambda function every hour or 15 minutes), or you can
specify a Cron expression. For more information on expressions schedules, see Schedule Expressions
Using Rate or Cron (p. 199).
This functionality is available when you create a Lambda function using the AWS Lambda console or the
AWS CLI. To conﬁgure it using the AWS CLI, see Run an AWS Lambda Function on a Schedule Using the

195

AWS Lambda Developer Guide
Tutorial

AWS CLI. The console provides CloudWatch Events as an event source. At the time of creating a Lambda
function, you choose this event source and specify a time interval.
If you have made any manual changes to the permissions on your function, you may need to reapply the
scheduled event access to your function. You can do that by using the following CLI command.
$ aws lambda add-permission --function-name function_name\
--action 'lambda:InvokeFunction' --principal events.amazonaws.com \
--statement-id 'statement_id' \
--source-arn arn:aws:events:region:account-id:rule/rule_name

Each AWS account can have up to 100 unique event sources of the CloudWatch Events- Schedule source
type. Each of these can be the event source for up to ﬁve Lambda functions. That is, you can have up to
500 Lambda functions that can be executing on a schedule in your AWS account.
The console also provides a blueprint (lambda-canary) that uses the CloudWatch Events - Schedule
source type. Using this blueprint, you can create a sample Lambda function and test this feature. The
example code that the blueprint provides checks for the presence of a speciﬁc webpage and speciﬁc text
string on the webpage. If either the webpage or the text string is not found, the Lambda function throws
an error.

Tutorial: Using AWS Lambda with Scheduled Events
In this tutorial, you do the following:
• Create a Lambda function using the lambda-canary blueprint. You conﬁgure the Lambda function
to run every minute. Note that if the function returns an error, AWS Lambda logs error metrics to
CloudWatch.
• Conﬁgure a CloudWatch alarm on the Errors metric of your Lambda function to post a message to
your Amazon SNS topic when AWS Lambda emits error metrics to CloudWatch. You subscribe to the
Amazon SNS topics to get email notiﬁcation. In this tutorial, you do the following to set this up:
• Create an Amazon SNS topic.
• Subscribe to the topic so you can get email notiﬁcations when a new message is posted to the topic.
• In Amazon CloudWatch, set an alarm on the Errors metric of your Lambda function to publish a
message to your SNS topic when errors occur.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.

Create a Lambda Function
1.

Sign in to the AWS Management Console and open the AWS Lambda console at https://
console.aws.amazon.com/lambda/.

2.
3.
4.
5.

Choose Create function.
Choose Blueprints.
Enter canary in the search bar. Choose the lambda-canary blueprint and then choose Conﬁgure.
Conﬁgure the following settings.
• Name – lambda-canary.
• Role – Create a new role from one or more templates.
• Role name – lambda-apigateway-role.

196

AWS Lambda Developer Guide
Tutorial

• Policy templates – Simple microservice permissions.
• Rule – Create a new rule.
• Rule name – CheckWebsiteScheduledEvent.
• Rule description – CheckWebsiteScheduledEvent trigger.
• Schedule expression – rate(1 minute).
• Enabled – True (checked).
• Environment variables
• site – https://docs.aws.amazon.com/lambda/latest/dg/welcome.html
• expected – What Is AWS Lambda?
6.

Choose Create function.

CloudWatch Events emits an event every minute, based on the schedule expression. The event triggers
the Lambda function, which veriﬁes that the expected string appears in the speciﬁed page. For more
information on expressions schedules, see Schedule Expressions Using Rate or Cron (p. 199).

Test the Lambda Function
Test the function with a sample event provided by the Lambda console.
1.

Open the Lambda console Functions page.

2.

Choose lambda-canary.

3.

Next to the Test button at the top of the page, choose Conﬁgure test events from the drop-down
menu.

4.

Create a new event using the CloudWatch Events event template.

5.

Choose Create.

6.

Choose Test.

The output from the function execution is shown at the top of the page.

Create an Amazon SNS Topic and Subscribe to It
Create an Amazon Simple Notiﬁcation Service topic to receive notiﬁcations when the canary function
returns an error.

To create a topic
1.

Open the Amazon SNS console.

2.

Choose Create topic.

3.

Create a topic with the following settings.
• Name – lambda-canary-notifications.
• Display name – Canary.

4.

Choose Create subscription.

5.

Create a subscription with the following settings.
• Protocol – Email.
• Endpoint – Your email address.

Amazon SNS sends an email from Canary , reﬂecting the friendly
name of the topic. Use the link in the email to conﬁrm your address.

197

AWS Lambda Developer Guide
Sample Template

Conﬁgure an Alarm
Conﬁgure an alarm in Amazon CloudWatch that monitors the Lambda function and sends a notiﬁcation
when it fails.

To create an alarm
1.

Open the CloudWatch console.

2.

Choose Alarms.

3.
4.

Choose Create alarm.
Choose Alarms.

5.

Create an with the following settings.
• Metrics – lambda-canary Errors.
Search for lambda canary errors to ﬁnd the metric.
• Statistic – Sum.
Choose the statistic from the drop down above the preview graph.
• Name – lambda-canary-alarm.
• Description – Lambda canary alarm.
• Threshold – Whenever Errors is >=1.
• Send notiﬁcation to – lambda-canary-notifications

Test the Alarm
Update the function conﬁguration to cause the function to return an error, triggering the alarm.

To trigger an alarm
1.
2.
3.

Open the Lambda console Functions page.
Choose lambda-canary.
Under Environment variables, set expected to 404.

4.

Choose Save

Wait a minute, and then check your email for a message from Amazon SNS

AWS SAM Template for a CloudWatch Events
Application
You can build this application using AWS SAM. To learn more about creating AWS SAM templates, see
AWS SAM Template Basics in the AWS Serverless Application Model Developer Guide.
Below is a sample AWS SAM template for the Lambda application from the tutorial (p. 196). Copy
the text below to a .yaml ﬁle and save it next to the ZIP package you created previously. Note that
the Handler and Runtime parameter values should match the ones you used when you created the
function in the previous section.

Example template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

198

AWS Lambda Developer Guide
Schedule Expressions
Parameters:
NotificationEmail:
Type: String
Resources:
CheckWebsitePeriodically:
Type: AWS::Serverless::Function
Properties:
Handler: LambdaFunctionOverHttps.handler
Runtime: runtime
Policies: AmazonDynamoDBFullAccess
Events:
CheckWebsiteScheduledEvent:
Type: Schedule
Properties:
Schedule: rate(1 minute)
AlarmTopic:
Type: AWS::SNS::Topic
Properties:
Subscription:
- Protocol: email
Endpoint: !Ref NotificationEmail
Alarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmActions:
- !Ref AlarmTopic
ComparisonOperator: GreaterThanOrEqualToThreshold
Dimensions:
- Name: FunctionName
Value: !Ref CheckWebsitePeriodically
EvaluationPeriods: 1
MetricName: Errors
Namespace: AWS/Lambda
Period: 60
Statistic: Sum
Threshold: '1'

For information on how to package and deploy your serverless application using the package and deploy
commands, see Deploying Serverless Applications in the AWS Serverless Application Model Developer
Guide.

Schedule Expressions Using Rate or Cron
Rate expression
rate(Value Unit)

Where:
Value can be a positive integer.
Unit can be minute(s), hour(s), or day(s).
For example:
Example

Cron expression

Invoke Lambda function every 5 minutes

rate(5 minutes)

199

AWS Lambda Developer Guide
Schedule Expressions

Example

Cron expression

Invoke Lambda function every hour

rate(1 hour)

Invoke Lambda function every seven days

rate(7 days)

Note the following:
• Rate frequencies of less than one minute are not supported.
• For a singular value the unit must be singular (for example, rate(1 day)), otherwise plural (for
example, rate(5 days)).
Cron expression
cron(Minutes Hours Day-of-month Month Day-of-week Year)

All ﬁelds are required and time zone is UTC only. The following table describes these ﬁelds.

Field

Values

Wildcards

Minutes

0-59

,-*/

Hours

0-23

,-*/

Day-of-month

1-31

,-*?/LW

Month

1-12 or JAN-DEC

,-*/

Day-of-week

1-7 or SUN-SAT

,-*?/L#

Year

1970-2199

,-*/

The following table describes the wildcard characters.

Character

Deﬁnition

Example

/

Speciﬁes
increments

0/15 in the minutes ﬁeld directs execution to occur every 15
minutes.

L

Speciﬁes "Last"

If used in Day-of-month ﬁeld, speciﬁes last day of the
month. If used in Day-of-week ﬁeld, speciﬁes last day of the
week (Saturday).

W

Speciﬁes Weekday

When used with a date, such as 5/W, speciﬁes the closest
weekday to 5th day of the month. If the 5th falls on a
Saturday, execution occurs on Friday. If the 5th falls on a
Sunday, execution occurs on Monday.

#

Speciﬁes the nd
or nth day of the
month

Specifying 3#2 means the second Tuesday of the month
(Tuesday is the third day of the 7-day week).

200

AWS Lambda Developer Guide
Schedule Expressions

Character

Deﬁnition

Example

*

Speciﬁes All values

If used in the Day-of-month ﬁeld, it means all days in the
month.

?

No speciﬁed value

Used in conjunction with another speciﬁed value. For
example, if a speciﬁc date is speciﬁed, but you don't care
what day of the week it falls on.

-

Speciﬁes ranges

10-12 would mean 10, 11 and 12

,

Speciﬁes
additional values

SUN,MON,TUE means Sunday, Monday and Tuesday

/

Speciﬁes
increments

5/10 means 5, 15, 25, 35, etc.

The following table lists common examples of cron expressions.

Example

Cron expression

Invoke a Lambda function at
10:00am (UTC) everyday

cron(0 10 * * ? *)

Invoke a Lambda function
12:15pm (UTC) everyday

cron(15 12 * * ? *)

Invoke a Lambda function at
06:00pm (UTC) every Mon-Fri

cron(0 18 ? * MON-FRI *)

Invoke a Lambda function at
8:00am (UTC) every ﬁrst day of
the month
Invoke a Lambda function every
10 min Mon-Fri
Invoke a Lambda function every
5 minutes Mon-Fri between
8:00am and 5:55pm (UTC)
Invoke a Lambda function at 9
a.m. (UTC) the ﬁrst Monday of
each month

cron(0 8 1 * ? *)

cron(0/10 * ? * MON-FRI *)

cron(0/5 8-17 ? * MON-FRI *)

cron(0 9 ? * 2#1 *)

Note the following:
• The previous examples assume you are using the AWS CLI. If you are using the Lambda console, do not
include the cron preﬁx to your expression.
• Cron expressions that lead to rates faster than one minute are not supported.
• One of the day-of-month or day-of-week values must be a question mark (?).

201

AWS Lambda Developer Guide
Application Load Balancer

Using AWS Lambda with an Application Load
Balancer
You can use a Lambda function to process requests from an Application Load Balancer. Elastic Load
Balancing supports Lambda functions as a target for an Application Load Balancer. Use load balancer
rules to route HTTP requests to a function, based on path or header values. Process the request and
return an HTTP response from your Lambda function.
Elastic Load Balancing invokes your Lambda function synchronously with an event that contains the
request body and metadata.

Example Application Load Balancer Request Event
{

'requestContext': {
'elb': {
'targetGroupArn': 'arn:aws:elasticloadbalancing:useast-1:123456789012:targetgroup/lambda-target/d6190d154bc908a5'
}
},
'httpMethod': 'GET',
'path': '/health',
'queryStringParameters': {},
'headers': {
'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
'accept-encoding': 'gzip',
'accept-language': 'en-US,en;q=0.5',
'connection': 'keep-alive',
'cookie': 'cookie',
'host': 'lambda-846800462.elb.amazonaws.com',
'upgrade-insecure-requests': '1',
'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:60.0)
Gecko/20100101 Firefox/60.0',
'x-amzn-trace-id': 'Root=1-5bdb40ca-556d8b0c50dc66f0511bf520',
'x-forwarded-for': '72.21.198.66',
'x-forwarded-port': '80',
'x-forwarded-proto': 'http',
},
'body': '',
'isBase64Encoded': False
}

Your function processes the event and returns a response to the load balancer in JSON. Elastic Load
Balancing converts the response to HTTP and returns it to the user.

Example Response Format
{

}

"statusCode": 200,
"statusDescription": "HTTP OK",
"isBase64Encoded": False,
"headers": {
"server": "my-server",
"set-cookie": "name=value",
"Content-Type": "text/html; charset=utf-8"
},
"body": "Welcome"

202

AWS Lambda Developer Guide
AWS CLI

To conﬁgure an Application Load Balancer as a function trigger, grant Elastic Load Balancing permission
to execute the function, create a target group that routes requests to the function, and add a rule to the
load balancer that sends requests to the target group.
Use the add-permission command to add a permission statement to your function's resource-based
policy.
$ aws lambda add-permission --function-name alb-function \
--statement-id load-balancer --action "lambda:InvokeFunction" \
--principal elasticloadbalancing.amazonaws.com
{
"Statement": "{\"Sid\":\"load-balancer\",\"Effect\":\"Allow\",\"Principal\":{\"Service
\":\"elasticloadbalancing.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource
\":\"arn:aws:lambda:us-west-2:123456789012:function:alb-function\"}"
}

For instructions on conﬁguring the Application Load Balancer listener and target group, see Lambda
Functions as a Target in the User Guide for Application Load Balancers.

Using AWS Lambda with the AWS Command Line
Interface
You can use the AWS Command Line Interface to manage functions and other AWS Lambda resources.
The AWS CLI uses the AWS SDK for Python (Boto) to interact with the Lambda API. You can use it to
learn about the API, and apply that knowledge in building applications that use Lambda with the AWS
SDK.
In this tutorial, you manage and invoke Lambda functions with the AWS CLI.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting Started with AWS Lambda (p. 3) to
create your ﬁrst Lambda function.
To follow the procedures in this guide, you will need a command line terminal or shell to run commands.
Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory,
when appropriate:
~/lambda-project$ this is a command
this is output

For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the Execution Role
Create the execution role (p. 222) that gives your function permission to access AWS resources.

To create an execution role
1.

Open the roles page in the IAM console.

203

AWS Lambda Developer Guide
Create the Function

2.

Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – AWS Lambda.
• Permissions – AWSLambdaBasicExecutionRole.
• Role name – lambda-cli-role.

The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write logs to
CloudWatch Logs.

Create the Function
The following example code receives an event as input and logs some of the incoming event data to
CloudWatch Logs.

Example index.js
console.log('Loading function');
exports.handler = function(event, context, callback) {
console.log('value1 =', event.key1);
console.log('value2 =', event.key2);
console.log('value3 =', event.key3);
callback(null, "Success");
};

To create the function
1.

Copy the sample code into a ﬁle named index.js.

2.

Create a deployment package.
$ zip function.zip index.js

3.

Create a Lambda function with the create-function command.
$ aws lambda create-function --function-name helloworld \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs8.10 \
--role arn:aws:iam::123456789012:role/lambda-cli-role
{
"FunctionName": "helloworld",
"CodeSize": 351,
"MemorySize": 128,
"FunctionArn": "function-arn",
"Handler": "index.handler",
"Role": "arn:aws:iam::account-id:role/LambdaExecRole",
"Timeout": 3,
"LastModified": "2015-04-07T22:02:58.854+0000",
"Runtime": "nodejs8.10",
"Description": ""
}

Invoke your Lambda function using the invoke command.
$ aws lambda invoke --function-name helloworld --log-type Tail \
--payload '{"key1":"value1", "key2":"value2", "key3":"value3"}' \
outputfile.txt

204

AWS Lambda Developer Guide
List the Lambda Functions in Your Account
{
}

"LogResult": "base64-encoded-log",
"StatusCode": 200

By specifying the --log-type parameter, the command also requests the tail end of the log produced
by the function. The log data in the response is base64-encoded. Use the base64 program to decode the
log.
$ echo base64-encoded-log | base64 --decode
START RequestId: 16d25499-d89f-11e4-9e64-5d70fce44801
2015-04-01T18:44:12.323Z
16d25499-d89f-11e4-9e64-5d70fce44801
value1 = value1
2015-04-01T18:44:12.323Z
16d25499-d89f-11e4-9e64-5d70fce44801
value2 = value2
2015-04-01T18:44:12.323Z
16d25499-d89f-11e4-9e64-5d70fce44801
value3 = value3
2015-04-01T18:44:12.323Z
16d25499-d89f-11e4-9e64-5d70fce44801
result: "value1"
END RequestId: 16d25499-d89f-11e4-9e64-5d70fce44801
REPORT RequestId: 16d25499-d89f-11e4-9e64-5d70fce44801
Duration: 13.35 ms
Billed Duration: 100 ms
Memory Size: 128 MB
Max Memory Used: 9 MB

Because you invoked the function using the default invocation type (RequestResponse), the connection
stays open until execution completes. Lambda writes the response to the output ﬁle.

List the Lambda Functions in Your Account
Execute the following AWS CLI list-functions command to retrieve a list of functions that you have
created.
$ aws lambda list-functions --max-items 10
{
"Functions": [
{
"FunctionName": "helloworld",
"MemorySize": 128,
"CodeSize": 412,
"FunctionArn": "arn:aws:lambda:us-east-1:accountid:function:ProcessKinesisRecords",
"Handler": "ProcessKinesisRecords.handler",
"Role": "arn:aws:iam::account-id:role/LambdaExecRole",
"Timeout": 3,
"LastModified": "2015-02-22T21:03:01.172+0000",
"Runtime": "nodejs6.10",
"Description": ""
},
{
"FunctionName": "ProcessKinesisRecords",
"MemorySize": 128,
"CodeSize": 412,
"FunctionArn": "arn:aws:lambda:us-east-1:accountid:function:ProcessKinesisRecords",
"Handler": "ProcessKinesisRecords.handler",
"Role": "arn:aws:iam::account-id:role/lambda-execute-test-kinesis",
"Timeout": 3,
"LastModified": "2015-02-22T21:03:01.172+0000",
"Runtime": "nodejs6.10",
"Description": ""
},
...
],
"NextMarker": null
}

205

AWS Lambda Developer Guide
Clean Up

In response, Lambda returns a list of up to 10 functions. If there are more functions you can retrieve,
NextMarker provides a marker you can use in the next list-functions request; otherwise, the value
is null. The following list-functions AWS CLI command is an example that shows the --marker
parameter.
$ aws lambda list-functions --max-items 10 \
--marker value-of-NextMarker-from-previous-response

Retrieve a Lambda Function
The Lambda CLI get-function command returns Lambda function metadata and a presigned URL that
you can use to download the function's deployment packagen.
$ aws lambda get-function --function-name helloworld
{
"Code": {
"RepositoryType": "S3",
"Location": "pre-signed-url"
},
"Configuration": {
"FunctionName": "helloworld",
"MemorySize": 128,
"CodeSize": 287,
"FunctionArn": "arn:aws:lambda:us-west-2:account-id:function:helloworld",
"Handler": "index.handler",
"Role": "arn:aws:iam::account-id:role/LambdaExecRole",
"Timeout": 3,
"LastModified": "2015-04-07T22:02:58.854+0000",
"Runtime": "nodejs8.10",
"Description": ""
}
}

For more information, see GetFunction (p. 395).

Clean Up
Execute the following delete-function command to delete the helloworld function.
$ aws lambda delete-function --function-name helloworld

Delete the IAM role you created in the IAM console. For information about deleting a role, see Deleting
Roles or Instance Proﬁles in the IAM User Guide.

Lambda@Edge
Lambda@Edge lets you run Lambda functions to customize content that CloudFront delivers, executing
the functions in AWS locations closer to the viewer. The functions run in response to CloudFront events,
without provisioning or managing servers. You can use Lambda functions to change CloudFront requests
and responses at the following points:
• After CloudFront receives a request from a viewer (viewer request)
• Before CloudFront forwards the request to the origin (origin request)
• After CloudFront receives the response from the origin (origin response)

206

AWS Lambda Developer Guide
Lambda@Edge

• Before CloudFront forwards the response to the viewer (viewer response)

You can also generate responses to viewers without ever sending the request to the origin.
With Lambda@Edge, you can build a variety of solutions, for example:
• Inspect cookies to rewrite URLs to diﬀerent versions of a site for A/B testing.
• Send diﬀerent objects to your users based on the User-Agent header, which contains information
about the device that submitted the request. For example, you can send images in diﬀerent resolutions
to users based on their devices.
• Inspect headers or authorized tokens, inserting a corresponding header and allowing access control
before forwarding a request to the origin.
• Add, delete, and modify headers, and rewrite the URL path to direct users to diﬀerent objects in the
cache.
• Generate new HTTP responses to do things like redirect unauthenticated users to login pages, or
create and deliver static webpages right from the edge. For more information, see Using Lambda
Functions to Generate HTTP Responses to Viewer and Origin Requests in the Amazon CloudFront
Developer Guide.
For more information about using Lambda@Edge, see Using CloudFront with Lambda@Edge.

207

AWS Lambda Developer Guide
Using Amazon CloudWatch

Monitoring and Troubleshooting
Lambda Applications
AWS Lambda will automatically track the behavior of your Lambda function invocations and provide
feedback that you can monitor. In addition, it provides metrics that allows you to analyze the full
function invocation spectrum, including event source integration and whether downstream resources
perform as expected. The following sections provide guidance on the tools you can use to analyze your
Lambda function invocation behavior:
Topics
• Using Amazon CloudWatch (p. 208)
• Using AWS X-Ray (p. 214)

Using Amazon CloudWatch
AWS Lambda automatically monitors Lambda functions on your behalf, reporting metrics through
Amazon CloudWatch. To help you monitor your code as it executes, Lambda automatically tracks the
number of requests, the execution duration per request, and the number of requests resulting in an error
and publishes the associated CloudWatch metrics. You can leverage these metrics to set CloudWatch
custom alarms. For more information about CloudWatch, see the Amazon CloudWatch User Guide.
You can view request rates and error rates for each of your Lambda functions by using the AWS Lambda
console, the CloudWatch console, and other Amazon Web Services (AWS) resources. The following topics
describe Lambda CloudWatch metrics and how to access them.
• Accessing Amazon CloudWatch Metrics for AWS Lambda (p. 210)
• AWS Lambda Metrics (p. 211)
You can insert logging statements into your code to help you validate that your code is working as
expected. Lambda automatically integrates with Amazon CloudWatch Logs and pushes all logs from
your code to a CloudWatch Logs group associated with a Lambda function (/aws/lambda/). To learn more about log groups and accessing them through the CloudWatch console, see
the Monitoring System, Application, and Custom Log Files in the Amazon CloudWatch User Guide. For
information about how to access CloudWatch log entries, see Accessing Amazon CloudWatch Logs for
AWS Lambda (p. 211).

Note

If your Lambda function code is executing, but you don't see any log data being generated after
several minutes, this could mean your execution role for the Lambda function did not grant
permissions to write log data to CloudWatch Logs. For information about how to make sure
that you have set up the execution role correctly to grant these permissions, see AWS Lambda
Execution Role (p. 222).

AWS Lambda Troubleshooting Scenarios
This section describes examples of how to monitor and troubleshoot your Lambda functions using the
logging and monitoring capabilities of CloudWatch.

208

AWS Lambda Developer Guide
AWS Lambda Troubleshooting Scenarios

Troubleshooting Scenario 1: Lambda Function Not Working as
Expected
In this scenario, you have just ﬁnished Tutorial: Using AWS Lambda with Amazon S3 (p. 116). However,
the Lambda function you created to upload a thumbnail image to Amazon S3 when you create an S3
object is not working as expected. When you upload objects to Amazon S3, you see that the thumbnail
images are not being uploaded. You can troubleshoot this issue in the following ways.

To determine why your Lambda function is not working as expected
1.

Check your code and verify that it is working correctly. An increased error rate would indicate that it
is not.
You can test your code locally as you would any other Node.js function, or you can test it within the
Lambda console using the console's test invoke functionality, or you can use the AWS CLI Invoke
command. Each time the code is executed in response to an event, it writes a log entry into the log
group associated with a Lambda function, which is /aws/lambda/.
Following are some examples of errors that might show up in the logs:
• If you see a stack trace in your log, there is probably an error in your code. Review your code and
debug the error that the stack trace refers to.
• If you see a permissions denied error in the log, the IAM role you have provided as an
execution role may not have the necessary permissions. Check the IAM role and verify that it has
all of the necessary permissions to access any AWS resources that your code references. To ensure
that you have correctly set up the execution role, see AWS Lambda Execution Role (p. 222).
• If you see a timeout exceeded error in the log, your function was terminated because it did not
return prior to the conﬁgured timeout. This may be because the timeout is too low, or the code is
taking too long to execute.
• If you see a memory exceeded error in the log, your memory setting is too low. Set it to a higher
value. For information about memory size limits, see CreateFunction (p. 368).

2.

Check your Lambda function and verify that it is receiving requests.
Even if your function code is working as expected and responding correctly to test invokes, the
function may not be receiving requests from Amazon S3. If Amazon S3 is able to invoke the
function, you should see an increase in your CloudWatch requests metrics. If you do not see an
increase in your CloudWatch requests, check the access permissions policy associated with the
function.

Troubleshooting Scenario 2: Increased Duration in Lambda
Function Execution
In this scenario, you have just ﬁnished Tutorial: Using AWS Lambda with Amazon S3 (p. 116). However,
the Lambda function you created to upload a thumbnail image to Amazon S3 when you create an
S3 object is not working as expected. When you upload objects to Amazon S3, you can see that the
thumbnail images are being uploaded, but your code is taking much longer to execute than expected.
You can troubleshoot this issue in a couple of diﬀerent ways. For example, you could monitor the
duration metric for the Lambda function to see if the execution time is increasing. Or you could see an
increase in the CloudWatch errors metric for the Lambda function, which might be due to timeout errors.

To determine why there is increased duration in the execution of a Lambda function
1.

Test your code with diﬀerent memory settings.
209

AWS Lambda Developer Guide
Monitoring Graphs

2.

If your code is taking too long to execute, it could be that it does not have enough compute
resources to execute its logic. Try increasing the memory allocated to your function and testing the
code again, using the Lambda console's test invoke functionality. You can see the memory used,
code execution time, and memory allocated in the function log entries. Changing the memory
setting can change how you are charged for execution time. For information about pricing, see AWS
Lambda.
Use logs to investigate the source of the execution bottleneck
You can test your code locally, as you would with any other Node.js function, or you can test it
within Lambda using the test invoke capability on the Lambda console, or using the asyncInvoke
command by using AWS CLI. Each time the code is executed in response to an event, it writes
a log entry into the log group associated with a Lambda function, which is named aws/
lambda/. Add logging statements around various parts of your code, such as
callouts to other services, to see how much time it takes to execute diﬀerent parts of your code.

Accessing Amazon CloudWatch Metrics for AWS
Lambda
AWS Lambda automatically monitors functions on your behalf, reporting metrics through Amazon
CloudWatch. These metrics include total requests, duration, and error rates.

To access metrics using the Lambda console
1.

Open the Lambda console.

2.
3.

Open the Lambda console Functions page.
Choose Monitoring.

The console provides the following graphs.

Lambda Monitoring Graphs
• Invocations – The number of times the function was invoked in each 5 minute period.
• Duration – Average, minimum, and maximum execution times.
• Errors, Availability (%) – The number of errors, and the percentage of executions that completed
without error.
• Throttles – The number of times execution failed due to concurrency limits.
• IteratorAge – For stream event sources, the age of the last item in the batch when Lambda receives it
and invokes the function.

210

AWS Lambda Developer Guide
Accessing CloudWatch Logs

• DeadLetterErrors – The number of events that Lambda attempted to write to a dead letter queue, but
failed.
To see the deﬁnition of a graph in CloudWatch, choose View in metrics from the menu in the top
right of the graph. For more information about the metrics that Lambda records, see AWS Lambda
Metrics (p. 211).

Accessing Amazon CloudWatch Logs for AWS Lambda
AWS Lambda automatically monitors Lambda functions on your behalf, reporting metrics through
Amazon CloudWatch. To help you troubleshoot failures in a function, Lambda logs all requests
handled by your function and also automatically stores logs generated by your code through Amazon
CloudWatch Logs.
You can insert logging statements into your code to help you validate that your code is working as
expected. Lambda automatically integrates with CloudWatch Logs and pushes all logs from your code to
a CloudWatch Logs group associated with a Lambda function, which is named /aws/lambda/. To learn more about log groups and accessing them through the CloudWatch console, see the
Monitoring System, Application, and Custom Log Files in the Amazon CloudWatch User Guide.
You can view logs for Lambda by using the Lambda console, the CloudWatch console, the AWS CLI,
or the CloudWatch API. The following procedure show you how to view the logs by using the Lambda
console.

Note

There is no additional charge for using Lambda logs; however, standard CloudWatch Logs
charges apply. For more information, see CloudWatch Pricing.

To view logs using the Lambda console
1.

Open the Lambda console.

2.
3.

Open the Lambda console Functions page.
Choose Monitoring.

4.

A graphical representation of the metrics for the Lambda function are shown.
Choose View logs in CloudWatch.

AWS Lambda Metrics
This topic describes the AWS Lambda namespace, metrics, and dimensions. AWS Lambda automatically
monitors functions on your behalf, reporting metrics through Amazon CloudWatch. These metrics

211

AWS Lambda Developer Guide
Lambda Metrics

include total invocations, errors, duration, throttles, DLQ errors and Iterator age for stream-based
invocations.
CloudWatch is basically a metrics repository. A metric is the fundamental concept in CloudWatch and
represents a time-ordered set of data points. You (or AWS services) publish metrics data points into
CloudWatch and you retrieve statistics about those data points as an ordered set of time-series data.
Metrics are uniquely deﬁned by a name, a namespace, and one or more dimensions. Each data point has
a time stamp, and, optionally, a unit of measure. When you request statistics, the returned data stream is
identiﬁed by namespace, metric name, and dimension. For more information about CloudWatch, see the
Amazon CloudWatch User Guide.

AWS Lambda CloudWatch Metrics
The AWS/Lambda namespace includes the following metrics.
Metric

Description

Invocations

Measures the number of times a function is invoked in response to an
event or invocation API call. This replaces the deprecated RequestCount
metric. This includes successful and failed invocations, but does not include
throttled attempts. This equals the billed requests for the function. Note
that AWS Lambda only sends these metrics to CloudWatch if they have a
nonzero value.
Units: Count

Errors

Measures the number of invocations that failed due to errors in the function
(response code 4XX). This replaces the deprecated ErrorCount metric. Failed
invocations may trigger a retry attempt that succeeds. This includes:
• Handled exceptions (for example, context.fail(error))
• Unhandled exceptions causing the code to exit
• Out of memory exceptions
• Timeouts
• Permissions errors
This does not include invocations that fail due to invocation rates exceeding
default concurrent limits (error code 429) or failures due to internal service
errors (error code 500).
Units: Count

DeadLetterErrors

Incremented when Lambda is unable to write the failed event payload to
your conﬁgured Dead Letter Queues. This could be due to the following:
• Permissions errors
• Throttles from downstream services
• Misconﬁgured resources
• Timeouts
Units: Count

Duration

Measures the elapsed wall clock time from when the function code starts
executing as a result of an invocation to when it stops executing. The
maximum data point value possible is the function timeout conﬁguration.

212

AWS Lambda Developer Guide
Lambda Metrics

Metric

Description
The billed duration will be rounded up to the nearest 100 millisecond. Note
that AWS Lambda only sends these metrics to CloudWatch if they have a
nonzero value.
Units: Milliseconds

Throttles

Measures the number of Lambda function invocation attempts that were
throttled due to invocation rates exceeding the customer’s concurrent
limits (error code 429). Failed invocations may trigger a retry attempt that
succeeds.
Units: Count

IteratorAge

Emitted for stream-based invocations only (functions triggered by an
Amazon DynamoDB stream or Kinesis stream). Measures the age of the last
record for each batch of records processed. Age is the diﬀerence between
the time Lambda received the batch, and the time the last record in the
batch was written to the stream.
Units: Milliseconds

ConcurrentExecutionsEmitted as an aggregate metric for all functions in the account, and for
functions that have a custom concurrency limit speciﬁed. Not applicable for
versions or aliases. Measures the sum of concurrent executions for a given
function at a given point in time. Must be viewed as an average metric if
aggregated across a time period.
Units: Count
UnreservedConcurrentExecutions
Emitted as an aggregate metric for all functions in the account only. Not
applicable for functions, versions, or aliases. Represents the sum of the
concurrency of the functions that do not have a custom concurrency limit
speciﬁed. Must be viewed as an average metric if aggregated across a time
period.
Units: Count

To access metrics using the CloudWatch console
1.

Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

2.

In the navigation pane, choose Metrics.

3.

In the CloudWatch Metrics by Category pane, choose Lambda Metrics.

Errors/Invocations Ratio

When calculating the error rate on Lambda function invocations, it’s important to distinguish
between an invocation request and an actual invocation. It is possible for the error rate to
exceed the number of billed Lambda function invocations. Lambda reports an invocation metric
only if the Lambda function code is executed. If the invocation request yields a throttling or
other initialization error that prevents the Lambda function code from being invoked, Lambda
will report an error, but it does not log an invocation metric.
• Lambda emits Invocations=1 when the function is executed. If the Lambda function is not
executed, nothing is emitted.
• Lambda emits a data point for Errors for each invoke request. Errors=0 means that there is
no function execution error. Errors=1 means that there is a function execution error.

213

AWS Lambda Developer Guide
Using AWS X-Ray

• Lambda emits a data point for Throttles for each invoke request. Throttles=0 means
there is no invocation throttle. Throttles=1 means there is an invocation throttle.

AWS Lambda CloudWatch Dimensions
You can use the dimensions in the following table to reﬁne the metrics returned for your Lambda
functions.
Dimension

Description

FunctionName

Filters the metric data by Lambda function.

Resource

Filters the metric data by Lambda function resource, such as function
version or alias.

ExecutedVersion

Filters the metric data by Lambda function versions. This only applies to
alias invocations.

Using AWS X-Ray
A typical Lambda-based application consists of one or more functions triggered by events such as object
uploads to Amazon S3, Amazon SNS notiﬁcations, and API actions. Once triggered, those functions
usually call downstream resources such as DynamoDB tables or Amazon S3 buckets, or make other
API calls. AWS Lambda leverages Amazon CloudWatch to automatically emit metrics and logs for all
invocations of your function. However, this mechanism might not be convenient for tracing the event
source that invoked your Lambda function, or for tracing downstream calls that your function made. For
a complete overview of how tracing works, see AWS X-Ray.

Tracing Lambda-Based Applications with AWS X-Ray
AWS X-Ray is an AWS service that allows you to detect, analyze, and optimize performance issues with
your AWS Lambda applications. X-Ray collects metadata from the Lambda service and any upstream or
downstream services that make up your application. X-Ray uses this metadata to generate a detailed
service graph that illustrates performance bottlenecks, latency spikes, and other issues that impact the
performance of your Lambda application.
After using the Lambda on the AWS X-Ray Service Map (p. 214)to identify a problematic resource or
component, you can zoom in and view a visual representation of the request. This visual representation
covers the time from when an event source triggers a Lambda function until the function execution has
completed. X-Ray provides you with a breakdown of your function's operations, such as information
regarding downstream calls your Lambda function made to other services. In addition, X-Ray integration
with Lambda provides you with visibility into the AWS Lambda service overhead. It does so by displaying
speciﬁcs such as your request's dwell time and number of invocations.

Note

Only services that currently integrate with X-Ray show as standalone traces, outside of your
Lambda trace. For a list of services that currently support X-Ray, see Integrating AWS X-Ray with
Other AWS Services.

Lambda on the AWS X-Ray Service Map
X-Ray displays three types of nodes on the service map for requests served by Lambda:

214

AWS Lambda Developer Guide
Tracing Lambda-Based Applications with AWS X-Ray

• Lambda service (AWS::Lambda) – This type of node represents the time the request spent in the
Lambda service. Timing starts when Lambda ﬁrst receives the request and ends when the request
leaves the Lambda service.
• Lambda function (AWS::Lambda::Function) – This type of node represents the Lambda function's
execution time.
• Downstream service calls – In this type, each downstream service call from within the Lambda
function is represented by a separate node.
In the diagram following, the nodes represent (from left to right): The Lambda service, the user function,
and a downstream call to Amazon S3:

For more information, see Viewing the Service Map.

Lambda as an AWS X-Ray Trace
From the service map, you can zoom in to see a trace view of your Lambda function. The trace will
display in-depth information regarding your function invocations, represented as segments and
subsegments:
• Lambda service segment – This segment represents diﬀerent information depending on the event
source used to invoke the function:
• Synchronous and stream event sources – The service segment measures the time from when the
Lambda service receives the request/event and ends when the request leaves the Lambda service
(after the ﬁnal invocation for the request is completed).
• Asynchronous – The service segment represents the response time, that is, the time it took the
Lambda service to return a 202 response to the client.
The Lambda service segment can include two types of subsegments:
• Dwell time (asynchronous invocations only) – Represents the time the function spends in the
Lambda service before being invoked. This subsegment starts when the Lambda service receives the
request/event and ends when the Lambda function is invoked for the ﬁrst time.
• Attempt – Represents a single invocation attempt, including any overhead introduced by the
Lambda service. Examples of overhead are time spent initializing the function's code and function
execution time.
• Lambda function segment – Represents execution time for the function for a given invocation
attempt. It starts when the function handler starts executing and ends when the function terminates.
This segment can include three types of subsegments:
• Initialization – The time spent running the initialization code of the function, deﬁned as the
code outside the Lambda function handler or static initializers.
• Downstream calls – Calls made to other AWS services from the Lambda function's code.
• Custom subsegments – Custom subsegments or user annotations that you can add to the Lambda
function segment by using the X-Ray SDK.

215

AWS Lambda Developer Guide
Setting Up AWS X-Ray with Lambda

Note

For each traced invocation, Lambda emits the Lambda service segment and all of its
subsegments. These segments are emitted regardless of the runtime and require you to use the
XRay SDK for AWS API calls.

Setting Up AWS X-Ray with Lambda
Following, you can ﬁnd detailed information on how to set up X-Ray with Lambda.

Before You Begin
To enable tracing on your Lambda function using the Lambda CLI, you must ﬁrst add tracing permissions
to your function's execution role. To do so, take the following steps:
• Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
• Find the execution role for your Lambda function.
• Attach the following managed policy: AWSXrayWriteOnlyAccess
To learn more about these policies, see AWS X-Ray.
If you are changing the tracing mode to active using the Lambda console, tracing permissions are added
automatically, as explained in the next section.

Tracing
The path of a request through your application is tracked with a trace ID. A trace collects all of the
segments generated by a single request, typically an HTTP GET or POST request.
There are two modes of tracing for a Lambda function:
• Pass Through: This is the default setting for all Lambda functions if you have added tracing
permissions to your function's execution role. This approach means the Lambda function is only traced
if X-Ray has been enabled on an upstream service, such as AWS Elastic Beanstalk.
• Active: When a Lambda function has this setting, Lambda automatically samples invocation requests,
based on the sampling algorithm speciﬁed by X-Ray.

Note

X-Ray applies a sampling algorithm to ensure that tracing is eﬃcient, while still providing
a representative sample of the requests that your application serves. The default sampling
algorithm is 1 request per minute, with 5 percent of requests sampled past that limit.
However, if the traﬃc volume to your function is low, you may see an increased rate of
sampling.
You can change the tracing mode for your Lambda function by using either the Lambda Management
Console or the Lambda CreateFunction (p. 368) or UpdateFunctionConﬁguration (p. 472) API actions.
If you use the Lambda console, the following applies:
• When you change a function's tracing mode to active, tracing permissions are automatically
attached to the function's execution role. If you receive an error stating Lambda couldn't add the
AWSXrayWriteOnlyAccess policy to your function's execution role, sign in to the IAM console at
https://console.aws.amazon.com/iam/ and manually add the policy.
• To enable active tracing, go to the Conﬁguration tab your function and select the Enable active
tracing box.

216

AWS Lambda Developer Guide
Emitting Trace Segments from a Lambda Function

If you use the Lambda CreateFunction (p. 368) or UpdateFunctionConﬁguration (p. 472) API actions:
• If you want the tracing mode to be active, set the TracingConfig parameter's Mode property to
Active. Again, any new function has its tracing mode set to PassThrough by default.
• Any new or updated Lambda function has its $LATEST version set to the value you specify.

Note

You receive an error if you haven't added tracing permissions to your function's execution role.
For more information, see Before You Begin (p. 216).

Emitting Trace Segments from a Lambda Function
For each traced invocation, Lambda will emit the Lambda service segment and all of its subsegments.
In addition, Lambda will emit the Lambda function segment and the init subsegment. These segments
will be emitted regardless of the function's runtime, and with no code changes or additional libraries
required. If you want your Lambda function's X-Ray traces to include custom segments, annotations, or
subsegments for downstream calls, you might need to include additional libraries and annotate your
code.
Note that any instrumentation code must be implemented inside the Lambda function handler and not
as part of the initialization code.
The following examples explain how to do this in the supported runtimes:
• Instrumenting Python Code in AWS Lambda (p. 272)
• Instrumenting Node.js Code in AWS Lambda (p. 260)
• Instrumenting Java Code in AWS Lambda (p. 300)
• ??? (p. 313)

217

AWS Lambda Developer Guide
The AWS X-Ray Daemon in the Lambda Environment

The AWS X-Ray Daemon in the Lambda Environment
The AWS X-Ray Daemon is a software application that gathers raw segment data and relays it to the AWS
X-Ray service. The daemon works in conjunction with the AWS X-Ray SDKs so that data sent by the SDKs
can reach the X-Ray service.
When you trace your Lambda function, the X-Ray daemon automatically runs in the Lambda
environment to gather trace data and send it to X-Ray. When tracing, the X-Ray daemon consumes a
maximum of 16 MB or 3 percent of your function's memory allocation. For example, if you allocate
128 MB of memory to your Lambda function, the X-Ray daemon has 16 MB of your function's memory
allocation. If you allocate 1024 MB to your Lambda function, the X-Ray daemon has 31 MB allocated to it
(3 percent). For more information, see The AWS X-Ray Daemon.

Note

Lambda will try to terminate the X-Ray daemon to avoid exceeding your function's memory
limit. For example, assume you have allocated 128 MB to your Lambda function, which means
the X-Ray daemon will have 16 MB allocated to it. That leaves your Lambda function with a
memory allocation of 112 MB. However, if your function exceeds 112 MB, the X-Ray daemon will
be terminated to avoid throwing an out-of-memory error.

Using Environment Variables to Communicate with
AWS X-Ray
AWS Lambda uses environment variables to facilitate communication with the X-Ray daemon and
conﬁgure the X-Ray SDK.
• _X_AMZN_TRACE_ID: Contains the tracing header, which includes the sampling decision, trace
ID, and parent segment ID. (To learn more about these properties, see Tracing Header.) If Lambda
receives a tracing header when your function is invoked, that header will be used to populate the
_X_AMZN_TRACE_ID environment variable. If a tracing header was not received, Lambda will generate
one for you.
• AWS_XRAY_CONTEXT_MISSING: The X-Ray SDK uses this variable to determine its behavior in the
event that your function tries to record X-Ray data, but a tracing header is not available. Lambda sets
this value to LOG_ERROR by default.
• AWS_XRAY_DAEMON_ADDRESS: This environment variable exposes the X-Ray daemon's address in
the following format: IP_ADDRESS:PORT. You can use the X-Ray daemon's address to send trace data
to the X-Ray daemon directly, without using the X-Ray SDK.

Lambda Traces in the AWS X-Ray Console: Examples
The following shows Lambda traces for two diﬀerent Lambda functions. Each trace showcases a trace
structure for a diﬀerent invocation type: asynchronous and synchronous.
• Async – The example following shows an asynchronous Lambda request with one successful
invocation and one downstream call to DynamoDB.

218

AWS Lambda Developer Guide
Lambda Traces in the AWS X-Ray Console: Examples

The Lambda service segment encapsulates the response time, which is the time it took to return a
response (for example, 202) to the client. It includes subsegments for the time spent in the Lambda
service queue (dwell time) and each invocation attempt. (Only one invocation attempt appears in
the example preceding.) Each attempt subsegment in the service segment will have a corresponding
user function segment. In this example, the user function segment contains two subsegments: the
initialization subsegment representing the function's initialization code that is run before the handler,
and a downstream call subsegment representing a ListTables call to DynamoDB.
Status codes and error messages are displayed for each Invocation subsegment and for each
downstream call.
• Synchronous – The example following shows a synchronous request with one downstream call to
Amazon S3.

The Lambda service segment captures the entire time the request spends in the Lambda service. The
service segment will have a corresponding User function segment. In this example, the User function
segment contains a subsegment representing the function's initialization code (code run before the
handler), and a subsegment representing the PutObject call to Amazon S3.

219

AWS Lambda Developer Guide
Lambda Traces in the AWS X-Ray Console: Examples

Note

If you want to trace HTTP calls, you need to use an HTTP client. For more information, see
Tracing Calls to Downstream HTTP Web Services with the X-Ray SDK for Java or Tracing Calls to
Downstream HTTP Web Services with the X-Ray SDK for Node.js .

220

AWS Lambda Developer Guide
Permissions

Administering Lambda-based
Applications
AWS Lambda integrates with many of the administration tools that AWS oﬀers, including AWS tagging,
AWS CloudTrail, and AWS IAM. The sections below oﬀer guidance on how to manage your Lambda-based
applications, including organizing your Lambda based applications using tags, auditing activity on your
AWS using CloudTrail, and introduce you to the AWS Security Model for how to secure your Lambdabased applications. We also discuss an administration task unique to AWS Lambda, which is managing
the concurrent execution behavior of a Lambda function.
The sections below oﬀer guidance on how to organize and track your Lambda function invocations and
introduce you to the AWS Security Model for how to secure your Lambda-based applications:
Topics
• AWS Lambda Permissions (p. 221)
• Logging AWS Lambda API Calls with AWS CloudTrail (p. 235)
• Tagging Lambda Functions (p. 238)
• Managing Concurrency (p. 241)
• Best Practices for Working with AWS Lambda Functions (p. 245)
• AWS Lambda Limits (p. 249)

AWS Lambda Permissions
You can use AWS Identity and Access Management to manage access to the Lambda API and resources
like functions and layers. For users and applications in your account that use Lambda, you manage
permissions in a permissions policy that you can apply to IAM users, groups or roles. To grant permissions
to other accounts or AWS services that use your Lambda resources, you use a policy that applies to the
resource itself.
A Lambda function also has a policy, called an execution role (p. 222), that grants it permission to
access AWS services and resources. At a minimum, your function needs access to Amazon CloudWatch
Logs for log streaming. If you use AWS X-Ray to trace your function (p. 214), or your function access
services with the AWS SDK, you grant it permission to call them in the execution role. Lambda also
uses the execution role to get permission to read from event sources when you use an event source
mapping (p. 64) to trigger your function.

Note

If your function needs network access to a resource like a relational database that is not
accessible through AWS APIs or the internet, conﬁgure it to connect to your VPC (p. 52).
Use resource-based policies (p. 223) to give other accounts and AWS services permission to use your
Lambda resources. Lambda resources include functions, versions, aliases, and layer versions. Each of
these resources has a permissions policy that applies when the resource is accessed, in addition to any
policies that apply to the user. When an AWS service like Amazon S3 calls your Lambda function, the
resource-based policy gives it access.
To manage permissions for users and applications in your accounts, use the managed policies that
Lambda provides (p. 226), or write your own. The Lambda console uses multiple services to get

221

AWS Lambda Developer Guide
Execution Role

information about your function's conﬁguration and triggers. You can the managed policies as-is, or as a
starting point for more restrictive policies.
You can restrict user permissions by the resource an action aﬀects and, in some cases, by additional
conditions. For example, you can specify a pattern for the Amazon Resource Name (ARN) of a function
that requires a user to include their username in the name of functions that they create. Additionally, you
can add a condition that requires that the user conﬁgure their function to use a speciﬁc layer to pull in
logging software. See Resources and Conditions (p. 231) for the resources and conditions supported by
each action.
For more information about IAM, see What Is IAM? in the IAM User Guide.
Topics
• AWS Lambda Execution Role (p. 222)
• Using Resource-Based Policies for AWS Lambda (p. 223)
• Identity-Based IAM Policies for AWS Lambda (p. 226)
• Resources and Conditions for Lambda Actions (p. 231)

AWS Lambda Execution Role
Each Lambda function has an IAM role associated with it. You specify the role when you create your
Lambda function. Permissions you grant to this role determine what AWS Lambda can do when it
assumes the role. There are two types of permissions that you grant to the IAM role:
• If your Lambda function code accesses other AWS resources, such as reading an object from an S3
bucket or writing logs to CloudWatch Logs, you need to grant permissions for relevant Amazon S3 and
CloudWatch actions to the role.
• If the event source is poll-based (Amazon Kinesis Data Streams, DynamoDB, Amazon SQS), AWS
Lambda polls these resources on your behalf. AWS Lambda needs permissions to poll either the stream
or queue to read new records. To enable this, you need to grant AWS Lambda permissions to access
the new records. In turn, AWS Lambda will invoke any Lambda function subscribed to this event source
to process the event.
For more information about IAM roles, see Roles (Delegation and Federation) in the IAM User Guide.

Important

The user that creates the IAM role is, in eﬀect, passing permissions to AWS Lambda to assume
this role. This requires the user to have permissions for the iam:PassRole action.
To simplify the process for creating an execution role, AWS Lambda provides the following AWS
managed permissions policies that you can use. These policies include common permissions for speciﬁc
scenarios:
• AWSLambdaBasicExecutionRole – Grants permissions only for the Amazon CloudWatch Logs actions
to write logs. You can use this policy if your Lambda function does not access any other AWS resources
except writing logs.
• AWSLambdaKinesisExecutionRole – Grants permissions for Amazon Kinesis Data Streams actions, and
CloudWatch Logs actions. If you are writing a Lambda function to process Kinesis stream events you
can attach this permissions policy.
• AWSLambdaDynamoDBExecutionRole – Grants permissions for DynamoDB streams actions and
CloudWatch Logs actions. If you are writing a Lambda function to process DynamoDB stream events
you can attach this permissions policy.

222

AWS Lambda Developer Guide
Resource-Based Policies

• AWSLambdaVPCAccessExecutionRole – Grants permissions for Amazon Elastic Compute Cloud
(Amazon EC2) actions to manage elastic network interfaces (ENIs). If you are writing a Lambda
function to access resources in a VPC, you can attach this permissions policy. The policy also grants
permissions for CloudWatch Logs actions to write logs.
In addition to the managed policies, the Lambda console provides templates for creating a custom policy
that has the permissions related to additional use cases. When you create a function, you can choose
to create a new execution role with permissions from one or more templates. These templates are also
applied automatically when you create a function from a blueprint, or when you conﬁgure options that
require access to other services. Example templates are available in this guide's GitHub repository.

Using Resource-Based Policies for AWS Lambda
A Lambda function is one of the resources in AWS Lambda. You can add permissions to the policy
associated with a Lambda function. Permissions policies attached to Lambda functions are referred to
as resource-based policies. You use Lambda function policies to manage Lambda function invocation
permissions.
Lambda function policies are primarily used when you are setting up an event source in AWS Lambda
to grant a service or an event source permissions to invoke your Lambda function. An exception to
this is when an event source (for example, Amazon DynamoDB or Kinesis) uses the pull model, where
permissions are managed in the Lambda function execution role instead. For more information, see AWS
Lambda Event Source Mapping (p. 64).
Lambda function policies also make it easy to grant cross-account permissions to invoke your Lambda
function. Suppose you want to grant cross-account permissions (for example, permissions to Amazon S3)
to invoke your Lambda function. Instead of creating an IAM role to grant cross-account permissions, you
can add the relevant permissions in a Lambda function policy.

Note

If the custom application and the Lambda function it invokes belong to the same AWS account,
you don't need to grant explicit permissions using the policy attached to the Lambda function.
AWS Lambda provides the following API operations to manage a permissions policy associated with a
Lambda function:
• AddPermission (p. 356)
• GetPolicy (p. 408)
• RemovePermission (p. 451)

Note

The AWS Lambda console is the easiest way to manage event sources and their permissions in
a Lambda function policy. If the AWS service console for the event source supports conﬁguring
event source mapping, you can use that console too. As you conﬁgure new event sources or
modify existing event sources, the console automatically modiﬁes the permissions policy
associated with the Lambda function.
You can use the console to view your function policy under the Conﬁguration tab and then choosing the
key icon. The console doesn't support directly modifying permissions in a function policy. You must use
either the AWS CLI or the AWS SDKs.
Examples
• Example 1: Allow Amazon S3 to Invoke a Lambda Function (p. 224)
• Example 2: Allow Amazon API Gateway to Invoke a Lambda Function (p. 224)

223

AWS Lambda Developer Guide
Resource-Based Policies

• Example 3: Allow a User Application Created by Another AWS Account to Invoke a Lambda Function
(Cross-Account Scenario) (p. 225)
• Example 4: Retrieve a Lambda Function Policy (p. 225)
• Example 5: Remove Permissions from a Lambda Function Policy (p. 225)

Example 1: Allow Amazon S3 to Invoke a Lambda Function
To grant Amazon S3 permission to invoke a Lambda function, you conﬁgure permissions as follows:
• Specify s3.amazonaws.com as the principal value.
• Specify lambda:InvokeFunction as the action for which you are granting permissions.
To ensure that the event is generated from a speciﬁc bucket that is owned by a speciﬁc AWS account, you
also specify the following:
• Specify the bucket ARN as the source-arn value to restrict events from a speciﬁc bucket.
• Specify the AWS account ID that owns the bucket, to ensure that the named bucket is owned by the
account.
The following example AWS CLI command adds a permission to the helloworld Lambda function
policy granting Amazon S3 permissions to invoke the function.
aws lambda add-permission --function-name helloworld --statement-id s3 --principal
s3.amazonaws.com \
--action lambda:InvokeFunction --source-arn arn:aws:s3:::examplebucket --source-account
111111111111

The example assumes that the adminuser (who has full permissions) is adding this permission.
Therefore, the --profile parameter speciﬁes the adminuser proﬁle.
In response, AWS Lambda returns the following JSON code. The Statement value is a JSON string
version of the statement added to the Lambda function policy.
{

"Statement": "{\"Condition\":{\"StringEquals\":{\"AWS:SourceAccount\":
\"111111111111\"},
\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:s3:::examplebucket\"}},
\"Action\":[\"lambda:InvokeFunction\"],
\"Resource\":\"arn:aws:lambda:us-west-2:111111111111:function:helloworld
\",
\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"s3.amazonaws.com\"},
\"Sid\":\"1\"}"
}

For information about the push model, see AWS Lambda Event Source Mapping (p. 64).

Example 2: Allow Amazon API Gateway to Invoke a Lambda
Function
To grant permissions to allow Amazon API Gateway to invoke a Lambda function, do the following:
• Specify apigateway.amazonaws.com as the principal value.
• Specify lambda:InvokeFunction as the action for which you are granting permissions.
• Specify the API Gateway endpoint ARN as the source-arn value.

224

AWS Lambda Developer Guide
Resource-Based Policies

The following example AWS CLI command adds a permission to the helloworld Lambda function
policy granting API Gateway permissions to invoke the function.
aws lambda add-permission --function-name helloworld --statement-id apigateway --principal
apigateway.amazonaws.com --action lambda:InvokeFunction \
--source-arn arn:aws:execute-api:region:account-id:api-id/stage/method/resource-path

In response, AWS Lambda returns the following JSON code. The Statement value is a JSON string
version of the statement added to the Lambda function policy.
{

"Statement": "{\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:apigateway:useast-1::my-api-id:/test/petstorewalkthrough/pets\"}},
\"Action\":[\"lambda:InvokeFunction\"],
\"Resource\":\"arn:aws:lambda:us-west-2:account-id:function:helloworld\",
\"Effect\":\"Allow\",
\"Principal\":{\"Service\":\"apigateway.amazonaws.com\"},
\"Sid\":\"5\"}"
}

Example 3: Allow a User Application Created by Another AWS
Account to Invoke a Lambda Function (Cross-Account Scenario)
To grant permissions to another AWS account (that is, to create a cross-account scenario), you specify the
AWS account ID as the principal value as shown in the following AWS CLI command:
aws lambda add-permission --function-name helloworld --statement-id 3 --principal
111111111111 --action lambda:InvokeFunction

In response, AWS Lambda returns the following JSON code. The Statement value is a JSON string
version of the statement added to the Lambda function policy.
{
\",

}

"Statement": "{\"Action\":[\"lambda:InvokeFunction\"],
\"Resource\":\"arn:aws:lambda:us-west-2:account-id:function:helloworld
\"Effect\":\"Allow\",
\"Principal\":{\"AWS\":\"account-id\"},
\"Sid\":\"3\"}"

Example 4: Retrieve a Lambda Function Policy
To retrieve your Lambda function policy, you use the get-policy command:
aws lambda get-policy --function-name example

Example 5: Remove Permissions from a Lambda Function Policy
To remove permissions from your Lambda function policy, you use the remove-permission command,
specifying the function name and statement ID:
aws lambda remove-permission --function-name example --statement-id s3

225

AWS Lambda Developer Guide
User Policies

Identity-Based IAM Policies for AWS Lambda
You can attach policies to IAM identities. For example, you can do the following:
• Attach a permissions policy to a user or a group in your account – An account administrator can
use a permissions policy that is associated with a particular user to grant permissions for that user to
create a Lambda function.
• Attach a permissions policy to a role (grant cross-account permissions) – You can attach an
identity-based permissions policy to an IAM role to grant cross-account permissions. For example,
the administrator in Account A can create a role to grant cross-account permissions to another AWS
account (for example, Account B) or an AWS service as follows:
1. Account A administrator creates an IAM role and attaches a permissions policy to the role that
grants permissions on resources in Account A.
2. Account A administrator attaches a trust policy to the role identifying Account B as the principal
who can assume the role.
3. Account B administrator can then delegate permissions to assume the role to any users in Account
B. Doing this allows users in Account B to create or access resources in Account A. The principal
in the trust policy can also be an AWS service principal if you want to grant an AWS service
permissions to assume the role.
For more information about using IAM to delegate permissions, see Access Management in the IAM
User Guide.
The following shows an example of a permissions policy.
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "CreateFunctionPermissions",
"Effect": "Allow",
"Action": [
"lambda:CreateFunction"
],
"Resource": "*"
},
{
"Sid": "PermissionToPassAnyRole",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws:iam::account-id:role/*"
}
]

The policy has two statements:
• The ﬁrst statement grants permissions for the AWS Lambda action (lambda:CreateFunction)
on a resource by using the Amazon Resource Name (ARN) for the Lambda function. Currently, AWS
Lambda doesn't support permissions for this particular action at the resource-level. Therefore, the
policy speciﬁes a wildcard character (*) as the Resource value.
• The second statement grants permissions for the IAM action (iam:PassRole) on IAM roles. The
wildcard character (*) at the end of the Resource value means that the statement allows permission
for the iam:PassRole action on any IAM role. To limit this permission to a speciﬁc role, replace the
wildcard character (*) in the resource ARN with the speciﬁc role name.

226

AWS Lambda Developer Guide
User Policies

The policy doesn't specify the Principal element because in an identity-based policy you don't specify
the principal who gets the permission. When you attach policy to a user, the user is the implicit principal.
When you attach a permission policy to an IAM role, the principal identiﬁed in the role's trust policy gets
the permissions.
If you use the Lambda console to conﬁgure triggers for your function, you need access to use the AWS
service that invokes your function. For example, to conﬁgure an Amazon S3 trigger, you need permission
to Amazon S3 actions to manage bucket notiﬁcations. Many of these permissions are included in the
AWSLambdaFullAccess managed policy. Example policies are available in this guide's GitHub repository.

AWS Managed Policies for AWS Lambda
AWS addresses many common use cases by providing standalone IAM policies that are created and
administered by AWS. Managed policies grant necessary permissions for common use cases so you can
avoid having to investigate what permissions are needed. For more information, see AWS Managed
Policies in the IAM User Guide.
The following AWS managed policies, which you can attach to users in your account, are speciﬁc to AWS
Lambda and are grouped by use case scenario:
• AWSLambdaReadOnlyAccess – Grants read-only access to AWS Lambda resources. Note that this
policy doesn't grant permission for the lambda:InvokeFunction action. If you want a user to invoke
a Lambda function, you can also attach the AWSLambdaRole AWS managed policy.
• AWSLambdaFullAccess – Grants full access to AWS Lambda resources.
• AWSLambdaRole – Grants permissions to invoke any Lambda function.
You can review these permissions policies by signing in to the IAM console and searching for speciﬁc
policies there.
In addition, there are other AWS-managed policies that are suitable for use with IAM role (execution role)
you specify at the time of creating a Lambda function. For more information, see AWS Lambda Execution
Role (p. 222).
You can also create your own custom IAM policies to allow permissions for AWS Lambda API actions
and resources. You can attach these custom policies to the IAM users or groups that require those
permissions or to custom execution roles (IAM roles) that you create for your Lambda functions.

Customer Managed Policy Examples
The examples in this section provide a group of sample policies that you can attach to a user. If you are
new to creating policies, we recommend that you ﬁrst create an IAM user in your account and attach the
policies to the user in sequence, as outlined in the steps in this section.
You can use the console to verify the eﬀects of each policy as you attach the policy to the user. Initially,
the user doesn't have permissions and the user won't be able to do anything in the console. As you
attach policies to the user, you can verify that the user can perform various actions in the console.
For each AWS Lambda resource, the service deﬁnes a set of API operations. To grant permissions
for these API operations, Lambda deﬁnes a set of actions that you can specify in a policy. Note that,
performing an API operation can require permissions for more than one action. When granting
permissions for speciﬁc actions, you also identify the resource on which the actions are allowed or
denied.
The following are the most basic policy elements:
• Resource – In a policy, you use an Amazon Resource Name (ARN) to identify the resource to which the
policy applies.

227

AWS Lambda Developer Guide
User Policies

• Action – You use action keywords to identify resource operations that you want to allow or deny.
For example, the lambda:InvokeFunction permission allows the user permissions to perform the
AWS Lambda Invoke action. For other actions, the name of the permission matches the name of the
action.
• Eﬀect – You specify the eﬀect when the user requests the speciﬁc action—this can be either allow or
deny. If you don't explicitly grant access to a resource, access is implicitly denied. You can also explicitly
deny access to a resource, which you might do to make sure that a user cannot access it, even if a
diﬀerent policy grants access.
• Principal – In identity-based policies, the user that the policy is attached to is the implicit principal. For
resource-based policies, you specify the user, account, service, or other entity that you want to receive
permissions.
Example Steps
• Step 1: Create an IAM User (p. 228)
• Step 2: Allow a User to List Lambda Functions (p. 228)
• Step 3: Allow a User to View Details of a Lambda Function (p. 228)
• Step 4: Allow a User to Invoke a Lambda Function (p. 229)
• Step 5: Allow a User to Monitor a Lambda Function and View CloudWatch Logs (p. 229)
• Step 6: Allow a User to Create a Lambda Function (p. 230)

Step 1: Create an IAM User
First, you need to create an IAM user, add the user to an IAM group with administrative permissions, and
then grant administrative permissions to the IAM user that you created. You can then access AWS using a
special URL and that IAM user's credentials.
For instructions, see Creating Your First IAM User and Administrators Group in the IAM User Guide.

Step 2: Allow a User to List Lambda Functions
An IAM user in your account must have permissions for the lambda:ListFunctions action before the
user can see anything in the console. When you grant these permissions, the console can show the list of
Lambda functions in the AWS account created in the speciﬁc AWS Region the user belongs to.
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "ListExistingFunctions",
"Effect": "Allow",
"Action": [
"lambda:ListFunctions"
],
"Resource": "*"
}
]

Step 3: Allow a User to View Details of a Lambda Function
A user can select a Lambda function and view details of the function (such as aliases, versions, and
other conﬁguration information), provided that the user has permissions for the following AWS Lambda
actions:

228

AWS Lambda Developer Guide
User Policies
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "DisplayFunctionDetailsPermissions",
"Effect": "Allow",
"Action": [
"lambda:ListVersionsByFunction",
"lambda:ListAliases",
"lambda:GetFunction",
"lambda:GetFunctionConfiguration",
"lambda:ListEventSourceMappings",
"lambda:GetPolicy"
],
"Resource": "*"
}
]

Step 4: Allow a User to Invoke a Lambda Function
If you want to allow a user permissions to manually invoke a function, you need to grant permissions for
the lambda:InvokeFunction action, as shown following:
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "InvokePermission",
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": "*"
}
]

Step 5: Allow a User to Monitor a Lambda Function and View CloudWatch Logs
When a user invokes a Lambda function, AWS Lambda executes it and returns results. The user needs
additional permissions to monitor the Lambda function.
To enable the user to see the Lambda function's CloudWatch metrics on the console's Monitoring tab, or
on the grid view on the console home page, you must grant the following permissions:
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "CloudWatchPermission",
"Effect": "Allow",
"Action": [
"cloudwatch:GetMetricStatistics"
],
"Resource": "*"
}
]

To enable a user to click the links to CloudWatch Logs in the AWS Lambda console and view log output
in CloudWatch Logs, you must grant the following permissions:

229

AWS Lambda Developer Guide
User Policies

{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "CloudWatchLogsPerms",
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents"

]

}

],
"Resource": "arn:aws:logs:region:account-id:log-group:/aws/lambda/*"

Step 6: Allow a User to Create a Lambda Function
If you want a user to be able to create a Lambda function, you must grant the following permissions. The
permissions for IAM-related actions are required because when a user creates a Lambda function, the
user needs to select an IAM execution role, which AWS Lambda assumes to execute the Lambda function.
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "ListExistingRolesAndPolicies",
"Effect": "Allow",
"Action": [
"iam:ListRolePolicies",
"iam:ListRoles"
],
"Resource": "*"
},
{
"Sid": "CreateFunctionPermissions",
"Effect": "Allow",
"Action": [
"lambda:CreateFunction"
],
"Resource": "*"
},
{
"Sid": "PermissionToPassAnyRole",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws:iam::account-id:role/*"
}
]

If you want a user to be able to create an IAM role when the user is creating a Lambda function, the user
needs permissions to perform the iam:PutRolePolicy action, as shown following:
{

"Sid": "CreateARole",
"Effect": "Allow",
"Action": [
"iam:CreateRole",

230

AWS Lambda Developer Guide
Resources and Conditions
"iam:CreatePolicy",
"iam:PutRolePolicy
"iam:AttachRolePolicy"

}

],
"Resource": "arn:aws:iam::account-id:role/*"

Important

Each IAM role has a permissions policy attached to it, which grants speciﬁc permissions to the
role. Regardless of whether the user creates a new role or uses an existing role, the user must
have permissions for all of the actions granted in the permissions policy associated with the
role. You must grant the user additional permissions accordingly.

Resources and Conditions for Lambda Actions
You can restrict the scope of a user's permissions by specifying resources and conditions in an IAM policy.
Each API action supports a combination of resource and condition types that varies depending on the
behavior of the action.
Every IAM policy statement grants permission to an action performed on a resource. When the action
doesn't act on a named resource, or when you grant permission to perform the action on all resources,
the value of the resource in the policy is a wildcard (*). For many APIs, you can restrict the resources that
a user can modify by specifying the Amazon Resource Name (ARN) of a resource, or an ARN pattern that
matches multiple resources.
To restrict permissions by resource, specify the resource by ARN.

Lambda Resource ARN Format
• Function – arn:aws:lambda:us-west-2:123456789012:function:my-function
• Function version – arn:aws:lambda:us-west-2:123456789012:function:my-function:1
• Function alias – arn:aws:lambda:us-west-2:123456789012:function:my-function:TEST
• Event source mapping – arn:aws:lambda:us-west-2:123456789012:event-sourcemapping:fa123456-14a1-4fd2-9fec-83de64ad683de6d47
• Layer – arn:aws:lambda:us-west-2:123456789012:layer:my-layer
• Layer version – arn:aws:lambda:us-west-2:123456789012:layer:my-layer:1
For example, the following policy allows a user in account 123456789012 to invoke a function named
my-function in the US West (Oregon) region.

Example Invoke a function
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "Invoke",
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": "arn:aws:lambda:us-west-2:123456789012:function:my-function"
}
]

231

AWS Lambda Developer Guide
Resources and Conditions

Note that this is a special case where the action identiﬁer (lambda:InvokeFunction) diﬀers from the
API operation (Invoke (p. 410)). For other actions, the action identiﬁer is the operation name preﬁxed
by lambda:.
Conditions are an optional policy element that applies additional logic to determine if an action is
allowed. In addition to common conditions supported by all actions, Lambda deﬁnes condition types
that you can use to restrict the values of additional parameters on some actions.
For example, the lambda:Principal condition lets you restrict the service or account to whom a user
can grant invocation access on a function's resource-based policy. The following policy lets a user grant
permission to SNS topics to invoke a function named test.

Example Manage function policy permissions
{

}

"Version": "2012-10-17",
"Statement": [
{
"Sid": "ManageFunctionPolicy",
"Effect": "Allow",
"Action": [
"lambda:AddPermission",
"lambda:RemovePermission"
],
"Resource": "arn:aws:lambda:us-west-2:123456789012:function:test:*",
"Condition": {
"StringEquals": {
"lambda:Principal": "sns.amazonaws.com"
}
}
}
]

The condition requires that the principal is Amazon SNS and not another service or account. The resource
pattern requires that the function name is test and includes a version number or alias. For example,
test:v1.
Sections
• Functions (p. 232)
• Event Source Mappings (p. 233)
• Layers (p. 234)

Functions
Actions that operate on a function can be restricted to a speciﬁc function by function, version, or alias
ARN, as described in the following table. Actions that do not support resource restrictions can only
granted for all resources (*).

Functions
Action

Resource

Condition

AddPermission (p. 356)

Function

lambda:Principal

RemovePermission (p. 451)

Function version
Function alias

232

AWS Lambda Developer Guide
Resources and Conditions

Action

Resource

Condition

Invoke (p. 410)

Function

None

Permission: lambda:InvokeFunction

Function version
Function alias

CreateFunction (p. 368)

Function

lambda:Layer

Function

None

*

None

UpdateFunctionConﬁguration (p. 472)
CreateAlias (p. 360)
DeleteAlias (p. 376)
DeleteFunction (p. 381)
DeleteFunctionConcurrency (p. 383)
GetAlias (p. 389)
GetFunction (p. 395)
GetFunctionConﬁguration (p. 398)
GetPolicy (p. 408)
ListAliases (p. 417)
ListVersionsByFunction (p. 433)
PublishVersion (p. 440)
PutFunctionConcurrency (p. 446)
UpdateAlias (p. 458)
UpdateFunctionCode (p. 466)
GetAccountSettings (p. 387)
ListFunctions (p. 423)
ListTags (p. 431)
TagResource (p. 454)
UntagResource (p. 456)

Event Source Mappings
For event source mappings, delete and update permissions can be restricted to a speciﬁc event source.
The lambda:FunctionArn condition lets you restrict which functions a user can conﬁgure an event
source to invoke.
The following policy allows a user to manage event source mappings only if they invoke a function
named my-function.

233

AWS Lambda Developer Guide
Resources and Conditions

Example Manage event sources for a function
{

"Version": "2012-10-17",
"Statement": [
{
"Sid": "EventSourceMappings",
"Effect": "Allow",
"Action": [
"lambda:CreateEventSourceMapping",
"lambda:UpdateEventSourceMapping",
"lambda:DeleteEventSourceMapping"
],
"Resource": "*",
"Condition": {"StringEquals": {"lambda:FunctionArn":
"arn:aws:lambda:*:123456789012:function:my-function"}}
}
]

}

For these actions, the resource is the event source mapping, so Lambda provides a condition that lets you
restrict permission based on the function that the event source mapping invokes.

Event Source Mappings
Action

Resource

Condition

DeleteEventSourceMapping (p. 378)

Event source mapping

lambda:FunctionArn

CreateEventSourceMapping (p. 364)

*

lambda:FunctionArn

GetEventSourceMapping (p. 392)

*

None

UpdateEventSourceMapping (p. 462)

ListEventSourceMappings (p. 420)

Layers
Layer actions let you restrict the layers that a user can manage or use with a function. Actions related
to layer use and permissions act on a version of a layer, while PublishLayerVersion acts on a layer
name. Either can be used with wildcards to restrict the layers that a user can work with by name.
The following policy grants a user permission to publish layers and use them with functions. The
resource patterns allow the user to work in any region and with any layer version, as long as the name of
the layer starts with test-.

Example Layer Policy
{

"Version": "2012-10-17",
"Statement": [
{
"Sid": "Publish",
"Effect": "Allow",
"Action": [
"lambda:PublishLayerVersion"
],
"Resource": "arn:aws:lambda:*:123456789012:layer:test-*"
},

234

AWS Lambda Developer Guide
CloudTrail
{

}

]

}

"Sid": "Use",
"Effect": "Allow",
"Action": [
"lambda:GetLayerVersion"
],
"Resource": "arn:aws:lambda:*:123456789012:layer:test-*:*"

Layers
Action

Resource

Condition

AddLayerVersionPermission (p. 352)

Layer version

None

PublishLayerVersion (p. 436)

Layer

None

ListLayers (p. 426)

*

None

RemoveLayerVersionPermission (p. 449)
GetLayerVersion (p. 403)
GetLayerVersionPolicy (p. 406)
DeleteLayerVersion (p. 385)

ListLayerVersions (p. 428)

Logging AWS Lambda API Calls with AWS
CloudTrail
AWS Lambda is integrated with AWS CloudTrail, a service that provides a record of actions taken by a
user, role, or an AWS service in AWS Lambda. CloudTrail captures API calls for AWS Lambda as events.
The calls captured include calls from the AWS Lambda console and code calls to the AWS Lambda API
operations. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3
bucket, including events for AWS Lambda. If you don't conﬁgure a trail, you can still view the most recent
events in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can
determine the request that was made to AWS Lambda, the IP address from which the request was made,
who made the request, when it was made, and additional details.
To learn more about CloudTrail, including how to conﬁgure and enable it, see the AWS CloudTrail User
Guide.

AWS Lambda Information in CloudTrail
CloudTrail is enabled on your AWS account when you create the account. When supported event activity
occurs in AWS Lambda, that activity is recorded in a CloudTrail event along with other AWS service
events in Event history. You can view, search, and download recent events in your AWS account. For
more information, see Viewing Events with CloudTrail Event History.
For an ongoing record of events in your AWS account, including events for AWS Lambda, create a trail.
A trail enables CloudTrail to deliver log ﬁles to an Amazon S3 bucket. By default, when you create a
trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the

235

AWS Lambda Developer Guide
Understanding AWS Lambda Log File Entries

AWS partition and delivers the log ﬁles to the Amazon S3 bucket that you specify. Additionally, you can
conﬁgure other AWS services to further analyze and act upon the event data collected in CloudTrail logs.
For more information, see the following:
• Overview for Creating a Trail
• CloudTrail Supported Services and Integrations
• Conﬁguring Amazon SNS Notiﬁcations for CloudTrail
• Receiving CloudTrail Log Files from Multiple Regions and Receiving CloudTrail Log Files from Multiple
Accounts
AWS Lambda supports logging the following actions as events in CloudTrail log ﬁles:
• AddPermission (p. 356)
• CreateEventSourceMapping (p. 364)
• CreateFunction (p. 368)
(The ZipFile parameter is omitted from the CloudTrail logs for CreateFunction.)
• DeleteEventSourceMapping (p. 378)
• DeleteFunction (p. 381)
• GetEventSourceMapping (p. 392)
• GetFunction (p. 395)
• GetFunctionConﬁguration (p. 398)
• GetPolicy (p. 408)
• ListEventSourceMappings (p. 420)
• ListFunctions (p. 423)
• RemovePermission (p. 451)
• UpdateEventSourceMapping (p. 462)
• UpdateFunctionCode (p. 466)
(The ZipFile parameter is omitted from the CloudTrail logs for UpdateFunctionCode.)
• UpdateFunctionConﬁguration (p. 472)
Every log entry contains information about who generated the request. The user identity information
in the log helps you determine whether the request was made with root or IAM user credentials,
with temporary security credentials for a role or federated user, or by another AWS service. For more
information, see the userIdentity ﬁeld in the CloudTrail Event Reference.
You can store your log ﬁles in your bucket for as long as you want, but you can also deﬁne Amazon S3
lifecycle rules to archive or delete log ﬁles automatically. By default, your log ﬁles are encrypted by using
Amazon S3 server-side encryption (SSE).
You can choose to have CloudTrail publish Amazon SNS notiﬁcations when new log ﬁles are delivered if
you want to take quick action upon log ﬁle delivery. For more information, see Conﬁguring Amazon SNS
Notiﬁcations for CloudTrail.
You can also aggregate AWS Lambda log ﬁles from multiple AWS regions and multiple AWS accounts
into a single S3 bucket. For more information, see Working with CloudTrail Log Files.

Understanding AWS Lambda Log File Entries
CloudTrail log ﬁles contain one or more log entries where each entry is made up of multiple JSONformatted events. A log entry represents a single request from any source and includes information

236

AWS Lambda Developer Guide
Understanding AWS Lambda Log File Entries

about the requested action, any parameters, the date and time of the action, and so on. The log entries
are not guaranteed to be in any particular order. That is, they are not an ordered stack trace of the public
API calls.
The following example shows CloudTrail log entries for the GetFunction and DeleteFunction
actions.
{

"Records": [
{
"eventVersion": "1.03",
"userIdentity": {
"type": "IAMUser",
"principalId": "A1B2C3D4E5F6G7EXAMPLE",
"arn": "arn:aws:iam::999999999999:user/myUserName",
"accountId": "999999999999",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "myUserName"
},
"eventTime": "2015-03-18T19:03:36Z",
"eventSource": "lambda.amazonaws.com",
"eventName": "GetFunction",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "Python-httplib2/0.8 (gzip)",
"errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:iam::999999999999:user/myUserName" is
not authorized to perform: lambda:GetFunction on resource: arn:aws:lambda:uswest-2:999999999999:function:other-acct-function",
"requestParameters": null,
"responseElements": null,
"requestID": "7aebcd0f-cda1-11e4-aaa2-e356da31e4ff",
"eventID": "e92a3e85-8ecd-4d23-8074-843aabfe89bf",
"eventType": "AwsApiCall",
"recipientAccountId": "999999999999"
},
{
"eventVersion": "1.03",
"userIdentity": {
"type": "IAMUser",
"principalId": "A1B2C3D4E5F6G7EXAMPLE",
"arn": "arn:aws:iam::999999999999:user/myUserName",
"accountId": "999999999999",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "myUserName"
},
"eventTime": "2015-03-18T19:04:42Z",
"eventSource": "lambda.amazonaws.com",
"eventName": "DeleteFunction",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "Python-httplib2/0.8 (gzip)",
"requestParameters": {
"functionName": "basic-node-task"
},
"responseElements": null,
"requestID": "a2198ecc-cda1-11e4-aaa2-e356da31e4ff",
"eventID": "20b84ce5-730f-482e-b2b2-e8fcc87ceb22",
"eventType": "AwsApiCall",
"recipientAccountId": "999999999999"
}
]
}

237

AWS Lambda Developer Guide
Using CloudTrail to Track Function Invocations

Note

The eventName may include date and version information, such as "GetFunction20150331",
but it is still referring to the same public API. For more information, see Services Supported by
CloudTrail Event History in the AWS CloudTrail User Guide.

Using CloudTrail to Track Function Invocations
CloudTrail also logs data events. You can turn on data event logging so that you log an event every time
Lambda functions are invoked. This helps you understand what identities are invoking the functions and
the frequency of their invocations. You can do this using the AWS CloudTrail console or Invoke (p. 410)
CLI operation. For more information on this option, see Logging Data and Management Events for Trails.

Tagging Lambda Functions
Lambda functions can span multiple applications across separate regions. To simplify the process
of tracking the frequency and cost of each function invocation, you can use tags. Tags are key-value
pairs that you attach to AWS resources to better organize them. They are particularly useful when you
have many resources of the same type, which in the case of AWS Lambda, is a function. By using tags,
customers with hundreds of Lambda functions can easily access and analyze a speciﬁc set by ﬁltering on
those that contain the same tag. Two of the key advantages of tagging your Lambda functions are:
• Grouping and Filtering: By applying tags, you can use the Lambda console or CLI to isolate a list of
Lambda functions contained within a speciﬁc application or billing department. For more information,
see Filtering on Tagged Lambda Functions (p. 240).
• Cost allocation: Because Lambda's support for tagging is integrated with AWS Billing, you can
break down bills into dynamic categories and map functions to speciﬁc cost centers. For example,
if you tag all Lambda functions with a "Department" key, then all AWS Lambda costs can be broken
down by department. You can then provide an individual department value, such "Department 1" or
"Department 2" to direct the function invocation cost to the appropriate cost center. Cost allocation is
surfaced via detailed billing reports, making it easier for you to categorize and track your AWS costs.
Topics
• Tagging Lambda Functions for Billing (p. 238)
• Applying Tags to Lambda Functions (p. 239)
• Filtering on Tagged Lambda Functions (p. 240)
• Tag Restrictions (p. 241)

Tagging Lambda Functions for Billing
You can use tags to organize your AWS bill to reﬂect your own cost structure. To do this, you can add tag
keys whose values will be included in the cost allocation report. For more information about setting up a
cost allocation report that includes the tag keys you select to be included as line items in the report, see
The Monthly Cost Allocation Report in About AWS Account Billing.
To see the cost of your combined resources, you can organize your billing information based on functions
that have the same tag key values. For example, you can tag several Lambda functions with a speciﬁc
application name, and then organize your billing information to see the total cost of that application
across several services. For more information, see Using Cost Allocation Tags in the AWS Billing and Cost
Management User Guide.

238

AWS Lambda Developer Guide
Applying Tags to Lambda Functions

Important

In AWS Lambda the only resource that can be tagged is a function. You cannot tag an alias or
a speciﬁc function version. Any invocation of a function's alias or version will be billed as an
invocation of the original function.

Applying Tags to Lambda Functions
How you tag your Lambda functions depends on how you create the function. You can apply them using
the Lambda console or CLI, as explained in the following sections:
• Applying Tags to Lambda Functions Using the Console (p. 239)
• Applying Tags to Lambda Functions Using the CLI (p. 239)

Applying Tags to Lambda Functions Using the Console
You can add tags to your function under the Tags section in the conﬁguration tab.

To remove tags from an existing function, open the function, choose the Tags section and then choose
the Remove button next to key-value pair.

Applying Tags to Lambda Functions Using the CLI
When you create a new Lambda function using the CreateFunction (p. 368) command, you can add tags
by populating the Tags parameter. Specify multiple tag values by enclosing them in quotation marks, as
shown below:

Note

If you have not already created the adminuser proﬁle, see Set Up the AWS CLI (p. 7).
$ aws lambda create-function \
--region region \
--function-name function-name
--role role-arn \
--handler handler-name \
--runtime runtime-value \
--runtime runtime \
--tags "DEPARTMENT=Department A, Department B" \
--profile adminuser \
--timeout 10 \
--memory-size 1024

239

AWS Lambda Developer Guide
Filtering on Tagged Lambda Functions

To apply or add more tags to an existing function, you can use the TagResource (p. 454) API and supply
it with the Lambda function ARN (Amazon Resource Name) along with the key-value pairs that comprise
your tags.
$ aws lambda tag-resource \
--resource function arn \
--tags DEPARTMENT="Department C, Department D"

Conversely, if you want to remove any or all tags from a Lambda function, you use the
UntagResource (p. 456) API and again supply the function ARN (Amazon Resource Name), along with a
list of tag keys to be removed from the function.
$ aws lambda untag-resource \
--resource function arn \
--tagkeys list of tag keys to be removed

Filtering on Tagged Lambda Functions
Once you have grouped your Lambda functions by using tags, you can leverage the ﬁltering capabilities
provided by the Lambda console or the AWS CLI to view them based on your speciﬁc requirements.

Filtering Lambda Functions Using the Console
The Lambda console contains a search ﬁeld that allows you to ﬁlter the list of functions based on a
speciﬁed set of function attributes, including Tags. Suppose you have two functions named MyFunction
and MyFunction2 that have a Tags key called Department. To view those functions, choose the search
ﬁeld and notice the automatic ﬁltering that includes a list of the Tags keys:

Choose the Department key. Lambda will return any function that contains that key.
Now suppose that the key value of the MyFunction tag is "Department A" and the key value of
MyFunction2 is "Department B". You can narrow your search by choosing the value of the Department
key, in this case Department A, as shown below.

240

AWS Lambda Developer Guide
Tag Restrictions

This will return only MyFunction.
You can further narrow your search by including the other accepted Function attributes, including
Description, Function name or Runtime.

Note

You are limited to a maximum of 50 tags per Lambda function. If you delete the Lambda
function, the associated tags will also be deleted.

Filtering Lambda Functions Using the CLI
If you want to view the tags that are applied to a speciﬁc Lambda function, you can use either of the
following Lambda API commands:
• ListTags (p. 431): You supply your Lambda function ARN (Amazon Resource Name) to view a list of
the tags associated with this function:
$ aws lambda list-tags \
--resource function arn \
--region region \
--profile adminuser

• GetFunction (p. 395): You supply your Lambda function name to a view a list of the tags associated
with this function:
$ aws lambda get-function \
--function-name function name \
--region region \
--profile adminuser

You can also use the AWS Tagging Service’s GetResources API to ﬁlter your resources by tags. The
GetResources API receives up to 10 ﬁlters, with each ﬁlter containing a tag key and up to 10 tag values.
You provide GetResources with a ‘ResourceType’ to ﬁlter by speciﬁc resource types. For more information
about the AWS Tagging Service, see Working with Resource Groups.

Tag Restrictions
The following restrictions apply to tags:
• Maximum number of tags per resource—50
• Maximum key length—128 Unicode characters in UTF-8
• Maximum value length—256 Unicode characters in UTF-8
• Tag keys and values are case sensitive.
• Do not use the aws: preﬁx in your tag names or values because it is reserved for AWS use. You can't
edit or delete tag names or values with this preﬁx. Tags with this preﬁx do not count against your tags
per resource limit.
• If your tagging schema will be used across multiple services and resources, remember that other
services may have restrictions on allowed characters. Generally allowed characters are: letters, spaces,
and numbers representable in UTF-8, plus the following special characters: + - = . _ : / @.

Managing Concurrency
The unit of scale for AWS Lambda is a concurrent execution (see Understanding Scaling Behavior (p. 68)
for more details). However, scaling indeﬁnitely is not desirable in all scenarios. For example, you may

241

AWS Lambda Developer Guide
Account Level Concurrent Executions Limit

want to control your concurrency for cost reasons, or to regulate how long it takes you to process a
batch of events, or to simply match it with a downstream resource. To assist with this, Lambda provides a
concurrent execution limit control at both the account level and the function level.

Account Level Concurrent Execution Limit
By default, AWS Lambda limits the total concurrent executions across all functions within a given region
to 1000. You can view the account level setting by using the GetAccountSettings (p. 387) API and
viewing the AccountLimit object. This limit can be raised as described below:

To request a limit increase for concurrent executions
1.

Open the AWS Support Center page, sign in if necessary, and then choose Create case.

2.
3.

For Regarding, select Service Limit Increase.
For Limit Type, choose Lambda, ﬁll in the necessary ﬁelds in the form, and then choose the button
at the bottom of the page for your preferred method of contact.

Function Level Concurrent Execution Limit
By default, the concurrent execution limit is enforced against the sum of the concurrent executions
of all functions. The shared concurrent execution pool is referred to as the unreserved concurrency
allocation. If you haven’t set up any function-level concurrency limit, then the unreserved concurrency
limit is the same as the account level concurrency limit. Any increases to the account level limit have a
corresponding increase in the unreserved concurrency limit. You can view the unreserved concurrency
allocation for a function by using the GetAccountSettings (p. 387) API or using the AWS Lambda
console. Functions that are being accounted against the shared concurrent execution pool will not show
any concurrency value when queried using the GetFunctionConﬁguration (p. 398) API.
You can optionally set the concurrent execution limit for a function. You may choose to do this for a few
reasons:
• The default behavior means a surge of concurrent executions in one function prevents the function
you have isolated with an execution limit from getting throttled. By setting a concurrent execution
limit on a function, you are reserving the speciﬁed concurrent execution value for that function.
• Functions scale automatically based on incoming request rate, but not all resources in your
architecture may be able to do so. For example, relational databases have limits on how many
concurrent connections they can handle. You can set the concurrent execution limit for a function to
align with the values of its downstream resources support.
• If your function connects to VPC based resources, you must make sure your subnets have adequate
address capacity to support the ENI scaling requirements of your function. You can estimate the
approximate ENI capacity with the following formula:
Concurrent executions * (Memory in GB / 3 GB)

Where:
• Concurrent execution – This is the projected concurrency of your workload. Use the information in
Understanding Scaling Behavior (p. 68) to determine this value.
• Memory in GB – The amount of memory you conﬁgured for your Lambda function.
You can set the concurrent execution limit for a function to match the subnet size limits you have.

Note

If you need a function to stop processing any invocations, you can choose to set the concurrency
to 0 and throttle all incoming executions.

242

AWS Lambda Developer Guide
Function Level Concurrent Execution Limit

By setting a concurrency limit on a function, Lambda guarantees that allocation will be applied
speciﬁcally to that function, regardless of the amount of traﬃc processing remaining functions. If that
limit is exceeded, the function will be throttled. How that function behaves when throttled will depend
on the event source. For more information, see Throttling Behavior (p. 244).

Note

Concurrency limits can only be set at the function level, not for individual versions. All
invocations to all versions and aliases of a given function will accrue towards the function limit.

Reserved vs. Unreserved Concurrency Limits
If you set the concurrent execution limit for a function, the value is deducted from the unreserved
concurrency pool. For example, if your account's concurrent execution limit is 1000 and you have 10
functions, you can specify a limit on one function at 200 and another function at 100. The remaining 700
will be shared among the other 8 functions.

Note

AWS Lambda will keep the unreserved concurrency pool at a minimum of 100 concurrent
executions, so that functions that do not have speciﬁc limits set can still process requests. So,
in practice, if your total account limit is 1000, you are limited to allocating 900 to individual
functions.

Setting Concurrency Limits Per Function (Console)
To set a concurrency limit for your Lambda function using the Lambda console, do the following:
1.

Sign in to the AWS Management Console and open the AWS Lambda console.

2.

Whether you are creating a new Lambda function or updating an existing function, the process of
setting a concurrency limit is the same. If you are new to Lambda and are unfamiliar with creating a
function, see Create a Lambda Function with the Console (p. 3).
Under the Conﬁguration tab, choose Concurrency. In Reserve concurrency, set the value to the
maximum of concurrent executions you want reserved for the function. Note that when you set
this value, the Unreserved account concurrency value will automatically be updated to display the
remaining number of concurrent executions available for all other functions in the account. Also
note that if you want to block invocation of this function, set the value to 0. To remove a dedicated
allotment value for this account, choose Use unreserved account concurrency.

3.

Setting Concurrency Limits Per Function (CLI)
To set a concurrency limit for your Lambda function using the AWS CLI, do the following:
• Use the PutFunctionConcurrency (p. 446) operation and pass in the function name and concurrency
limit you want allocated to this function:
aws lambda put-function-concurrency --function-name function-name
--reserved-concurrent-executions limit value

To remove a concurrency limit for your Lambda function using the AWS CLI, do the following:
• Use the DeleteFunctionConcurrency (p. 383) operation and pass in the function name:
aws lambda delete-function-concurrency --function-name function-name

To view a concurrency limit for your Lambda function using the AWS CLI, do the following:

243

AWS Lambda Developer Guide
Throttling Behavior

• Use the GetFunction (p. 395) operation and pass in the function name:
aws lambda get-function --function-name function-name

Note

Setting the per function concurrency can impact the concurrency pool available to other
functions. We recommend restricting the permissions to the PutFunctionConcurrency (p. 446)
API and DeleteFunctionConcurrency (p. 383) API to administrative users so that the number of
users who can make these changes is limited.

Throttling Behavior
On reaching the concurrency limit associated with a function, any further invocation requests to that
function are throttled, i.e. the invocation doesn't execute your function. Each throttled invocation
increases the Amazon CloudWatch Throttles metric for the function. AWS Lambda handles throttled
invocation requests diﬀerently, depending on their source:
• Event sources that aren't stream-based: Some of these event sources invoke a Lambda function
synchronously, and others invoke it asynchronously. Handling is diﬀerent for each:
• Synchronous invocation: If the function is invoked synchronously and is throttled, Lambda returns
a 429 error and the invoking service is responsible for retries. The ThrottledReason error code
explains whether you ran into a function level throttle (if speciﬁed) or an account level throttle
(see note below). Each service may have its own retry policy. For a list of event sources and their
invocation type, see Supported Event Sources (p. 71).

Note

If you invoke the function directly through the AWS SDKs using the RequestResponse
invocation mode, your client receives the 429 error and you can retry the invocation.
• Asynchronous invocation: If your Lambda function is invoked asynchronously and is throttled, AWS
Lambda automatically retries the throttled event for up to six hours, with delays between retries.
For example, CloudWatch Logs retries the failed batch up to ﬁve times with delays between retries.
Remember, asynchronous events are queued before they are used to invoke the Lambda function.
You can conﬁgure a Dead Letter Queue (DLQ) to investigate why your function was throttled. For
more information, see Dead Letter Queues (p. 70).
• Poll-based event sources that are also stream-based: such as Amazon Kinesis or Amazon DynamoDB,
AWS Lambda polls your stream and invokes your Lambda function. When your Lambda function is
throttled, Lambda attempts to process the throttled batch of records until the time the data expires.
This time period can be up to seven days for Amazon Kinesis. The throttled request is treated as
blocking per shard, and Lambda doesn't read any new records from the shard until the throttled batch
of records either expires or succeeds. If there is more than one shard in the stream, Lambda continues
invoking on the non-throttled shards until one gets through.
• Poll-based event sources that are not stream-based: such as Amazon Simple Queue Service, AWS
Lambda polls your queue and invokes your Lambda function. When your Lambda function is throttled,
Lambda attempts to process the throttled batch of records until it is succesfully invoked (in which case
the message is automatically deleted from the queue) or until the MessageRetentionPeriod set for the
queue expires.

Monitoring Your Concurrency Usage
To understand your concurrent execution usage, AWS Lambda provides the following metrics:
• ConcurrentExecutions: This shows you the concurrent executions at an account level, and for any
function with a custom concurrency limit.
244

AWS Lambda Developer Guide
Best Practices

• UnreservedConcurrentExecutions: This shows you the total concurrent executions for functions
assigned to the default unreserved concurrency pool.
To learn about these metrics and how to access them, see Using Amazon CloudWatch (p. 208).

Best Practices for Working with AWS Lambda
Functions
The following are recommended best practices for using AWS Lambda:
Topics
• Function Code (p. 245)
• Function Conﬁguration (p. 246)
• Alarming and Metrics (p. 246)
• Stream Event Invokes (p. 247)
• Async Invokes (p. 247)
• Lambda VPC (p. 247)

Function Code
• Separate the Lambda handler (entry point) from your core logic. This allows you to make a more
unit-testable function. In Node.js this may look like:
exports.myHandler = function(event, context, callback) {
var foo = event.foo;
var bar = event.bar;
var result = MyLambdaFunction (foo, bar);
callback(null, result);

}

function MyLambdaFunction (foo, bar) {
// MyLambdaFunction logic here
}

• Take advantage of Execution Context reuse to improve the performance of your function. Make
sure any externalized conﬁguration or dependencies that your code retrieves are stored and referenced
locally after initial execution. Limit the re-initialization of variables/objects on every invocation.
Instead use static initialization/constructor, global/static variables and singletons. Keep alive and reuse
connections (HTTP, database, etc.) that were established during a previous invocation.
• Use AWS Lambda Environment Variables (p. 23) to pass operational parameters to your function.
For example, if you are writing to an Amazon S3 bucket, instead of hard-coding the bucket name you
are writing to, conﬁgure the bucket name as an environment variable.
• Control the dependencies in your function's deployment package. The AWS Lambda execution
environment contains a number of libraries such as the AWS SDK for the Node.js and Python runtimes
(a full list can be found here: Lambda Execution Environment and Available Libraries (p. 92)). To enable
the latest set of features and security updates, Lambda will periodically update these libraries. These
updates may introduce subtle changes to the behavior of your Lambda function. To have full control
of the dependencies your function uses, we recommend packaging all your dependencies with your
deployment package.

245

AWS Lambda Developer Guide
Function Conﬁguration

• Minimize your deployment package size to its runtime necessities. This will reduce the amount of
time that it takes for your deployment package to be downloaded and unpacked ahead of invocation.
For functions authored in Java or .NET Core, avoid uploading the entire AWS SDK library as part of
your deployment package. Instead, selectively depend on the modules which pick up components of
the SDK you need (e.g. DynamoDB, Amazon S3 SDK modules and Lambda core libraries).
• Reduce the time it takes Lambda to unpack deployment packages authored in Java by putting your
dependency .jar ﬁles in a separate /lib directory. This is faster than putting all your function’s code in
a single jar with a large number of .class ﬁles.
• Minimize the complexity of your dependencies. Prefer simpler frameworks that load quickly on
Execution Context startup. For example, prefer simpler Java dependency injection (IoC) frameworks
like Dagger or Guice, over more complex ones like Spring Framework.
• Avoid using recursive code in your Lambda function, wherein the function automatically calls itself
until some arbitrary criteria is met. This could lead to unintended volume of function invocations
and escalated costs. If you do accidentally do so, set the function concurrent execution limit to 0
immediately to throttle all invocations to the function, while you update the code.

Function Conﬁguration
• Performance testing your Lambda function is a crucial part in ensuring you pick the optimum
memory size conﬁguration. Any increase in memory size triggers an equivalent increase in CPU
available to your function. The memory usage for your function is determined per-invoke and can be
viewed in AWS CloudWatch Logs. On each invoke a REPORT: entry will be made, as shown below:
REPORT RequestId: 3604209a-e9a3-11e6-939a-754dd98c7be3 Duration: 12.34 ms Billed
Duration: 100 ms Memory Size: 128 MB Max Memory Used: 18 MB

By analyzing the Max Memory Used: ﬁeld, you can determine if your function needs more memory
or if you over-provisioned your function's memory size.
• Load test your Lambda function to determine an optimum timeout value. It is important to analyze
how long your function runs so that you can better determine any problems with a dependency
service that may increase the concurrency of the function beyond what you expect. This is especially
important when your Lambda function makes network calls to resources that may not handle
Lambda's scaling.
• Use most-restrictive permissions when setting IAM policies. Understand the resources and
operations your Lambda function needs, and limit the execution role to these permissions. For more
information, see AWS Lambda Permissions (p. 221).
• Be familiar with AWS Lambda Limits (p. 249). Payload size, ﬁle descriptors and /tmp space are
often overlooked when determining runtime resource limits.
• Delete Lambda functions that you are no longer using. By doing so, the unused functions won't
needlessly count against your deployment package size limit.
• If you are using Amazon Simple Queue Service as an event source, make sure the value of the
function's expected execution time does not exceed the Visibility Timeout value on the queue. This
applies both to CreateFunction (p. 368) and UpdateFunctionConﬁguration (p. 472).
• In the case of CreateFunction, AWS Lambda will fail the function creation process.
• In the case of UpdateFunctionConﬁguration, it could result in duplicate invocations of the function.

Alarming and Metrics
• Use AWS Lambda Metrics (p. 211) and CloudWatch Alarms instead of creating or updating a metric
from within your Lambda function code. It's a much more eﬃcient way to track the health of your
Lambda functions, allowing you to catch issues early in the development process. For instance, you can
246

AWS Lambda Developer Guide
Stream Event Invokes

conﬁgure an alarm based on the expected duration of your Lambda function execution time in order
to address any bottlenecks or latencies attributable to your function code.
• Leverage your logging library and AWS Lambda Metrics and Dimensions to catch app errors (e.g.
ERR, ERROR, WARNING, etc.)

Stream Event Invokes
• Test with diﬀerent batch and record sizes so that the polling frequency of each event source is tuned
to how quickly your function is able to complete its task. BatchSize controls the maximum number
of records that can be sent to your function with each invoke. A larger batch size can often more
eﬃciently absorb the invoke overhead across a larger set of records, increasing your throughput.

Note

When there are not enough records to process, instead of waiting, the stream processing
function will be invoked with a smaller number of records.
• Increase Kinesis stream processing throughput by adding shards. A Kinesis stream is composed
of one or more shards. Lambda will poll each shard with at most one concurrent invocation. For
example, if your stream has 100 active shards, there will be at most 100 Lambda function invocations
running concurrently. Increasing the number of shards will directly increase the number of maximum
concurrent Lambda function invocations and can increase your Kinesis stream processing throughput.
If you are increasing the number of shards in a Kinesis stream, make sure you have picked a good
partition key (see Partition Keys) for your data, so that related records end up on the same shards and
your data is well distributed.
• Use Amazon CloudWatch on IteratorAge to determine if your Kinesis stream is being processed. For
example, conﬁgure a CloudWatch alarm with a maximum setting to 30000 (30 seconds).

Async Invokes
• Create and use Dead Letter Queues (p. 70) to address and replay async function errors.

Lambda VPC
• The following diagram guides you through a decision tree as to whether you should use a VPC (Virtual
Private Cloud):

247

AWS Lambda Developer Guide
Lambda VPC

• Don't put your Lambda function in a VPC unless you have to. There is no beneﬁt outside of using
this to access resources you cannot expose publicly, like a private Amazon Relational Database
instance. Services like Amazon Elasticsearch Service can be secured over IAM with access policies, so
exposing the endpoint publicly is safe and wouldn't require you to run your function in the VPC to
secure it.
• Lambda creates elastic network interfaces (ENIs) in your VPC to access your internal resources.
Before requesting a concurrency increase, ensure you have enough ENI capacity (the formula for this
can be found here: Conﬁguring a Lambda Function to Access Resources in an Amazon VPC (p. 52)) and
IP address space. If you do not have enough ENI capacity, you will need to request an increase. If you
do not have enough IP address space, you may need to create a larger subnet.
• Create dedicated Lambda subnets in your VPC:
• This will make it easier to apply a custom route table for NAT Gateway traﬃc without changing your
other private/public subnets. For more information, see Conﬁguring a Lambda Function to Access
Resources in an Amazon VPC (p. 52)
• This also allows you to dedicate an address space to Lambda without sharing it with other resources.

248

AWS Lambda Developer Guide
Limits

AWS Lambda Limits
AWS Lambda limits the amount of compute and storage resources that you can use to run and store
functions. The following limits apply per-region and can be increased. To request an increase, use the
Support Center console.
Resource

Default Limit

Concurrent executions (p. 241)

1000

Function and layer storage

75 GB

For details on how Lambda scales your function concurrency in response to traﬃc, see Understanding
Scaling Behavior (p. 68).
The following limits apply to function conﬁguration, deployments, and execution. They cannot be
changed.
Resource

Limit

Function memory allocation (p. 22)

128 MB to 3008 MB, in 64 MB
increments.

Function timeout (p. 22)

900 seconds (15 minutes)

Function environment variables (p. 23)

4 KB

Function resource-based policy (p. 47)

20 KB

Function layers (p. 47)

5 layers

Invocation payload (p. 60) (request and response)

6 MB (synchronous)
256 KB (asynchronous)

Deployment package (p. 19) size

50 MB (zipped, for direct upload)
250 MB (unzipped, including layers)
3 MB (console editor)

Test events (console editor)

10

/tmp directory storage

512 MB

File descriptors

1024

Execution processes/threads

1024

Limits for other services, such as AWS Identity and Access Management, Amazon CloudFront
(Lambda@Edge), and Amazon Virtual Private Cloud, can impact your Lambda functions. For more
information, see AWS Service Limits and Using AWS Lambda With Other Services (p. 114).

249

AWS Lambda Developer Guide
Deployment Package

Building Lambda Functions with
Node.js
AWS Lambda supports the following Node.js runtimes.

Node.js Runtimes
Name

Identiﬁer

Node.js 8.10

nodejs8.10

Node.js 6.10

nodejs6.10

When you create a Lambda function, you specify the runtime that you want to use. For more
information, see runtime parameter of CreateFunction (p. 368).
The following sections explain how common programming patterns and core concepts apply when
authoring Lambda function code in Node.js. The programming model described in the following sections
applies to all supported runtime versions, except where indicated.
Topics
• AWS Lambda Deployment Package in Node.js (p. 250)
• AWS Lambda Function Handler in Node.js (p. 251)
• AWS Lambda Context Object in Node.js (p. 254)
• AWS Lambda Function Logging in Node.js (p. 255)
• AWS Lambda Function Errors in Node.js (p. 257)
• Instrumenting Node.js Code in AWS Lambda (p. 260)

AWS Lambda Deployment Package in Node.js
To create a Lambda function you ﬁrst create a Lambda function deployment package, a .zip ﬁle
consisting of your code and any dependencies.
You can create a deployment package yourself or write your code directly in the Lambda console, in
which case the console creates the deployment package for you and uploads it, creating your Lambda
function. Note the following to determine if you can use the console to create your Lambda function:
• Simple scenario – If your custom code requires only the AWS SDK library, then you can use the
inline editor in the AWS Lambda console. Using the console, you can edit and upload your code to
AWS Lambda. The console will zip up your code with the relevant conﬁguration information into a
deployment package that the Lambda service can run.
You can also test your code in the console by manually invoking it using sample event data.

Note

The Lambda service has preinstalled the AWS SDK for Node.js.
250

AWS Lambda Developer Guide
Handler

• Advanced scenario – If you are writing code that uses other resources, such as a graphics library for
image processing, or you want to use the AWS CLI instead of the console, you need to ﬁrst create the
Lambda function deployment package, and then use the console or the CLI to upload the package.

Note

After you create a deployment package, you may either upload it directly or upload the .zip ﬁle
ﬁrst to an Amazon S3 bucket in the same AWS region where you want to create the Lambda
function, and then specify the bucket name and object key name when you create the Lambda
function using the console or the AWS CLI.
The following is an example procedure to create a deployment package (outside the console). Suppose
you want to create a deployment package that includes a filename.js code ﬁle and your code uses the
async library.
1. Open a text editor, and write your code. Save the ﬁle (for example, filename.js).
You will use the ﬁle name to specify the handler at the time of creating the Lambda function.
2. In the same directory, use npm to install the libraries that your code depends on. For example, if your
code uses the async library, use the following npm command.
npm install async

3. Your directory will then have the following structure:
filename.js
node_modules/async
node_modules/async/lib
node_modules/async/lib/async.js
node_modules/async/package.json

4. Zip the content of the folder, that is your deployment package (for example, sample.zip).
Then, specify the .zip ﬁle name as your deployment package at the time you create your Lambda
function.
If you want to include your own binaries, including native ones, just package them in the Zip ﬁle you
upload and then reference them (including the relative path within the Zip ﬁle you created) when you
call them from Node.js or from other processes that you’ve previously started. Ensure that you include
the following at the start of your function code: process.env[‘PATH’] = process.env[‘PATH’]
+ ‘:’ + process.env[‘LAMBDA_TASK_ROOT’]
For more information on including native binaries in your Lambda function package, see Running
Executables in AWS Lambda. Also note that you need to supply the requisite permissions to the contents
of the Zip ﬁle. For more information, see Permissions Policies on Lambda Deployment Packages (p. 19).

AWS Lambda Function Handler in Node.js
AWS Lambda invokes your Lambda function via a handler object. A handler represents the name of
your Lambda function and serves as the entry point that AWS Lambda uses to execute your function
code. For example:
exports.myHandler = function(event, context, callback) {
... function code

251

AWS Lambda Developer Guide
Using the Callback Parameter

}

callback(null, "some success message");
// or
// callback("some error type");

• myHandler – This is the name of the function AWS Lambda invokes. Suppose you save this code as
helloworld.js. Then, myHandler is the function that contains your Lambda function code and
helloworld is the name of the ﬁle that represents your deployment package. For more information,
see AWS Lambda Deployment Package in Node.js (p. 250).
AWS Lambda supports two invocation types:
• RequestResponse, or synchronous execution: AWS Lambda returns the result of the function call
to the client invoking the Lambda function. If the handler code of your Lambda function does not
specify a return value, AWS Lambda will automatically return null for that value. For a simple
sample, see Example (p. 253).
• Event, or asynchronous execution: AWS Lambda will discard any results of the function call.

Note

If you discover that your Lambda function does not process the event using asynchronous
invocation, you can investigate the failure using Dead Letter Queues (p. 70).
Event sources can range from a supported AWS service or custom applications that invoke your
Lambda function. For examples, see Sample Events Published by Event Sources (p. 79). For a simple
sample, see Example (p. 253).
• context – AWS Lambda uses this parameter to provide details of your Lambda function's execution.
For more information, see AWS Lambda Context Object in Node.js (p. 254).
• callback (optional) – See Using the Callback Parameter (p. 252).

Using the Callback Parameter
The Node.js runtimes v6.10 and v8.10 support the optional callback parameter. You can use it to
explicitly return information back to the caller. The general syntax is:
callback(Error error, Object result);

Where:
• error – is an optional parameter that you can use to provide results of the failed Lambda function
execution. When a Lambda function succeeds, you can pass null as the ﬁrst parameter.
• result – is an optional parameter that you can use to provide the result of a successful function
execution. The result provided must be JSON.stringify compatible. If an error is provided, this
parameter is ignored.
If you don't use callback in your code, AWS Lambda will call it implicitly and the return value is null.
When the callback is called (explicitly or implicitly), AWS Lambda continues the Lambda function
invocation until the event loop is empty.
The following are example callbacks:
callback();
// Indicates success but no information returned to the caller.
callback(null); // Indicates success but no information returned to the caller.
callback(null, "success"); // Indicates success with information returned to the caller.
callback(error);
// Indicates error with error information returned to the caller.

252

AWS Lambda Developer Guide
Example

AWS Lambda treats any non-null value for the error parameter as a handled exception.
Note the following:
• Regardless of the invocation type speciﬁed at the time of the Lambda function invocation (see
Invoke (p. 410)), the callback method automatically logs the string representation of non-null values
of error to the Amazon CloudWatch Logs stream associated with the Lambda function.
• If the Lambda function was invoked synchronously (using the RequestResponse invocation type), the
callback returns a response body as follows:
• If error is null, the response body is set to the string representation of result.
• If the error is not null, the error value will be populated in the response body.

Note

When the callback(error, null) (and callback(error)) is called, Lambda will log the
ﬁrst 256 KB of the error object. For a larger error object, AWS Lambda truncates the log and
displays the text Truncated by Lambda next to the error object.
If you are using runtime version 8.10, you can include the async keyword:
exports.myHandler = async function(event, context) {
...
}

// return information to the caller.

Example
Consider the following Node.js example code.
exports.myHandler = function(event, context, callback) {
console.log("value1 = " + event.key1);
console.log("value2 = " + event.key2);
callback(null, "some success message");
// or
// callback("some error type");
}

This example has one function, myHandler
In the function, the console.log() statements log some of the incoming event data to CloudWatch
Logs. When the callback parameter is called, the Lambda function exits only after the event loop
passed is empty.
If you want to use the async feature provided by the v8.10 runtime, consider the following code sample:
exports.myHandler = async function(event, context) {
console.log("value1 = " + event.key1);
console.log("value2 = " + event.key2);
return "some success message";
// or
// throw new Error("some error type");
}

To upload and test this code as a Lambda function (console)
1.

In the console, create a Lambda function using the following information:

253

AWS Lambda Developer Guide
Context

• Use the hello-world blueprint.
• The sample uses nodejs6.10 as the runtime but you can also select nodejs8.10. The code samples
provided will work for any version.
For instructions to create a Lambda function using the console, see Create a Lambda Function with
the Console (p. 3).
2.

Replace the template code with the code provided in this section and create the function.

3.

Test the Lambda function using the Sample event template called Hello World provided in the
Lambda console.

AWS Lambda Context Object in Node.js
When Lambda runs your function, it passes a context object to the handler (p. 251). This object
provides methods and properties that provide information about the invocation, function, and execution
environment.

Context Methods
• getRemainingTimeInMillis() – Returns the number of milliseconds left before the execution
times out.

Context Properties
• functionName – The name of the Lambda function.
• functionVersion – The version (p. 30) of the function.
• invokedFunctionArn – The Amazon Resource Name (ARN) used to invoke the function. Indicates if
the invoker speciﬁed a version number or alias.
• memoryLimitInMB – The amount of memory conﬁgured on the function.
• awsRequestId – The identiﬁer of the invocation request.
• logGroupName – The log group for the function.
• logStreamName – The log stream for the function instance.
• identity – (mobile apps) Information about the Amazon Cognito identity that authorized the
request.
• cognitoIdentityId – The authenticated Amazon Cognito identity.
• cognitoIdentityPoolId – The Amazon Cognito identity pool that authorized the invocation.
• clientContext – (mobile apps) Client context provided to the Lambda invoker by the client
application.
• client.installation_id
• client.app_title
• client.app_version_name
• client.app_version_code
• client.app_package_name
• env.platform_version
• env.platform
• env.make
• env.model
254

AWS Lambda Developer Guide
Logging

• env.locale
• Custom – Custom values set by the mobile application.
• callbackWaitsForEmptyEventLoop – Set to false to send the response right away when the
callback (p. 252) executes, instead of waiting for the Node.js event loop to be empty. If false, any
outstanding events will continue to run during the next invocation.
The following example shows a handler function that logs context information.

Example index.js
exports.handler = function(event, context, callback) {
console.log('remaining time =', context.getRemainingTimeInMillis());
console.log('functionName =', context.functionName);
console.log('AWSrequestID =', context.awsRequestId);
callback(null, context.functionName);
};

AWS Lambda Function Logging in Node.js
Your Lambda function can contain logging statements. AWS Lambda writes these logs to CloudWatch. If
you use the Lambda console to invoke your Lambda function, the console displays the same logs.
The following Node.js statements generate log entries:
• console.log()
• console.error()
• console.warn()
• console.info()
For example, consider the following Node.js code examples:
• The ﬁrst sample can be written using either runtime version 6.10 or 4.3.
console.log('Loading function');
exports.handler = function(event, context, callback) {
//console.log('Received event:', JSON.stringify(event, null, 2));
console.log('value1 =', event.key1);
console.log('value2 =', event.key2);
console.log('value3 =', event.key3);
callback(null, event.key1); // Echo back the first key value
};

• The second sample uses the Node.js async feature, available only in runtime versions 8.10 or later.
console.log('Loading function');
exports.handler = async function(event) {
//console.log('Received event:', JSON.stringify(event, null, 2));
console.log('value1 =', event.key1);
console.log('value2 =', event.key2);
console.log('value3 =', event.key3);
return event.key1 // Echo back the first key value

255

AWS Lambda Developer Guide
Finding Logs
};

In either case, the following screenshot shows an example Log output section in the Lambda console.
You can examine the same information in CloudWatch Logs. For more information, see Accessing
Amazon CloudWatch Logs for AWS Lambda (p. 211).

The console uses the RequestResponse invocation type (synchronous invocation) when invoking the
function, therefore it gets the return value (value1) back from AWS Lambda which the console displays.

To test the preceding Node.js code in AWS Lambda console
1.

2.

In the console, create a Lambda function using the hello-world blueprint. Make sure to select the
Node.js as the runtime. For instructions on how to do this, see Create a Lambda Function with the
Console (p. 3).
Test the Lambda function using the Sample event template called Hello World provided in the
Lambda console. You can also update the code and try other logging methods and properties
discussed in this section.

For step-by-step instructions, see Getting Started with AWS Lambda (p. 3).

Finding Logs
You can ﬁnd the logs that your Lambda function writes, as follows:
• In the AWS Lambda console – The Log output section in the AWS Lambda console shows the logs.
• In the response header, when you invoke a Lambda function programmatically – If you invoke a
Lambda function programmatically, you can add the LogType parameter to retrieve the last 4 KB of

256

AWS Lambda Developer Guide
Errors

log data that is written to CloudWatch Logs. AWS Lambda returns this log information in the x-amzlog-results header in the response. For more information, see Invoke.
If you use AWS CLI to invoke the function, you can specify the --log-type parameter with
value Tail to retrieve the same information.
• In CloudWatch Logs – To ﬁnd your logs in CloudWatch you need to know the log group name
and log stream name. You can get that information by adding the context.logGroupName, and
context.logStreamName methods in your code. When you run your Lambda function, the resulting
logs in the console or CLI will show you the log group name and log stream name.

AWS Lambda Function Errors in Node.js
If your Lambda function notiﬁes AWS Lambda that it failed to execute properly, Lambda will attempt to
convert the error object to a String. Consider the following example:
console.log('Loading function');
exports.handler = function(event, context, callback) {
// This example code only throws error.
var error = new Error("something is wrong");
callback(error);
};

When you invoke this Lambda function, it will notify AWS Lambda that function execution completed
with an error and passes the error information to AWS Lambda. AWS Lambda returns the error
information back to the client:
{

}

"errorMessage": "something is wrong",
"errorType": "Error",
"stackTrace": [
"exports.handler (/var/task/index.js:10:17)"
]

You would get the same result if you write the function using the async feature of Node.js runtime
version 8.10. For example:
exports.handler = async function(event, context) {
function AccountAlreadyExistsError(message) {
this.name = "AccountAlreadyExistsError";
this.message = message;
}
AccountAlreadyExistsError.prototype = new Error();

};

const error = new AccountAlreadyExistsError("Account is in use!");
throw error

Again, when this Lambda function is invoked, it will notify AWS Lambda that function execution
completed with an error and passes the error information to AWS Lambda. AWS Lambda returns the
error information back to the client:
{

257

AWS Lambda Developer Guide
Errors

}

"errorMessage": "Account is in use!",
"errorType": "Error",
"stackTrace": [
"exports.handler (/var/task/index.js:10:17)"
]

Note that the error information is returned as the stackTrace JSON array of stack trace elements.
How you get the error information back depends on the invocation type that the client speciﬁes at the
time of function invocation:
• If a client speciﬁes the RequestResponse invocation type (that is, synchronous execution), it returns
the result to the client that made the invoke call.
For example, the console always use the RequestResponse invocation type, so the console will
display the error in the Execution result section as shown:

The same information is also sent to CloudWatch and the Log output section shows the same logs.

• If a client speciﬁes the Event invocation type (that is, asynchronous execution), AWS Lambda will not
return anything. Instead, it logs the error information to CloudWatch Logs. You can also see the error
metrics in CloudWatch Metrics.
Depending on the event source, AWS Lambda may retry the failed Lambda function. For example, if
Kinesis is the event source, AWS Lambda will retry the failed invocation until the Lambda function
succeeds or the records in the stream expire. For more information on retries, see AWS Lambda Retry
Behavior (p. 67).

258

AWS Lambda Developer Guide
Function Error Handling

To test the preceding Node.js code (console)
1.

In the console, create a Lambda function using the hello-world blueprint. In runtime, choose
Node.js and, in Role, choose Basic execution role. For instructions on how to do this, see Create a
Lambda Function with the Console (p. 3).

2.

Replace the template code with the code provided in this section.

3.

Test the Lambda function using the Sample event template called Hello World provided in the
Lambda console.

Function Error Handling
You can create custom error handling to raise an exception directly from your Lambda function and
handle it directly (Retry or Catch) within an AWS Step Functions State Machine. For more information,
see Handling Error Conditions Using a State Machine.
Consider a CreateAccount state is a task that writes a customer's details to a database using a Lambda
function.
• If the task succeeds, an account is created and a welcome email is sent.
• If a user tries to create an account for a username that already exists, the Lambda function raises an
error, causing the state machine to suggest a diﬀerent username and to retry the account-creation
process.
The following code samples demonstrate how to do this. Note that custom errors in Node.js must extend
the error prototype.
exports.handler = function(event, context, callback) {
function AccountAlreadyExistsError(message) {
this.name = "AccountAlreadyExistsError";
this.message = message;
}
AccountAlreadyExistsError.prototype = new Error();

};

const error = new AccountAlreadyExistsError("Account is in use!");
callback(error);

You can conﬁgure Step Functions to catch the error using a Catch rule:
{

}

"StartAt": "CreateAccount",
"States": {
"CreateAccount": {
"Type": "Task",
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:CreateAccount",
"Next": "SendWelcomeEmail",
"Catch": [
{
"ErrorEquals": ["AccountAlreadyExistsError"],
"Next": "SuggestAccountName"
}
]
},
…
}

259

AWS Lambda Developer Guide
Tracing

At runtime, AWS Step Functions catches the error, transitioning to the SuggestAccountName state as
speciﬁed in the Next transition.

Note

The name property of the Error object must match the ErrorEquals value.
Custom error handling makes it easier to create serverless applications. This feature integrates with
all the languages supported by the Lambda Programming Model (p. 18), allowing you to design your
application in the programming languages of your choice, mixing and matching as you go.
To learn more about creating your own serverless applications using AWS Step Functions and AWS
Lambda, see AWS Step Functions.

Instrumenting Node.js Code in AWS Lambda
In Node.js, you can have Lambda emit subsegments to X-Ray to show you information about
downstream calls to other AWS services made by your function. To do so, you ﬁrst need to include the
the AWS X-Ray SDK for Node.js in your deployment package. In addition, wrap your AWS SDK require
statement in the following manner:
var AWSXRay = require('aws-xray-sdk-core');
var AWS = AWSXRay.captureAWS(require('aws-sdk'));

Then, use the AWS variable deﬁned in the preceding example to initialize any service client that you want
to trace with X-Ray, for example:
s3Client = AWS.S3();

After following these steps, any call made from your function using s3Client results in an X-Ray
subsegment that represents that call. As an example, you can run the Node.js function following to see
how the trace looks in X-Ray:

Example index.js
var AWSXRay = require('aws-xray-sdk-core');
var AWS = AWSXRay.captureAWS(require('aws-sdk'));
var s3 = new AWS.S3();
exports.handler = (event, context, callback) => {
var params = {Bucket: process.env.BUCKET_NAME, Key: process.env.BUCKET_KEY, Body:
process.env.BODY};

};

s3.putObject(params, function(err, data) {
if (err)
{ console.log(err) }
else {
console.log('success!')
}
});

Following is what a trace emitted by the code preceding looks like (asynchronous invocation):

260

AWS Lambda Developer Guide
Tracing

261

AWS Lambda Developer Guide
Deployment Package

Building Lambda Functions with
Python
The following sections explain how common programming patterns and core concepts apply when
authoring Lambda function code in Python.

Python Runtimes
Name

Identiﬁer

Python 3.6

python3.6

Python 3.7

python3.7

Python 2.7

python2.7

Topics
• AWS Lambda Deployment Package in Python (p. 262)
• AWS Lambda Function Handler in Python (p. 266)
• AWS Lambda Context Object in Python (p. 267)
• AWS Lambda Function Logging in Python (p. 268)
• AWS Lambda Function Errors in Python (p. 270)
• Instrumenting Python Code in AWS Lambda (p. 272)

AWS Lambda Deployment Package in Python
A deployment package is a ZIP archive that contains your function code and dependencies. You need
to create a deployment package if you use the Lambda API to manage functions, or if your code
uses libraries other than the AWS SDK. Other libraries and dependencies need to be included in the
deployment package. You can upload the package directly to Lambda, or you can use an Amazon S3
bucket, and then upload it to Lambda.
If you use the Lambda console editor (p. 11) to author your function, the console manages the
deployment package. You can use this method as long as you don't need to add any libraries. You can
also use it to update a function that already has libraries in the deployment package, as long as the total
size doesn't exceed 3 MB.

Note

You can use the AWS SAM CLI build command to create a deployment package for your Python
function code and dependencies. See Building Applications with Dependencies in the AWS SAM
Developer Guide for instructions.
Sections
• Without Additional Dependencies (p. 263)
• With Additional Dependencies (p. 263)
• With a Virtual Environment (p. 264)

262

AWS Lambda Developer Guide
Without Additional Dependencies

Without Additional Dependencies
To create or update a function with the Lambda API, create an archive that contains your function code
and upload it with the AWS CLI.

To update a Python function with no dependencies
1.

Create a ZIP archive.
~/my-function$ zip function.zip function.py

2.

Use the update-function-code command to upload the package.
~/my-function$ aws lambda update-function-code --function-name python37 --zip-file
fileb://function.zip
{
"FunctionName": "python37",
"FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:python37",
"Runtime": "python3.7",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "function.handler",
"CodeSize": 815,
"Description": "",
"Timeout": 3,
"MemorySize": 128,
"LastModified": "2018-11-20T20:41:16.647+0000",
"CodeSha256": "GcZ05oeHoJi61VpQj7vCLPs8DwCXmX5sE/fE2IHsizc=",
"Version": "$LATEST",
"VpcConfig": {
"SubnetIds": [],
"SecurityGroupIds": [],
"VpcId": ""
},
"TracingConfig": {
"Mode": "Active"
},
"RevisionId": "d1e983e3-ca8e-434b-8dc1-7add83d72ebd"
}

With Additional Dependencies
If your function depends on libraries other than the SDK for Python (Boto 3), install them to a local
directory with pip, and include them in your deployment package.

To update a Python function with dependencies
1.

Create a directory for dependencies.
~/my-function$ mkdir package

2.

Install libraries in the package directory with the --target option.
~/my-function$ cd package
~/my-function/package$ pip install Pillow --target .
Collecting Pillow
Using cached https://files.pythonhosted.org/
packages/62/8c/230204b8e968f6db00c765624f51cfd1ecb6aea57b25ba00b240ee3fb0bd/
Pillow-5.3.0-cp37-cp37m-manylinux1_x86_64.whl

263

AWS Lambda Developer Guide
With a Virtual Environment
Installing collected packages: Pillow
Successfully installed Pillow-5.3.0

3.

Create a ZIP archive.
package$ zip -r9 ../function.zip .
adding: PIL/ (stored 0%)
adding: PIL/.libs/ (stored 0%)
adding: PIL/.libs/libfreetype-7ce95de6.so.6.16.1 (deflated 65%)
adding: PIL/.libs/libjpeg-3fe7dfc0.so.9.3.0 (deflated 72%)
adding: PIL/.libs/liblcms2-a6801db4.so.2.0.8 (deflated 67%)
...

4.

Add your function code to the archive.
~/my-function/package$ cd ../
~/my-function$ zip -g function.zip function.py
adding: function.py (deflated 56%)

5.

Update the function code.
~/my-function$ aws lambda update-function-code --function-name python37 --zip-file
fileb://function.zip
{
"FunctionName": "python37",
"FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:python37",
"Runtime": "python3.7",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "function.handler",
"CodeSize": 2269409,
"Description": "",
"Timeout": 3,
"MemorySize": 128,
"LastModified": "2018-11-20T20:51:35.871+0000",
"CodeSha256": "GcZ05oeHoJi61VpQj7vCLPs8DwCXmX5sE/fE2IHsizc=",
"Version": "$LATEST",
"VpcConfig": {
"SubnetIds": [],
"SecurityGroupIds": [],
"VpcId": ""
},
"TracingConfig": {
"Mode": "Active"
},
"RevisionId": "a9c05ffd-8ad6-4d22-b6cd-d34a00c1702c"
}

With a Virtual Environment
In some cases, you may need to use a virtual environment to install dependencies for your function.
This can occur if your function or its dependencies have dependencies on native libraries, or if you used
Homebrew to install Python.

To update a Python function with a virtual environment
1.

Create a virtual environment.
~/my-function$ virtualenv v-env
Using base prefix '~/.local/python-3.7.0'

264

AWS Lambda Developer Guide
With a Virtual Environment
New python executable in v-env/bin/python3.7
Also creating executable in v-env/bin/python
Installing setuptools, pip, wheel...
done.

2.

Activate the environment.
~/my-function$ source v-env/bin/activate
(v-env) ~/my-function$

For the Windows command line, the activation script is in the Scripts directory.
> v-env\Scripts\activate.bat

3.

Install libraries with pip.
~/my-function$ pip install Pillow
Collecting Pillow
Using cached https://files.pythonhosted.org/
packages/62/8c/230204b8e968f6db00c765624f51cfd1ecb6aea57b25ba00b240ee3fb0bd/
Pillow-5.3.0-cp37-cp37m-manylinux1_x86_64.whl
Installing collected packages: Pillow
Successfully installed Pillow-5.3.0

4.

Deactivate the virtual environment.
(v-env)~/my-function$ deactivate

5.

Create a ZIP archive with the contents of the site-packages directory.
~/my-function$ cd v-env/lib/python3.7/site-packages/
~/my-function/v-env/lib/python3.7/site-packages$ zip -r9 ../../../../function.zip .
adding: easy_install.py (deflated 17%)
adding: PIL/ (stored 0%)
adding: PIL/.libs/ (stored 0%)
adding: PIL/.libs/libfreetype-7ce95de6.so.6.16.1 (deflated 65%)
adding: PIL/.libs/libjpeg-3fe7dfc0.so.9.3.0 (deflated 72%)
...

Note

In some cases, libraries may also be installed in the dist-packages directory.
6.

Add your function code to the archive.
~/my-function/v-env/lib/python3.7/site-packages$ cd ../../../../
~/my-function$ zip -g function.zip function.py
adding: function.py (deflated 56%)

7.

Update the function code.
~/my-function$ aws lambda update-function-code --function-name python37 --zip-file
fileb://function.zip
{
"FunctionName": "python37",
"FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:python37",
"Runtime": "python3.7",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "function.handler",
"CodeSize": 5912988,
"Description": "",

265

AWS Lambda Developer Guide
Handler

}

"Timeout": 3,
"MemorySize": 128,
"LastModified": "2018-11-20T21:08:26.326+0000",
"CodeSha256": "A2P0NUWq1J+LtSbkuP8tm9uNYqs1TAa3M76ptmZCw5g=",
"Version": "$LATEST",
"VpcConfig": {
"SubnetIds": [],
"SecurityGroupIds": [],
"VpcId": ""
},
"TracingConfig": {
"Mode": "Active"
},
"RevisionId": "5afdc7dc-2fcb-4ca8-8f24-947939ca707f"

AWS Lambda Function Handler in Python
At the time you create a Lambda function, you specify a handler, which is a function in your code, that
AWS Lambda can invoke when the service executes your code. Use the following general syntax structure
when creating a handler function in Python.
def handler_name(event, context):
...
return some_value

In the syntax, note the following:
• event – AWS Lambda uses this parameter to pass in event data to the handler. This parameter is
usually of the Python dict type. It can also be list, str, int, float, or NoneType type.
• context – AWS Lambda uses this parameter to provide runtime information to your handler. This
parameter is of the LambdaContext type.
• Optionally, the handler can return a value. What happens to the returned value depends on the
invocation type you use when invoking the Lambda function:
• If you use the RequestResponse invocation type (synchronous execution), AWS Lambda returns
the result of the Python function call to the client invoking the Lambda function (in the HTTP
response to the invocation request, serialized into JSON). For example, AWS Lambda console uses
the RequestResponse invocation type, so when you invoke the function using the console, the
console will display the returned value.
If the handler returns NONE, AWS Lambda returns null.
• If you use the Event invocation type (asynchronous execution), the value is discarded.
For example, consider the following Python example code.
def my_handler(event, context):
message = 'Hello {} {}!'.format(event['first_name'],
event['last_name'])
return {
'message' : message
}

This example has one function called my_handler. The function returns a message containing data from
the event it received as input.
266

AWS Lambda Developer Guide
Context

AWS Lambda Context Object in Python
When Lambda runs your function, it passes a context object to the handler (p. 266). This object
provides methods and properties that provide information about the invocation, function, and execution
environment.

Context Methods
• get_remaining_time_in_millis – Returns the number of milliseconds left before the execution
times out.

Context Properties
• function_name – The name of the Lambda function.
• function_version – The version (p. 30) of the function.
• invoked_function_arn – The Amazon Resource Name (ARN) used to invoke the function. Indicates
if the invoker speciﬁed a version number or alias.
• memory_limit_in_mb – The amount of memory conﬁgured on the function.
• aws_request_id – The identiﬁer of the invocation request.
• log_group_name – The log group for the function.
• log_stream_name – The log stream for the function instance.
• deadline_ms – The date that the execution times out, in Unix time milliseconds.
• identity – (mobile apps) Information about the Amazon Cognito identity that authorized the
request.
• cognito_identity_id – The authenticated Amazon Cognito identity.
• cognito_identity_pool_id – The Amazon Cognito identity pool that authorized the invocation.
• client_context – (mobile apps) Client context provided to the Lambda invoker by the client
application.
• client.installation_id
• client.app_title
• client.app_version_name
• client.app_version_code
• cclient.app_package_name
• custom – A dict of custom values set by the mobile client application.
• env – A dict of environment information provided by the AWS SDK.
The following example shows a handler function that logs context information.

Example handler.py
import time
def get_my_log_stream(event, context):
print("Log stream name:", context.log_stream_name)
print("Log group name:", context.log_group_name)
print("Request ID:",context.aws_request_id)
print("Mem. limits(MB):", context.memory_limit_in_mb)
# Code will execute quickly, so we add a 1 second intentional delay so you can see that
in time remaining value.
time.sleep(1)
print("Time remaining (MS):", context.get_remaining_time_in_millis())

267

AWS Lambda Developer Guide
Logging

In addition to the options listed above, you can also use the AWS X-Ray SDK for Instrumenting Python
Code in AWS Lambda (p. 272) to identify critical code paths, trace their performance and capture the
data for analysis.

AWS Lambda Function Logging in Python
Your Lambda function can contain logging statements. AWS Lambda writes these logs to CloudWatch. If
you use the Lambda console to invoke your Lambda function, the console displays the same logs.
The following Python statements generate log entries:
• print statements.
• Logger functions in the logging module (for example, logging.Logger.info and
logging.Logger.error).
Both print and logging.* functions write logs to CloudWatch Logs but the logging.* functions
write additional information to each log entry, such as time stamp and log level.
For example, consider the following Python code example.
import logging
logger = logging.getLogger()
logger.setLevel(logging.INFO)
def my_logging_handler(event, context):
logger.info('got event{}'.format(event))
logger.error('something went wrong')
return 'Hello from Lambda!'

Because the code example uses the logging module to write message to the logs, you also get some
additional information in the log such as the time stamp and the log levels. The log level identiﬁes the
type of log, such as [INFO], [ERROR], and [DEBUG].
You can also ﬁnd these logs in CloudWatch. For more information, see Accessing Amazon CloudWatch
Logs for AWS Lambda (p. 211).
Instead of using the logging module, you can use the print statements in your code as shown in the
following Python example:
from __future__ import print_function
def lambda_handler(event, context):
print('this will also show up in cloud watch')
return 'Hello World!'

In this case only the text passed to the print method is sent to CloudWatch. The log entries will not have
additional information that the logging.* function returns. The from __future__ statement enables
you to write code that is compatible with Python 2 or 3.

268

AWS Lambda Developer Guide
Finding Logs

The console uses the RequestResponse invocation type (synchronous invocation) when invoking
the function. And therefore it gets the return value ("Hello world!") back from AWS Lambda which the
console displays.

To test the preceding Python code (console)
1.

In the console, create a Lambda function using the hello-world-python blueprint. In runtime,
choose Python 2.7. In Handler, replace lambda_function.lambda_handler with
lambda_function.my_other_logging_handler and in Role, choose Basic execution role.
You also replace the code provided by the blueprint by the code in this section. For step-by-step
instructions to create a Lambda function using the console, see Create a Lambda Function with the
Console (p. 3).

2.

Replace the template code with the code provided in this section.

3.

Test the Lambda function using the Sample event template called Hello World provided in the
Lambda console.

Finding Logs
You can ﬁnd the logs that your Lambda function writes, as follows:
• In the AWS Lambda console – The Log output section in AWS Lambda console shows the logs.
• In the response header, when you invoke a Lambda function programmatically – If you invoke a
Lambda function programmatically, you can add the LogType parameter to retrieve the last 4 KB of
log data that is written to CloudWatch Logs. AWS Lambda returns this log information in the x-amzlog-results header in the response. For more information, see Invoke (p. 410).
If you use AWS CLI to invoke the function, you can specify the --log-type parameter with
value Tail to retrieve the same information.

269

AWS Lambda Developer Guide
Errors

• In CloudWatch Logs – To ﬁnd your logs in CloudWatch you need to know the log group name and
log stream name. You can use the context.log_group_name and context.log_stream_name
properties in your code to get this information. When you run your Lambda function, the resulting logs
in the console or CLI will show you the log group name and log stream name.

AWS Lambda Function Errors in Python
If your Lambda function raises an exception, AWS Lambda recognizes the failure and serializes the
exception information into JSON and returns it. Consider the following example:
def always_failed_handler(event, context):
raise Exception('I failed!')

When you invoke this Lambda function, it will raise an exception and AWS Lambda returns the following
error message:
{

}

"errorMessage": "I failed!",
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"my_always_fails_handler",
"raise Exception('I failed!')"
]
],
"errorType": "Exception"

Note that the stack trace is returned as the stackTrace JSON array of stack trace elements.
How you get the error information back depends on the invocation type that the client speciﬁes at the
time of function invocation:
• If a client speciﬁes the RequestResponse invocation type (that is, synchronous execution), it returns
the result to the client that made the invoke call.
For example, the console always use the RequestResponse invocation type, so the console will
display the error in the Execution result section as shown:

The same information is also sent to CloudWatch and the Log output section shows the same logs.

270

AWS Lambda Developer Guide
Function Error Handling

• If a client speciﬁes the Event invocation type (that is, asynchronous execution), AWS Lambda will not
return anything. Instead, it logs the error information to CloudWatch Logs. You can also see the error
metrics in CloudWatch Metrics.
Depending on the event source, AWS Lambda may retry the failed Lambda function. For example, if
Kinesis is the event source, AWS Lambda will retry the failed invocation until the Lambda function
succeeds or the records in the stream expire.

To test the preceding Python code (console)
1.

In the console, create a Lambda function using the hello-world blueprint. In runtime,
choose Python 3.7. In Handler, replace lambda_function.lambda_handler with
lambda_function.always_failed_handler. For instructions on how to do this, see Create a
Lambda Function with the Console (p. 3).

2.

Replace the template code with the code provided in this section.

3.

Test the Lambda function using the Sample event template called Hello World provided in the
Lambda console.

Function Error Handling
You can create custom error handling to raise an exception directly from your Lambda function and
handle it directly (Retry or Catch) within an AWS Step Functions State Machine. For more information,
see Handling Error Conditions Using a State Machine.
Consider a CreateAccount state is a task that writes a customer's details to a database using a Lambda
function.
• If the task succeeds, an account is created and a welcome email is sent.
• If a user tries to create an account for a username that already exists, the Lambda function raises an
error, causing the state machine to suggest a diﬀerent username and to retry the account-creation
process.
The following code samples demonstrate how to do this. Note that custom errors in Python must extend
the Exception class.
class AccountAlreadyExistsException(Exception): pass
def create_account(event, context):
raise AccountAlreadyExistsException('Account is in use!')

271

AWS Lambda Developer Guide
Tracing

You can conﬁgure Step Functions to catch the error using a Catch rule. Lambda automatically sets the
error name to the simple class name of the exception at runtime:
{

}

"StartAt": "CreateAccount",
"States": {
"CreateAccount": {
"Type": "Task",
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:CreateAccount",
"Next": "SendWelcomeEmail",
"Catch": [
{
"ErrorEquals": ["AccountAlreadyExistsException"],
"Next": "SuggestAccountName"
}
]
},
…
}

At runtime, AWS Step Functions catches the error, transitioning to the SuggestAccountName state as
speciﬁed in the Next transition.
Custom error handling makes it easier to create serverless applications. This feature integrates with
all the languages supported by the Lambda Programming Model (p. 18), allowing you to design your
application in the programming languages of your choice, mixing and matching as you go.
To learn more about creating your own serverless applications using AWS Step Functions and AWS
Lambda, see AWS Step Functions.

Instrumenting Python Code in AWS Lambda
In Python, you can have Lambda emit subsegments to X-Ray to show you information about downstream
calls to other AWS services made by your function. To do so, you ﬁrst need to include the the AWS X-Ray
SDK for Python in your deployment package. In addition, you can patch the boto3 (or botocore if you
are using sessions), so any client you create to access other AWS services will automatically be traced by
X-Ray.
import boto3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch
patch(['boto3'])

Once you've patched the module you are using to create clients, you can use it to create your traced
clients, in the case below Amazon S3:
s3_client = boto3.client('s3')

The X-Ray SDK for Python creates a subsegment for the call and records information from
the request and response. You can use the aws_xray_sdk_sdk.core.xray_recorder to
create subsegments automatically by decorating your Lambda functions or manually by calling
xray_recorder.begin_subsegment() and xray_recorder.end_subsegment() inside the
function, as shown in the following Lambda function.

272

AWS Lambda Developer Guide
Tracing

import boto3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch
patch(['boto3'])
s3_client = boto3.client('s3')
def lambda_handler(event, context):
bucket_name = event['bucket_name']
bucket_key = event['bucket_key']
body = event['body']
put_object_into_s3(bucket_name, bucket_key, body)
get_object_from_s3(bucket_name, bucket_key)
# Define subsegments manually
def put_object_into_s3(bucket_name, bucket_key, body):
try:
xray_recorder.begin_subsegment('put_object')
response = s3_client.put_object(Bucket=bucket_name, Key=bucket_key, Body=body)
status_code = response['ResponseMetadata']['HTTPStatusCode']
xray_recorder.current_subsegment().put_annotation('put_response', status_code)
finally:
xray_recorder.end_subsegment()
# Use decorators to automatically set the subsegments
@xray_recorder.capture('get_object')
def get_object_from_s3(bucket_name, bucket_key):
response = s3_client.get_object(Bucket=bucket_name, Key=bucket_key)
status_code = response['ResponseMetadata']['HTTPStatusCode']
xray_recorder.current_subsegment().put_annotation('get_response', status_code)

Note

The X-Ray SDK for Python allows you to patch the following modules:
• botocore
• boto3
• requests
• sqlite3
• mysql
You can use patch_all() to patch all of them at once.
Following is what a trace emitted by the code preceding looks like (synchronous invocation):

273

AWS Lambda Developer Guide
Tracing

274

AWS Lambda Developer Guide

Building Lambda Functions with Java
The following sections explain how common programming patterns and core concepts apply when
authoring Lambda function code in Java.

Java Runtimes
Name

Identiﬁer

JDK

Java 8

java8

java-1.8.0-openjdk

Topics
• AWS Lambda Deployment Package in Java (p. 276)
• AWS Lambda Function Handler in Java (p. 283)
• AWS Lambda Context Object in Java (p. 293)
• AWS Lambda Function Logging in Java (p. 294)
• AWS Lambda Function Errors in Java (p. 298)
• Instrumenting Java Code in AWS Lambda (p. 300)
• Create a Lambda Function Authored in Java (p. 302)
Additionally, note that AWS Lambda provides the following libraries:
• aws-lambda-java-core – This library provides the Context object, RequestStreamHandler, and the
RequestHandler interfaces. The Context object (AWS Lambda Context Object in Java (p. 293))
provides runtime information about your Lambda function. The predeﬁned interfaces provide one way
of deﬁning your Lambda function handler. For more information, see Leveraging Predeﬁned Interfaces
for Creating Handler (Java) (p. 289).
• aws-lambda-java-events – This library provides predeﬁned types that you can use when writing
Lambda functions to process events published by Amazon S3, Kinesis, Amazon SNS, and Amazon
Cognito. These classes help you process the event without having to write your own custom
serialization logic.
• Custom Appender for Log4j2.8 – You can use the custom Log4j (see Apache Log4j 2) appender
provided by AWS Lambda for logging from your lambda functions. Every call to Log4j methods, such
as log.info() or log.error(), will result in a CloudWatch Logs event. The custom appender is called
LambdaAppender and must be used in the log4j2.xml ﬁle. You must include the aws-lambda-javalog4j2 artifact (artifactId:aws-lambda-java-log4j2) in the deployment package (.jar ﬁle).For more
information, see AWS Lambda Function Logging in Java (p. 294).
• Custom Appender for Log4j1.2 – You can use the custom Log4j (see Apache Log4j 1.2) appender
provided by AWS Lambda for logging from your lambda functions. For more information, see AWS
Lambda Function Logging in Java (p. 294).

Note

Support for the Log4j v1.2 custom appender is marked for End-Of-Life. It will not receive
ongoing updates and is not recommended for use.
These libraries are available through the Maven Central Repository and can also be found on GitHub.

275

AWS Lambda Developer Guide
Deployment Package

AWS Lambda Deployment Package in Java
Your deployment package can be a .zip ﬁle or a standalone jar; it is your choice. You can use any build
and packaging tool you are familiar with to create a deployment package.
We provide examples of using Maven to create standalone jars and using Gradle to create a .zip ﬁle. For
more information, see the following topics:
Topics
• Creating a .jar Deployment Package Using Maven without any IDE (Java) (p. 276)
• Creating a .jar Deployment Package Using Maven and Eclipse IDE (Java) (p. 278)
• Creating a .zip Deployment Package (Java) (p. 280)
• Authoring Lambda Functions Using Eclipse IDE and AWS SDK Plugin (Java) (p. 283)

Creating a .jar Deployment Package Using Maven
without any IDE (Java)
This section shows how to package your Java code into a deployment package using Maven at the
command line.
Topics
• Before You Begin (p. 276)
• Project Structure Overview (p. 276)
• Step 1: Create Project (p. 277)
• Step 2: Build Project (Create Deployment Package) (p. 278)

Before You Begin
You will need to install the Maven command-line build tool. For more information, go to Maven. If you
are using Linux, check your package manager.
sudo apt-get install mvn

if you are using Homebrew
brew install maven

Project Structure Overview
After you set up the project, you should have the following folder structure:
project-dir/pom.xml
project-dir/src/main/java/

(your code goes here)

Your code will then be in the /java folder. For example, if your package name is example and you have a
Hello.java class in it, the structure will be:

276

AWS Lambda Developer Guide
Creating a .jar Deployment Package
Using Maven without any IDE (Java)
project-dir/src/main/java/example/Hello.java

After you build the project, the resulting .jar ﬁle (that is, your deployment package), will be in the
project-dir/target subdirectory.

Step 1: Create Project
Follow the steps in this section to create a Java project.
1.
2.

Create a project directory (project-dir).
In the project-dir directory, create the following:
• Project Object Model ﬁle, pom.xml. Add the following project information and conﬁguration
details for Maven to build the project.

4.0.0
doc-examples
lambda-java-example
jar
1.0-SNAPSHOT
lambda-java-example


com.amazonaws
aws-lambda-java-core
1.1.0





org.apache.maven.plugins
maven-shade-plugin
2.3

false



package

shade








Note
• In the dependencies section, the groupId (that is, com.amazonaws) is the Amazon
AWS group ID for Maven artifacts in the Maven Central Repository. The artifactId
(that is, aws-lambda-java-core) is the AWS Lambda core library that provides deﬁnitions

277

AWS Lambda Developer Guide
Creating a .jar Deployment Package
Using Maven and Eclipse IDE (Java)

of the RequestHandler, RequestStreamHandler, and the Context AWS Lambda
interfaces for use in your Java application. At the build time Maven resolves these
dependencies.
• In the plugins section, the Apache maven-shade-plugin is a plugin that Maven will
download and use during your build process. This plugin is used for packaging jars to
create a standalone .jar (a .zip ﬁle), your deployment package.
• If you are following other tutorial topics in this guide, the speciﬁc tutorials might
require you to add more dependencies. Make sure to add those dependencies as
required.
3.

In the project-dir, create the following structure:
project-dir/src/main/java

4.

Under the /java subdirectory you add your Java ﬁles and folder structure, if any. For example, if
you Java package name is example, and source code is Hello.java, your directory structure looks
like this:
project-dir/src/main/java/example/Hello.java

Step 2: Build Project (Create Deployment Package)
Now you can build the project using Maven at the command line.
1.

At a command prompt, change directory to the project directory (project-dir).

2.

Run the following mvn command to build the project:
$ mvn package

The resulting .jar is saved as project-dir/target/lambda-java-example-1.0SNAPSHOT.jar. The .jar name is created by concatenating the artifactId and version in the
pom.xml ﬁle.
The build creates this resulting .jar, using information in the pom.xml to do the necessary
transforms. This is a standalone .jar (.zip ﬁle) that includes all the dependencies. This is your
deployment package that you can upload to AWS Lambda to create a Lambda function.

Creating a .jar Deployment Package Using Maven and
Eclipse IDE (Java)
This section shows how to package your Java code into a deployment package using Eclipse IDE and
Maven plugin for Eclipse.
Topics
• Before You Begin (p. 278)
• Step 1: Create and Build a Project (p. 279)

Before You Begin
Install the Maven Plugin for Eclipse.
278

AWS Lambda Developer Guide
Creating a .jar Deployment Package
Using Maven and Eclipse IDE (Java)

1.

Start Eclipse. From the Help menu in Eclipse, choose Install New Software.

2.

In the Install window, type http://download.eclipse.org/technology/m2e/releases in
the Work with: box, and choose Add.

3.

Follow the steps to complete the setup.

Step 1: Create and Build a Project
In this step, you start Eclipse and create a Maven project. You will add the necessary dependencies, and
build the project. The build will produce a .jar, which is your deployment package.
1.

Create a new Maven project in Eclipse.
a.

From the File menu, choose New, and then choose Project.

b.

In the New Project window, choose Maven Project.

c.

In the New Maven Project window, choose Create a simple project, and leave other default
selections.

d.

In the New Maven Project, Conﬁgure project windows, type the following Artifact information:
• Group Id: doc-examples
• Artifact Id: lambda-java-example
• Version: 0.0.1-SNAPSHOT
• Packaging: jar
• Name: lambda-java-example

2.

Add the aws-lambda-java-core dependency to the pom.xml ﬁle.
It provides deﬁnitions of the RequestHandler, RequestStreamHandler, and Context interfaces.
This allows you to compile code that you can use with AWS Lambda.
a.

Open the context (right-click) menu for the pom.xml ﬁle, choose Maven, and then choose Add
Dependency.

b.

In the Add Dependency windows, type the following values:
Group Id: com.amazonaws
Artifact Id: aws-lambda-java-core
Version: 1.1.0

Note

If you are following other tutorial topics in this guide, the speciﬁc tutorials might
require you to add more dependencies. Make sure to add those dependencies as
required.
3.

Add Java class to the project.
a.

Open the context (right-click) menu for the src/main/java subdirectory in the project, choose
New, and then choose Class.

b.

In the New Java Class window, type the following values:
• Package: example
• Name: Hello

Note

If you are following other tutorial topics in this guide, the speciﬁc tutorials might
recommend diﬀerent package name or class name.
279

AWS Lambda Developer Guide
Creating a .zip Deployment Package (Java)

c.
4.

Add your Java code. If you are following other tutorial topics in this guide, add the provided
code.

Build the project.
Open the context (right-click) menu for the project in Package Explorer, choose Run As, and then
choose Maven Build .... In the Edit Conﬁguration window, type package in the Goals box.

Note

The resulting .jar, lambda-java-example-0.0.1-SNAPSHOT.jar, is not the ﬁnal
standalone .jar that you can use as your deployment package. In the next step, you add the
Apache maven-shade-plugin to create the standalone .jar. For more information, go to
Apache Maven Shade Plugin.
5.

Add the maven-shade-plugin plugin and rebuild.
The maven-shade-plugin will take artifacts (jars) produced by the package goal (produces customer
code .jar), and created a standalone .jar that contains the compiled customer code, and the resolved
dependencies from the pom.xml.
a.

Open the context (right-click) menu for the pom.xml ﬁle, choose Maven, and then choose Add
Plugin.

b.

In the Add Plugin window, type the following values:
• Group Id: org.apache.maven.plugins
• Artifact Id: maven-shade-plugin
• Version: 2.3

c.

Now build again.
This time we will create the jar as before, and then use the maven-shade-plugin to pull in
dependencies to make the standalone .jar.
i.

Open the context (right-click) menu for the project, choose Run As, and then choose Maven
build ....

ii.

In the Edit Conﬁguration windows, type package shade:shade in the Goals box.

iii. Choose Run.
You can ﬁnd the resulting standalone .jar (that is, your deployment package), in the /
target subdirectory.
Open the context (right-click) menu for the /target subdirectory, choose Show In, choose
System Explorer, and you will ﬁnd the lambda-java-example-0.0.1-SNAPSHOT.jar.

Creating a .zip Deployment Package (Java)
This section provides examples of creating .zip ﬁle as your deployment package. You can use any build
and packaging tool you like to create this zip. Regardless of the tools you use, the resulting .zip ﬁle must
have the following structure:
• All compiled class ﬁles and resource ﬁles at the root level.
• All required jars to run the code in the /lib directory.

Note

You can also build a standalone .jar (also a zipped ﬁle) as your deployment package. For
examples of creating standalone .jar using Maven, see AWS Lambda Deployment Package in
Java (p. 276).
280

AWS Lambda Developer Guide
Creating a .zip Deployment Package (Java)

The following examples use Gradle build and deployment tool to create the .zip.

Important

Gradle version 2.0 or later is required.

Before You Begin
You will need to download Gradle. For instructions, go to the gradle website, https://gradle.org/ .

Example 1: Creating .zip Using Gradle and the Maven Central
Repository
At the end of this walkthrough, you will have a project directory (project-dir) with content having the
following structure:
project-dir/build.gradle
project-dir/src/main/java/

The /java folder will contain your code. For example, if your package name is example, and you have a
Hello.java class in it, the structure will be:
project-dir/src/main/java/example/Hello.java

After you build the project, the resulting .zip ﬁle (that is, your deployment package), will be in the
project-dir/build/distributions subdirectory.
1.

Create a project directory (project-dir).

2.

In the project-dir, create build.gradle ﬁle and add the following content:
apply plugin: 'java'
repositories {
mavenCentral()
}
dependencies {
compile (
'com.amazonaws:aws-lambda-java-core:1.1.0',
'com.amazonaws:aws-lambda-java-events:1.1.0'
)
}
task buildZip(type: Zip) {
from compileJava
from processResources
into('lib') {
from configurations.compileClasspath
}
}
build.dependsOn buildZip

Note
• The repositories section refers to Maven Central Repository. At the build time, it fetches
the dependencies (that is, the two AWS Lambda libraries) from Maven Central.
• The buildZip task describes how to create the deployment package .zip ﬁle.
281

AWS Lambda Developer Guide
Creating a .zip Deployment Package (Java)

For example, if you unzip the resulting .zip ﬁle you should ﬁnd any of the compiled class
ﬁles and resource ﬁles at the root level. You should also ﬁnd a /lib directory with the
required jars for running the code.
• If you are following other tutorial topics in this guide, the speciﬁc tutorials might require
you to add more dependencies. Make sure to add those dependencies as required.
3.

In the project-dir, create the following structure:
project-dir/src/main/java/

4.

Under the /java subdirectory you add your Java ﬁles and folder structure, if any. For example, if
you Java package name is example, and source code is Hello.java, then your directory structure
looks like this:
project-dir/src/main/java/example/Hello.java

5.

Run the following gradle command to build and package the project in a .zip ﬁle.
project-dir> gradle build

6.

Verify the resulting project-dir.zip ﬁle in the project-dir/build/distributions
subdirectory.

7.

Now you can upload the .zip ﬁle, your deployment package to AWS Lambda to create a Lambda
function and test it by manually invoking it using sample event data. For instruction, see Create a
Lambda Function Authored in Java (p. 302).

Example 2: Creating .zip Using Gradle Using Local Jars
You may choose not to use the Maven Central repository. Instead have all the dependencies in the
project folder. In this case your project folder (project-dir) will have the following structure:
project-dir/jars/
project-dir/build.gradle
project-dir/src/main/java/

(all jars go here)
(your code goes here)

So if your Java code has example package and Hello.java class, the code will be in the following
subdirectory:
project-dir/src/main/java/example/Hello.java

You build.gradle ﬁle should be as follows:
apply plugin: 'java'
dependencies {
compile fileTree(dir: 'jars', include: '*.jar')
}
task buildZip(type: Zip) {
from compileJava
from processResources
into('lib') {
from configurations.compileClasspath
}
}

282

AWS Lambda Developer Guide
Authoring Lambda Functions Using
Eclipse IDE and AWS SDK Plugin (Java)
build.dependsOn buildZip

Note that the dependencies specify fileTree which identiﬁes project-dir/jars as the subdirectory
that will include all the required jars.
Now you build the package. Run the following gradle command to build and package the project in a .zip
ﬁle.
project-dir> gradle build

Authoring Lambda Functions Using Eclipse IDE and
AWS SDK Plugin (Java)
AWS SDK Eclipse Toolkit provides an Eclipse plugin for you to both create a deployment package and
also upload it to create a Lambda function. If you can use Eclipse IDE as your development environment,
this plugin enables you to author Java code, create and upload a deployment package, and create your
Lambda function. For more information, see the AWS Toolkit for Eclipse Getting Started Guide. For an
example of using the toolkit for authoring Lambda functions, see Using AWS Lambda with the AWS
Toolkit for Eclipse.

AWS Lambda Function Handler in Java
At the time you create a Lambda function you specify a handler that AWS Lambda can invoke when the
service executes the Lambda function on your behalf.
Lambda supports two approaches for creating a handler:
• Loading the handler method directly without having to implement an interface. This section describes
this approach.
• Implementing standard interfaces provided as part of aws-lambda-java-core library (interface
approach). For more information, see Leveraging Predeﬁned Interfaces for Creating Handler
(Java) (p. 289).
The general syntax for the handler is as follows:
outputType handler-name(inputType input, Context context) {
...
}

In order for AWS Lambda to successfully invoke a handler it must be invoked with input data that can be
serialized into the data type of the input parameter.
In the syntax, note the following:
• inputType – The ﬁrst handler parameter is the input to the handler, which can be event data
(published by an event source) or custom input that you provide such as a string or any custom data
object. In order for AWS Lambda to successfully invoke this handler, the function must be invoked with
input data that can be serialized into the data type of the input parameter.
• outputType – If you plan to invoke the Lambda function synchronously (using the
RequestResponse invocation type), you can return the output of your function using any of the
supported data types. For example, if you use a Lambda function as a mobile application backend, you
are invoking it synchronously. Your output data type will be serialized into JSON.

283

AWS Lambda Developer Guide
Handler Overload Resolution

If you plan to invoke the Lambda function asynchronously (using the Event invocation type), the
outputType should be void. For example, if you use AWS Lambda with event sources such as
Amazon S3 or Amazon SNS, these event sources invoke the Lambda function using the Event
invocation type.
• The inputType and outputType can be one of the following:
• Primitive Java types (such as String or int).
• Predeﬁned AWS event types deﬁned in the aws-lambda-java-events library.
For example S3Event is one of the POJOs predeﬁned in the library that provides methods for you
to easily read information from the incoming Amazon S3 event.
• You can also write your own POJO class. AWS Lambda will automatically serialize and deserialize
input and output JSON based on the POJO type.
For more information, see Handler Input/Output Types (Java) (p. 285).
• You can omit the Context object from the handler method signature if it isn't needed. For more
information, see AWS Lambda Context Object in Java (p. 293).
For example, consider the following Java example code.
package example;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
public class Hello implements RequestHandler{
public String myHandler(int myCount, Context context) {
return String.valueOf(myCount);
}
}

In this example input is of type Integer and output is of type String. If you package this code and
dependencies, and create your Lambda function, you specify example.Hello::myHandler
(package.class::method-reference) as the handler.
In the example Java code, the ﬁrst handler parameter is the input to the handler (myHandler), which can
be event data (published by an event source such as Amazon S3) or custom input you provide such as an
Integer object (as in this example) or any custom data object.
For instructions to create a Lambda function using this Java code, see Create a Lambda Function
Authored in Java (p. 302).

Handler Overload Resolution
If your Java code contains multiple methods with same name as the handler name, then AWS Lambda
uses the following rules to pick a method to invoke:
1. Select the method with the largest number of parameters.
2. If two or more methods have the same number of parameters, AWS Lambda selects the method that
has the Context as the last parameter.
If none or all of these methods have the Context parameter, then the behavior is undeﬁned.

Additional Information
The following topics provide more information about the handler.

284

AWS Lambda Developer Guide
Handler Input/Output Types (Java)

• For more information about the handler input and output types, see Handler Input/Output Types
(Java) (p. 285).
• For information about using predeﬁned interfaces to create a handler, see Leveraging Predeﬁned
Interfaces for Creating Handler (Java) (p. 289).
If you implement these interfaces, you can validate your handler method signature at compile time.
• If your Lambda function throws an exception, AWS Lambda records metrics in CloudWatch indicating
that an error occurred. For more information, see AWS Lambda Function Errors in Java (p. 298).

Handler Input/Output Types (Java)
When AWS Lambda executes the Lambda function, it invokes the handler. The ﬁrst parameter is the
input to the handler which can be event data (published by an event source) or custom input you provide
such as a string or any custom data object.
AWS Lambda supports the following input/output types for a handler:
• Simple Java types (AWS Lambda supports the String, Integer, Boolean, Map, and List types)
• POJO (Plain Old Java Object) type
• Stream type (If you do not want to use POJOs or if Lambda's serialization approach does not meet
your needs, you can use the byte stream implementation. For more information, see Example: Using
Stream for Handler Input/Output (Java) (p. 288).)

Handler Input/Output: String Type
The following Java class shows a handler called myHandler that uses String type for input and output.
package example;
import com.amazonaws.services.lambda.runtime.Context;
public class Hello {
public String myHandler(String name, Context context) {
return String.format("Hello %s.", name);
}
}

You can have similar handler functions for other simple Java types.

Note

When you invoke a Lambda function asynchronously, any return value by your Lambda function
will be ignored. Therefore you might want to set the return type to void to make this clear in
your code. For more information, see Invoke (p. 410).
To test an end-to-end example, see Create a Lambda Function Authored in Java (p. 302).

Handler Input/Output: POJO Type
The following Java class shows a handler called myHandler that uses POJOs for input and output.
package example;
import com.amazonaws.services.lambda.runtime.Context;
public class HelloPojo {

285

AWS Lambda Developer Guide
Handler Input/Output Types (Java)
// Define two classes/POJOs for use with Lambda function.
public static class RequestClass {
...
}
public static class ResponseClass {
...
}
public static ResponseClass myHandler(RequestClass request, Context context) {
String greetingString = String.format("Hello %s, %s.", request.getFirstName(),
request.getLastName());
return new ResponseClass(greetingString);
}

}

AWS Lambda serializes based on standard bean naming conventions (see The Java EE 6 Tutorial). You
should use mutable POJOs with public getters and setters.

Note

You shouldn't rely on any other features of serialization frameworks such as annotations. If you
need to customize the serialization behavior, you can use the raw byte stream to use your own
serialization.
If you use POJOs for input and output, you need to provide implementation of the RequestClass
and ResponseClass types. For an example, see Example: Using POJOs for Handler Input/Output
(Java) (p. 286).

Example: Using POJOs for Handler Input/Output (Java)
Suppose your application events generate data that includes ﬁrst name and last name as shown:
{ "firstName": "John", "lastName": "Doe" }

For this example, the handler receives this JSON and returns the string "Hello John Doe".
public static ResponseClass handleRequest(RequestClass request, Context context){
String greetingString = String.format("Hello %s, %s.", request.firstName,
request.lastName);
return new ResponseClass(greetingString);
}

To create a Lambda function with this handler, you must provide implementation of the input and
output types as shown in the following Java example. The HelloPojo class deﬁnes the handler
method.
package example;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
public class HelloPojo implements RequestHandler{
public ResponseClass handleRequest(RequestClass request, Context context){
String greetingString = String.format("Hello %s, %s.", request.firstName,
request.lastName);
return new ResponseClass(greetingString);
}

}

286

AWS Lambda Developer Guide
Handler Input/Output Types (Java)

In order to implement the input type, add the following code to a separate ﬁle and name it
RequestClass.java. Place it next to the HelloPojo.java class in your directory structure:
package example;
public class RequestClass {
String firstName;
String lastName;
public String getFirstName() {
return firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
return lastName;
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
public RequestClass(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}

}

public RequestClass() {
}

In order to implement the output type, add the following code to a separate ﬁle and name it
ResponseClass.java. Place it next to the HelloPojo.java class in your directory structure:
package example;
public class ResponseClass {
String greetings;
public String getGreetings() {
return greetings;
}
public void setGreetings(String greetings) {
this.greetings = greetings;
}
public ResponseClass(String greetings) {
this.greetings = greetings;
}
public ResponseClass() {
}
}

Note

The get and set methods are required in order for the POJOs to work with AWS Lambda's built
in JSON serializer. The constructors that take no arguments are usually not required, however

287

AWS Lambda Developer Guide
Handler Input/Output Types (Java)

in this example we provided other constructors and therefore we need to explicitly provide the
zero argument constructors.
You can upload this code as your Lambda function and test as follows:
• Using the preceding code ﬁles, create a deployment package.
• Upload the deployment package to AWS Lambda and create your Lambda function. You can do this
using the console or AWS CLI.
• Invoke the Lambda function manually using the console or the CLI. You can use provide sample JSON
event data when you manually invoke your Lambda function. For example:
{ "firstName":"John", "lastName":"Doe" }

For more information, see Create a Lambda Function Authored in Java (p. 302). Note the following
diﬀerences:
• When you create a deployment package, don't forget the aws-lambda-java-core library
dependency.
• When you create the Lambda function, specify example.HelloPojo::handleRequest
(package.class::method) as the handler value.

Example: Using Stream for Handler Input/Output (Java)
If you do not want to use POJOs or if Lambda's serialization approach does not meet your needs, you can
use the byte stream implementation. In this case, you can use the InputStream and OutputStream as
the input and output types for the handler. An example handler function is shown:
public void handler(InputStream inputStream, OutputStream outputStream, Context context)
throws IOException{
...
}

Note that in this case the handler function uses parameters for both the request and response streams.
The following is a Lambda function example that implements the handler that uses InputStream and
OutputStream types for the input and output parameters.

Note

The input payload must be valid JSON but the output stream does not carry such a restriction.
Any bytes are supported.
package example;
import
import
import
import

java.io.InputStream;
java.io.OutputStream;
com.amazonaws.services.lambda.runtime.RequestStreamHandler;
com.amazonaws.services.lambda.runtime.Context;

public class Hello implements RequestStreamHandler{
public void handler(InputStream inputStream, OutputStream outputStream, Context
context) throws IOException {
int letter;
while((letter = inputStream.read()) != -1)
{
outputStream.write(Character.toUpperCase(letter));
}
}

288

AWS Lambda Developer Guide
Leveraging Predeﬁned Interfaces
for Creating Handler (Java)
}

You can do the following to test the code:
• Using the preceding code, create a deployment package.
• Upload the deployment package to AWS Lambda and create your Lambda function. You can do this
using the console or AWS CLI.
• You can manually invoke the code by providing sample input. For example:
test

Follow instructions provided in the Getting Started. For more information, see Create a Lambda Function
Authored in Java (p. 302). Note the following diﬀerences:
• When you create a deployment package, don't forget the aws-lambda-java-core library
dependency.
• When you create the Lambda function, specify example.Hello::handler
(package.class::method) as the handler value.

Leveraging Predeﬁned Interfaces for Creating
Handler (Java)
You can use one of the predeﬁned interfaces provided by the AWS Lambda Java core library (awslambda-java-core) to create your Lambda function handler, as an alternative to writing your own
handler method with an arbitrary name and parameters. For more information about handlers, see (see
AWS Lambda Function Handler in Java (p. 283)).
You can implement one of the predeﬁned interfaces, RequestStreamHandler or RequestHandler
and provide implementation for the handleRequest method that the interfaces provide. You
implement one of these interfaces depending on whether you want to use standard Java types or
custom POJO types for your handler input/output (where AWS Lambda automatically serializes and
deserializes the input and output to Match your data type), or customize the serialization using the
Stream type.

Note

These interfaces are available in the aws-lambda-java-core library.
When you implement standard interfaces, they help you validate your method signature at compile time.
If you implement one of the interfaces, you specify package.class in your Java code as the handler
when you create the Lambda function. For example, the following is the modiﬁed create-function
CLI command from the getting started. Note that the --handler parameter speciﬁes "example.Hello"
value:
aws lambda create-function \
--region region \
--function-name getting-started-lambda-function-in-java \
--zip-file fileb://deployment-package (zip or jar)
path \
--role arn:aws:iam::account-id:role/lambda_basic_execution
--handler example.Hello \
--runtime java8 \
--timeout 15 \
--memory-size 512

289

\

AWS Lambda Developer Guide
Leveraging Predeﬁned Interfaces
for Creating Handler (Java)

The following sections provide examples of implementing these interfaces.

Example 1: Creating Handler with Custom POJO Input/Output
(Leverage the RequestHandler Interface)
The example Hello class in this section implements the RequestHandler interface. The interface
deﬁnes handleRequest() method that takes in event data as input parameter of the Request type
and returns an POJO object of the Response type:
public Response handleRequest(Request request, Context context) {
...
}

The Hello class with sample implementation of the handleRequest() method is shown. For this
example, we assume event data consists of ﬁrst name and last name.
package example;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.Context;
public class Hello implements RequestHandler {
public Response handleRequest(Request request, Context context) {
String greetingString = String.format("Hello %s %s.", request.firstName,
request.lastName);
return new Response(greetingString);
}

}

For example, if the event data in the Request object is:
{
}

"firstName":"value1",
"lastName" : "value2"

The method returns a Response object as follows:
{
}

"greetings": "Hello value1 value2."

Next, you need to implement the Request and Response classes. You can use the following
implementation for testing:
The Request class:
package example;
public class Request {
String firstName;
String lastName;
public String getFirstName() {
return firstName;
}

290

AWS Lambda Developer Guide
Leveraging Predeﬁned Interfaces
for Creating Handler (Java)
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
return lastName;
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
public Request(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}
public Request() {
}

}

The Response class:
package example;
public class Response {
String greetings;
public String getGreetings() {
return greetings;
}
public void setGreetings(String greetings) {
this.greetings = greetings;
}
public Response(String greetings) {
this.greetings = greetings;
}
public Response() {
}

}

You can create a Lambda function from this code and test the end-to-end experience as follows:
• Using the preceding code, create a deployment package. For more information, see AWS Lambda
Deployment Package in Java (p. 276)
• Upload the deployment package to AWS Lambda and create your Lambda function.
• Test the Lambda function using either the console or CLI. You can specify any sample JSON data that
conform to the getter and setter in your Request class, for example:
{
}

"firstName":"John",
"lastName" : "Doe"

The Lambda function will return the following JSON in response.
{

"greetings": "Hello John, Doe."

291

AWS Lambda Developer Guide
Leveraging Predeﬁned Interfaces
for Creating Handler (Java)
}

Follow instructions provided in the getting started (see Create a Lambda Function Authored in
Java (p. 302)). Note the following diﬀerences:
• When you create a deployment package, don't forget the aws-lambda-java-core library
dependency.
• When you create the Lambda function specify example.Hello (package.class) as the handler
value.

Example 2: Creating Handler with Stream Input/Output
(Leverage the RequestStreamHandler Interface)
The Hello class in this example implements the RequestStreamHandler interface. The interface
deﬁnes handleRequest method as follows:
public void handleRequest(InputStream inputStream, OutputStream outputStream, Context
context)
throws IOException {
...
}

The Hello class with sample implementation of the handleRequest() handler is shown. The handler
processes incoming event data (for example, a string "hello") by simply converting it to uppercase and
return it.
package example;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import com.amazonaws.services.lambda.runtime.RequestStreamHandler;
import com.amazonaws.services.lambda.runtime.Context;
public class Hello implements RequestStreamHandler {
public void handleRequest(InputStream inputStream, OutputStream outputStream, Context
context)
throws IOException {
int letter;
while((letter = inputStream.read()) != -1)
{
outputStream.write(Character.toUpperCase(letter));
}
}
}

You can create a Lambda function from this code and test the end-to-end experience as follows:
• Use the preceding code to create deployment package.
• Upload the deployment package to AWS Lambda and create your Lambda function.
• Test the Lambda function using either the console or CLI. You can specify any sample string data, for
example:
"test"

292

AWS Lambda Developer Guide
Context

The Lambda function will return TEST in response.
Follow instructions provided in the getting started (see Create a Lambda Function Authored in
Java (p. 302)). Note the following diﬀerences:
• When you create a deployment package, don't forget the aws-lambda-java-core library
dependency.
• When you create the Lambda function specify example.Hello (package.class) as the handler
value.

AWS Lambda Context Object in Java
When Lambda runs your function, it passes a context object to the handler (p. 283). This object
provides methods and properties that provide information about the invocation, function, and execution
environment.

Context Methods
• getRemainingTimeInMillis() – Returns the number of milliseconds left before the execution
times out.
• getFunctionName() – Returns the name of the Lambda function.
• getFunctionVersion() – Returns the version (p. 30) of the function.
• getInvokedFunctionArn() – Returns the Amazon Resource Name (ARN) used to invoke the
function. Indicates if the invoker speciﬁed a version number or alias.
• getMemoryLimitInMB() – Returns the amount of memory conﬁgured on the function.
• getAwsRequestId() – Returns the identiﬁer of the invocation request.
• getLogGroupName() – Returns the log group for the function.
• getLogStreamName() – Returns the log stream for the function instance.
• getIdentity() – (mobile apps) Returns information about the Amazon Cognito identity that
authorized the request.
• getClientContext() – (mobile apps) Returns the client context provided to the Lambda invoker by
the client application.
• getLogger() – Returns the logger object (p. 294) for the function.
The following example shows a handler function that logs context information.

Example ContextLogger.java
package example;
import java.io.InputStream;
import java.io.OutputStream;
import com.amazonaws.services.lambda.runtime.Context;
public class ContextLogger {
public static void myHandler(InputStream inputStream, OutputStream outputStream,
Context context) {
int letter;
try {
while((letter = inputStream.read()) != -1)
{
outputStream.write(Character.toUpperCase(letter));
}

293

AWS Lambda Developer Guide
Logging
Thread.sleep(3000); // Intentional delay for testing the
getRemainingTimeInMillis() result.
}
catch (Exception e)
{
e.printStackTrace();
}
// Print info from the context object
System.out.println("Function name: " + context.getFunctionName());
System.out.println("Max mem allocated: " + context.getMemoryLimitInMB());
System.out.println("Time remaining in milliseconds: " +
context.getRemainingTimeInMillis());
System.out.println("CloudWatch log stream name: " + context.getLogStreamName());
System.out.println("CloudWatch log group name: " + context.getLogGroupName());
}

}

Dependencies
• aws-lambda-java-core
Build the code with the Lambda library dependencies to create a deployment package. For instructions,
see AWS Lambda Deployment Package in Java (p. 276).

AWS Lambda Function Logging in Java
Your Lambda function can contain logging statements. AWS Lambda writes these logs to CloudWatch.
We recommend you use one of the following to write logs.

Custom Appender for Log4j™ 2
AWS Lambda recommends Log4j 2 to provide a custom appender. You can use the custom Log4j (see
Apache log4j) appender provided by Lambda for logging from your lambda functions. Every call to Log4j
methods, such as log.info() or log.error(), will result in a CloudWatch Logs event. The custom
appender is called LambdaAppender and must be used in the log4j2.xml ﬁle. You must include the
aws-lambda-java-log4j2 artifact (artifactId:aws-lambda-java-log4j2) in the deployment
package (.jar ﬁle). For an example, see Example 1: Writing Logs Using Log4J v2.8 (p. 295).

LambdaLogger.log()
Each call to LambdaLogger.log() results in a CloudWatch Logs event, provided the event size is within
the allowed limits. For information about CloudWatch Logs limits, see CloudWatch Logs Limits in the
Amazon CloudWatch User Guide. For an example, see Example 2: Writing Logs Using LambdaLogger
(Java) (p. 297).
In addition, you can also use the following statements in your Lambda function code to generate log
entries:
• System.out()
• System.err()
However, note that AWS Lambda treats each line returned by System.out and System.err as a
separate event. This works well when each output line corresponds to a single log entry. When a log
entry has multiple lines of output, AWS Lambda attempts to parse them using line breaks to identify
separate events. For example, the following logs the two words ("Hello" and "world") as two separate
events:

294

AWS Lambda Developer Guide
How to Find Logs

System.out.println("Hello \n world");

How to Find Logs
You can ﬁnd the logs that your Lambda function writes, as follows:
• Find logs in CloudWatch Logs. The context object (in the aws-lambda-java-core library) provides
the getLogStreamName() and the getLogGroupName() methods. Using these methods, you can
ﬁnd the speciﬁc log stream where logs are written.
• If you invoke a Lambda function via the console, the invocation type is always RequestResponse
(that is, synchronous execution) and the console displays the logs that the Lambda function writes
using the LambdaLogger object. AWS Lambda also returns logs from System.out and System.err
methods.
• If you invoke a Lambda function programmatically, you can add the LogType parameter to
retrieve the last 4 KB of log data that is written to CloudWatch Logs. For more information, see
Invoke (p. 410). AWS Lambda returns this log information in the x-amz-log-results header in the
response. If you use the AWS Command Line Interface to invoke the function, you can specify the -log-type parameter with value Tail.

Logging Examples (Java)
This section provides examples of using Custom Appender for Log4j and the LambdaLogger objects for
logging information.

Example 1: Writing Logs Using Log4J v2.8
• The following shows how to build your artifact with Maven to correctly include the Log4j v2.8 plugins:
• For Maven pom.xml:


...

com.amazonaws
aws-lambda-java-log4j2
1.0.0


org.apache.logging.log4j
log4j-core
2.8.2


org.apache.logging.log4j
log4j-api
2.8.2

....


• If using the Maven shade plugin, set the plugin conﬁguration as follows:


...

295

AWS Lambda Developer Guide
Logging Examples (Java)

org.apache.maven.plugins
maven-shade-plugin
2.4.3


package

shade








%d{yyyy-MM-dd HH:mm:ss} %X{AWSRequestId} %-5p %c{1}:%L - %m%n










Example 2: Writing Logs Using LambdaLogger (Java)
The following Java code example writes logs using both the System methods and the LambdaLogger
object to illustrate how they diﬀer when AWS Lambda logs information to CloudWatch.
package example;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.LambdaLogger;
public class Hello {
public String myHandler(String name, Context context) {
// System.out: One log statement but with a line break (AWS Lambda writes two
events to CloudWatch).
System.out.println("log data from stdout \n this is continuation of system.out");
// System.err: One log statement but with a line break (AWS Lambda writes two
events to CloudWatch).
System.err.println("log data from stderr \n this is continuation of system.err");
LambdaLogger logger = context.getLogger();
// Write log to CloudWatch using LambdaLogger.
logger.log("log data from LambdaLogger \n this is continuation of logger.log");
// Return will include the log stream name so you can look
// up the log later.
return String.format("Hello %s. log stream = %s", name,
context.getLogStreamName());
}

}

The following is sample of log entries in CloudWatch Logs.

297

AWS Lambda Developer Guide
Errors

Note:
• AWS Lambda parses the log string in each of the System.out.println() and
System.err.println() statements logs as two separate events (note the two down arrows in the
screenshot) because of the line break.
• The LambdaLogger.log() produce one CloudWatch event.
You can do the following to test the code:
• Using the code, create a deployment package.
• Upload the deployment package to AWS Lambda to create your Lambda function.
• To test your Lambda function use a string ("this is a test") as sample event. The handler code receives
the sample event but does nothing with it. It only shows how to write logs.
Follow the instructions provided in the Getting Started. For more information, see Create a Lambda
Function Authored in Java (p. 302). Note the following diﬀerences:
• When you create a deployment package, don't forget the aws-lambda-java-core library
dependency.
• When you create the Lambda function, specify example.Hello::myHandler
(package.class::method) as the handler value.

AWS Lambda Function Errors in Java
If your Lambda function throws an exception, AWS Lambda recognizes the failure and serializes the
exception information into JSON and returns it. Following is an example error message:
{

"errorMessage": "Name John Doe is invalid. Exception occurred...",
"errorType": "java.lang.Exception",
"stackTrace": [
"example.Hello.handler(Hello.java:9)",
"sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)",
"sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)",
"sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)",
"java.lang.reflect.Method.invoke(Method.java:497)"
]

}

Note that the stack trace is returned as the stackTrace JSON array of stack trace elements.

298

AWS Lambda Developer Guide
Function Error Handling

The method in which you get the error information back depends on the invocation type that you
speciﬁed at the time you invoked the function:
• RequestResponse invocation type (that is, synchronous execution): In this case, you get the error
message back.
For example, if you invoke a Lambda function using the Lambda console, the RequestResponse is
always the invocation type and the console displays the error information returned by AWS Lambda in
the Execution result section as shown in the following image.

• Event invocation type (that is, asynchronous execution): In this case AWS Lambda does not return
anything. Instead, it logs the error information in CloudWatch Logs and CloudWatch metrics.
Depending on the event source, AWS Lambda may retry the failed Lambda function. For example, if
Kinesis is the event source for the Lambda function, AWS Lambda retries the failed function until the
Lambda function succeeds or the records in the stream expire.

Function Error Handling
You can create custom error handling to raise an exception directly from your Lambda function and
handle it directly (Retry or Catch) within an AWS Step Functions State Machine. For more information,
see Handling Error Conditions Using a State Machine.
Consider a CreateAccount state is a task that writes a customer's details to a database using a Lambda
function.
• If the task succeeds, an account is created and a welcome email is sent.
• If a user tries to create an account for a username that already exists, the Lambda function raises an
error, causing the state machine to suggest a diﬀerent username and to retry the account-creation
process.
The following code samples demonstrate how to do this. Note that custom errors in Java must extend
the Exception class.
package com.example;
public static class AccountAlreadyExistsException extends Exception {
public AccountAlreadyExistsException(String message) {
super(message);
}
}
package com.example;

299

AWS Lambda Developer Guide
Tracing
import com.amazonaws.services.lambda.runtime.Context;
public class Handler {
public static void CreateAccount(String name, Context context) throws
AccountAlreadyExistsException {
throw new AccountAlreadyExistsException ("Account is in use!");
}
}

You can conﬁgure Step Functions to catch the error using a Catch rule. Lambda automatically sets the
error name to the fully-qualiﬁed class name of the exception at runtime:
{

}

"StartAt": "CreateAccount",
"States": {
"CreateAccount": {
"Type": "Task",
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:CreateAccount",
"Next": "SendWelcomeEmail",
"Catch": [
{
"ErrorEquals": ["com.example.AccountAlreadyExistsException"],
"Next": "SuggestAccountName"
}
]
},
…
}

At runtime, AWS Step Functions catches the error, transitioning to the SuggestAccountName state as
speciﬁed in the Next transition.
Custom error handling makes it easier to create serverless applications. This feature integrates with
all the languages supported by the Lambda Programming Model (p. 18), allowing you to design your
application in the programming languages of your choice, mixing and matching as you go.
To learn more about creating your own serverless applications using AWS Step Functions and AWS
Lambda, see AWS Step Functions.

Instrumenting Java Code in AWS Lambda
In Java, you can have Lambda emit subsegments to X-Ray to show you information regarding
downstream calls to other AWS services made by your function. To take advantage of this capability,
include the AWS X-Ray SDK for Java in your deployment package. No code changes are needed. As long
as you are using an AWS SDK version 1.11.48 or later, there is no need to add any additional code lines
for downstream calls from your function to be traced.
The AWS SDK will dynamically import the X-Ray SDK to emit subsegments for downstream calls made
by your function. By using the X-Ray SDK for Java, you can instrument your code in order to emit custom
subsegments and or add annotations to your X-Ray segments.
The following example uses the X-Ray SDK for Java to instrument a Lambda function to emit a custom
subsegment and send custom annotation to X-Ray:
package uptime;

300

AWS Lambda Developer Guide
Tracing
import
import
import
import

java.io.IOException;
java.time.Instant;
java.util.HashMap;
java.util.Map;

import
import
import
import
import

org.apache.commons.logging.Log;
org.apache.commons.logging.LogFactory;
org.apache.http.HttpResponse;
org.apache.http.client.HttpClient;
org.apache.http.client.methods.HttpGet;

import
import
import
import
import
import
import

com.amazonaws.regions.Regions;
com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
com.amazonaws.services.dynamodbv2.model.AttributeValue;
com.amazonaws.services.lambda.runtime.Context;
com.amazonaws.xray.AWSXRay;
com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;

public class Hello {
private static final Log logger = LogFactory.getLog(Hello.class);
private static final AmazonDynamoDB dynamoClient;
private static final HttpClient httpClient;
static {
dynamoClient =
AmazonDynamoDBClientBuilder.standard().withRegion(Regions.US_EAST_1).build();
httpClient = HttpClientBuilder.create().build();
}
public void checkUptime(Context context) {
AWSXRay.createSubsegment("makeRequest", (subsegment) -> {
HttpGet request = new HttpGet("https://aws.amazon.com/");
boolean is2xx = false;
try {
HttpResponse response = httpClient.execute(request);
is2xx = (response.getStatusLine().getStatusCode() / 100) == 2;
subsegment.putAnnotation("responseCode",
response.getStatusLine().getStatusCode());
} catch (IOException ioe) {
logger.error(ioe);
}
Map item = new HashMap<>();
item.put("Timestamp", new AttributeValue().withN("" +
Instant.now().getEpochSecond()));
item.put("2xx", new AttributeValue().withBOOL(is2xx));
dynamoClient.putItem("amazon-2xx", item);
});
}

}

Following is what a trace emitted by the code preceding looks like (synchronous invocation):

301

AWS Lambda Developer Guide
Sample Function

Create a Lambda Function Authored in Java
The blueprints provide sample code authored either in Python or Node.js. You can easily modify the
example using the inline editor in the console. However, if you want to author code for your Lambda
function in Java, there are no blueprints provided. Also, there is no inline editor for you to write Java
code in the AWS Lambda console.
That means, you must write your Java code and also create your deployment package outside the
console. After you create the deployment package, you can use the console to upload the package
to AWS Lambda to create your Lambda function. You can also use the console to test the function by
manually invoking it.
In this section you create a Lambda function using the following Java code example.
package example;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.LambdaLogger;
public class Hello {
public String myHandler(int myCount, Context context) {
LambdaLogger logger = context.getLogger();
logger.log("received : " + myCount);
return String.valueOf(myCount);
}
}

The programming model explains how to write your Java code in detail, for example the input/output
types AWS Lambda supports. For more information about the programming model, see Building Lambda
Functions with Java (p. 275). For now, note the following about this code:
• When you package and upload this code to create your Lambda function, you specify the
example.Hello::myHandler method reference as the handler.
• The handler in this example uses the int type for input and the String type for output.
AWS Lambda supports input/output of JSON-serializable types and InputStream/OutputStream types.
When you invoke this function you will pass a sample int (for example, 123).

302

AWS Lambda Developer Guide
Sample Function

• You can use the Lambda console to manually invoke this Lambda function. The console always uses
the RequestResponse invocation type (synchronous) and therefore you will see the response in the
console.
• The handler includes the optional Context parameter. In the code we use the LambdaLogger
provided by the Context object to write log entries to CloudWatch logs. For information about using
the Context object, see AWS Lambda Context Object in Java (p. 293).
First, you need to package this code and any dependencies into a deployment package. Then, you can
use the Getting Started exercise to upload the package to create your Lambda function and test using
the console. For more information creating a deployment package, see AWS Lambda Deployment
Package in Java (p. 276).

303

AWS Lambda Developer Guide
Deployment Package

Building Lambda Functions with Go
The following sections explain how common programming patterns and core concepts apply when
authoring Lambda function code in Go.

Go Runtimes
Name

Identiﬁer

Go 1.x

go1.x

Topics
• AWS Lambda Deployment Package in Go (p. 304)
• AWS Lambda Function Handler in Go (p. 305)
• AWS Lambda Context Object in Go (p. 309)
• AWS Lambda Function Logging in Go (p. 310)
• AWS Lambda Function Errors in Go (p. 312)
• Instrumenting Go Code in AWS Lambda (p. 313)
• Using Environment Variables (p. 315)
Additionally, note that AWS Lambda provides the following:
• github.com/aws/aws-lambda-go/lambda: The implementation of the Lambda programming
model for Go. This package is used by AWS Lambda to invoke your AWS Lambda Function Handler in
Go (p. 305).
• github.com/aws/aws-lambda-go/lambdacontext: Helpers for accessing execution context
information from the AWS Lambda Context Object in Go (p. 309).
• github.com/aws/aws-lambda-go/events: This library provides type deﬁnitions for common event
source integrations.

AWS Lambda Deployment Package in Go
To create a Lambda function you ﬁrst create a Lambda function deployment package, a .zip ﬁle
consisting of your code and any dependencies.
After you create a deployment package, you may either upload it directly or upload the .zip ﬁle ﬁrst to
an Amazon S3 bucket in the same AWS region where you want to create the Lambda function, and then
specify the bucket name and object key name when you create the Lambda function using the console or
the AWS CLI.
For Lambda functions written in Go, download the Lambda library for Go by navigating to the Go
runtime directory and enter the following command: go get github.com/aws/aws-lambda-go/
lambda
Then use following command to build, package and deploy a Go Lambda function via the CLI. Note that
your function-name must match the name of your Lambda handler name.
GOOS=linux go build lambda_handler.go
zip handler.zip ./lambda_handler

304

AWS Lambda Developer Guide
Creating a Deployment Package on Windows
# --handler is the path to the executable inside the .zip
aws lambda create-function \
--region region \
--function-name lambda-handler \
--memory 128 \
--role arn:aws:iam::account-id:role/execution_role \
--runtime go1.x \
--zip-file fileb://path-to-your-zip-file/handler.zip \
--handler lambda-handler

Note

If you are using a non-Linux environment, such as Windows or macOS, ensure that your handler
function is compatible with the Lambda Execution Context by setting the GOOS (Go Operating
System) environment variable to 'linux' when compiling your handler function code.

Creating a Deployment Package on Windows
To create a .zip that will work on AWS Lambda using Windows, we recommend installing the buildlambda-zip tool.

Note

If you have not already done so, you will need to install git and then add the git executable to
your Windows %PATH% environment variable.
To download the tool, run the following command:
go.exe get -u github.com/aws/aws-lambda-go/cmd/build-lambda-zip

Use the tool from your GOPATH. If you have a default installation of Go, the tool will typically be in
%USERPROFILE%\Go\bin. Otherwise, navigate to where you installed the Go runtime and do the
following:
In cmd.exe, run the following:
set GOOS=linux
go build -o main main.go
%USERPROFILE%\Go\bin\build-lambda-zip.exe -o main.zip main

In Powershell, run the following:
$env:GOOS = "linux"
go build -o main main.go
~\Go\Bin\build-lambda-zip.exe -o main.zip main

AWS Lambda Function Handler in Go
A Lambda function written in Go is authored as a Go executable. In your Lambda function code, you
need to include the github.com/aws/aws-lambda-go/lambda package, which implements the Lambda
programming model for Go. In addition, you need to implement handler function code and a main()
function.
package main
import (

"fmt"

305

AWS Lambda Developer Guide
Handler
"context"
"github.com/aws/aws-lambda-go/lambda"

)

type MyEvent struct {
Name string `json:"name"`
}
func HandleRequest(ctx context.Context, name MyEvent) (string, error) {
return fmt.Sprintf("Hello %s!", name.Name ), nil
}
func main() {
lambda.Start(HandleRequest)
}

Note the following:
• package main: In Go, the package containing func main() must always be named main.
• import: Use this to include the libraries your Lambda function requires. In this instance, it includes:
• context: AWS Lambda Context Object in Go (p. 309).
• fmt: The Go Formatting object used to format the return value of your function.
• github.com/aws/aws-lambda-go/lambda: As mentioned previously, implements the Lambda
programming model for Go.
• func HandleRequest(ctx context.Context, name MyEvent) (string, error): This is your Lambda
handler signature and includes the code which will be executed. In addition, the parameters included
denote the following:
• ctx context.Context: Provides runtime information for your Lambda function invocation. ctx is
the variable you declare to leverage the information available via AWS Lambda Context Object in
Go (p. 309).
• name MyEvent: An input type with a variable name of name whose value will be returned in the
return statement.
• string, error: Returns standard error information. For more information on custom error handling,
see AWS Lambda Function Errors in Go (p. 312).
• return fmt.Sprintf("Hello %s!", name), nil: Simply returns a formatted "Hello" greeting with the
name you supplied in the handler signature. nil indicates there were no errors and the function
executed successfully.
• func main(): The entry point that executes your Lambda function code. This is required.
By adding lambda.Start(HandleRequest) between func main(){} code brackets, your Lambda
function will be executed.

Note

Per Go language standards, the opening bracket, { must be placed directly at end the of the
main function signature.

Lambda Function Handler Using Structured Types
In the example above, the input type was a simple string. But you can also pass in structured events to
your function handler:
package main
import (

"fmt"
"github.com/aws/aws-lambda-go/lambda"

306

AWS Lambda Developer Guide
Handler
)

``
type MyEvent struct {
Name string `json:"What is your name?"`
Age int
`json:"How old are you?"`
}
type MyResponse struct {
Message string `json:"Answer:"`
}
func HandleLambdaEvent(event MyEvent) (MyResponse, error) {
return MyResponse{Message: fmt.Sprintf("%s is %d years old!", event.Name,
event.Age)}, nil
}
func main() {
lambda.Start(HandleLambdaEvent)
}

Your request would then look like this:

# request
{
"What is your name?": "Jim",
"How old are you?": 33
}

And the response would look like this:

# response
{
"Answer": "Jim is 33 years old!"
}

For more information on handling events from AWS event sources, see aws-lambda-go/events.

Valid Handler Signatures
You have several options when building a Lambda function handler in Go, but you must adhere to the
following rules:
• The handler must be a function.
• The handler may take between 0 and 2 arguments. If there are two arguments, the ﬁrst argument
must implement context.Context.
• The handler may return between 0 and 2 arguments. If there is a single return value, it must
implement error. If there are two return values, the second value must implement error. For
more information on implementing error-handling information, see AWS Lambda Function Errors in
Go (p. 312).
The following lists valid handler signatures. TIn and TOut represent types compatible with the
encoding/json standard library. For more information, see func Unmarshal to learn how these types are
deserialized.
•

func ()

307

AWS Lambda Developer Guide
Using Global State

•
•
•
•
•
•
•

func () error
func (TIn), error
func () (TOut, error)
func (context.Context) error
func (context.Context, TIn) error
func (context.Context) (TOut, error)
func (context.Context, TIn) (TOut, error)

Using Global State
You can declare and modify global variables that are independent of your Lambda function's handler
code. In addition, your handler may declare an init function that is executed when your handler is
loaded. This behaves the same in AWS Lambda as it does in standard Go programs. A single instance of
your Lambda function will never handle multiple events simultaneously. This means, for example, that
you may safely change global state, assured that those changes will require a new Execution Context
and will not introduce locking or unstable behavior from function invocations directed at the previous
Execution Context. For more information, see the following:
• AWS Lambda Execution Context (p. 93)
• Best Practices for Working with AWS Lambda Functions (p. 245)

package main
import (

)

"log"
"github.com/aws/aws-lambda-go/lambda"
"github.com/aws/aws-sdk-go/aws/session"
"github.com/aws/aws-sdk-go/service/s3"
"github.com/aws/aws-sdk-go/aws"

var invokeCount = 0
var myObjects []*s3.Object
func init() {
svc := s3.New(session.New())
input := &s3.ListObjectsV2Input{
Bucket: aws.String("examplebucket"),
}
result, _ := svc.ListObjectsV2(input)
myObjects = result.Contents
}
func LambdaHandler() (int, error) {
invokeCount = invokeCount + 1
log.Print(myObjects)
return invokeCount, nil
}
func main() {

308

AWS Lambda Developer Guide
Context
lambda.Start(LambdaHandler)

}

AWS Lambda Context Object in Go
When Lambda runs your function, it passes a context object to the handler (p. 305). This object
provides methods and properties with information about the invocation, function, and execution
environment.
The Lambda context library provides the following global variables, methods, and properties.

Global Variables
• FunctionName – The name of the Lambda function.
• FunctionVersion – The version (p. 30) of the function.
• MemoryLimitInMB – The amount of memory conﬁgured on the function.
• LogGroupName – The log group for the function.
• LogStreamName – The log stream for the function instance.

Context Methods
• Deadline – Returns the date that the execution times out, in Unix time milliseconds.

Context Properties
• InvokedFunctionArn – The Amazon Resource Name (ARN) used to invoke the function. Indicates if
the invoker speciﬁed a version number or alias.
• AwsRequestID – The identiﬁer of the invocation request.
• Identity – (mobile apps) Information about the Amazon Cognito identity that authorized the
request.
• ClientContext – (mobile apps) Client context provided to the Lambda invoker by the client
application.

Accessing Invoke Context Information
Lambda functions have access to metadata about their environment and the invocation request. This
can be accessed at Package context. Should your handler include context.Context as a parameter,
Lambda will insert information about your function into the context's Value property. Note that you
need to import the lambdacontext library to access the contents of the context.Context object.
package main
import (

)

"context"
"log"
"github.com/aws/aws-lambda-go/lambda"
"github.com/aws/aws-lambda-go/lambdacontext"

func CognitoHandler(ctx context.Context) {
lc, _ := lambdacontext.FromContext(ctx)
log.Print(lc.Identity.CognitoPoolID)

309

AWS Lambda Developer Guide
Logging
}
func main() {
lambda.Start(CognitoHandler)
}

In the example above, lc is the variable used to consume the information that the context object
captured and log.Print(lc.Identity.CognitoPoolID) prints that information, in this case, the
CognitoPoolID.

Monitoring Execution Time of a Function
The following example introduces how to use the context object to monitor how long it takes to execute
your Lambda function. This allows you to analyze performance expectations and adjust your function
code accordingly, if needed.
package main
import (

)

"context"
"log"
"time"
"github.com/aws/aws-lambda-go/lambda"

func LongRunningHandler(ctx context.Context) (string, error) {
deadline, _ := ctx.Deadline()
deadline = deadline.Add(-100 * time.Millisecond)
timeoutChannel := time.After(time.Until(deadline))
for {
select {
case <- timeoutChannel:
return "Finished before timing out.", nil
default:

}

}

}

log.Print("hello!")
time.Sleep(50 * time.Millisecond)

func main() {
lambda.Start(LongRunningHandler)
}

AWS Lambda Function Logging in Go
Your Lambda function can contain logging statements. AWS Lambda writes these logs to CloudWatch. If
you use the Lambda console to invoke your Lambda function, the console displays the same logs.
For example, consider the following example.
package main
import (

310

AWS Lambda Developer Guide
Finding Logs
"log"
"github.com/aws/aws-lambda-go/lambda"

)

func HandleRequest() {
log.Print("Hello from Lambda")
}
func main() {
lambda.Start(HandleRequest)
}

By importing the log module, Lambda will write additional logging information such as the time stamp.
You can also analyze the logs in CloudWatch. For more information, see Accessing Amazon CloudWatch
Logs for AWS Lambda (p. 211).
Instead of using the log module, you can use Print statements in your code as shown below:
package main
import (
)

"fmt"
"github.com/aws/aws-lambda-go/lambda"

func HandleRequest() {
fmt.Print("Hello from Lambda")
}
func main() {
lambda.Start(HandleRequest)
}

In this case only the text passed to the Print method is sent to CloudWatch. The log entries will not
have additional information that the log.Print function returns. In addition, any logger that writes to
stdout or stderror will seamlessly integrate with a Go function and those logs will automatically be
sent to CloudWatch logs.
The console uses the RequestResponse invocation type (synchronous invocation) when invoking the
function. And therefore it gets the return value ("Hello from Lambda!") back from AWS Lambda.

Finding Logs
You can ﬁnd the logs that your Lambda function writes, as follows:
• In the AWS Lambda console – The Log output section in the AWS Lambda console shows the logs.
• In the response header, when you invoke a Lambda function programmatically – If you invoke a
Lambda function programmatically, you can add the LogType parameter to retrieve the last 4 KB of
log data that is written to CloudWatch Logs. AWS Lambda returns this log information in the x-amzlog-results header in the response. For more information, see Invoke (p. 410).
If you use AWS CLI to invoke the function, you can specify the --log-type parameter with
value Tail to retrieve the same information.
• In CloudWatch Logs – To ﬁnd your logs in CloudWatch you need to know the log group name and
log stream name. You can use the context.logGroupName, and context.logStreamName global
variables in AWS Lambda Context Object in Go (p. 310) library to get this information. When you run
your Lambda function, the resulting logs in the console or CLI will show you the log group name and
log stream name.

311

AWS Lambda Developer Guide
Errors

AWS Lambda Function Errors in Go
You can create custom error handling to raise an exception directly from your Lambda function and
handle it directly.
The following code samples demonstrate how to do this. Note that custom errors in Go must import the
errors module.
package main
import (
)

"errors"
"github.com/aws/aws-lambda-go/lambda"

func OnlyErrors() error {
return errors.New("something went wrong!")
}
func main() {
lambda.Start(OnlyErrors)
}

Which will return:
{

"errorMessage": "something went wrong!"
}

Function Error Handling
You can create custom error handling to raise an exception directly from your Lambda function and
handle it directly (Retry or Catch) within an AWS Step Functions State Machine. For more information,
see Handling Error Conditions Using a State Machine.
Consider a CreateAccount state is a task that writes a customer's details to a database using a Lambda
function.
• If the task succeeds, an account is created and a welcome email is sent.
• If a user tries to create an account for a username that already exists, the Lambda function raises an
error, causing the state machine to suggest a diﬀerent username and to retry the account-creation
process.
The following code samples demonstrate how to do this.
package main
type CustomError struct {}
func (e *CustomError) Error() string {
return "bad stuff happened..."
}
func MyHandler() (string, error) {
return "", &CustomError{}
}

312

AWS Lambda Developer Guide
Handling Unexpected Errors

At runtime, AWS Step Functions catches the error, transitioning to the SuggestAccountName state as
speciﬁed in the Next transition.
Custom error handling makes it easier to create serverless applications. This feature integrates with
all the languages supported by the Lambda Programming Model (p. 18), allowing you to design your
application in the programming languages of your choice, mixing and matching as you go.
To learn more about creating your own serverless applications using AWS Step Functions and AWS
Lambda, see AWS Step Functions.

Handling Unexpected Errors
Lambda functions can fail for reasons beyond your control, such as network outages. These are
exceptional circumstances. In Go, panic addresses these issues. If your code panics, Lambda will attempt
to capture the error and serialize it into the standard error json format. Lambda will also attempt to
insert the value of the panic into the function's CloudWatch logs. After returning the response, Lambda
will re-create the function automatically. If you ﬁnd it necessary, you can include the panic function in
your code to customize the error response.
package main
import (
"errors"
"github.com/aws/aws-lambda-go/lambda"

)

func handler(string) (string, error) {
panic(errors.New("Something went wrong"))
}
func main() {
lambda.Start(handler)
}

Which would return the following stack in json:
{

"errorMessage": "Something went wrong",
"errorType": "errorString",
"stackTrace": [
{
"path": "github.com/aws/aws-lambda-go/lambda/function.go",
"line": 27,
"label": "(*Function).Invoke.function"
},

...
}

]

Instrumenting Go Code in AWS Lambda
You can use the X-Ray SDK for Go with your Lambda function. If your handler includes AWS Lambda
Context Object in Go (p. 309) as its ﬁrst argument, that object can be passed to the X-Ray SDK. Lambda
passes values through this context that the SDK can use to attach subsegments to the Lambda invoke
service segment. Subsegments created with the SDK will appear as a part of your Lambda traces.

313

AWS Lambda Developer Guide
Installing the X-Ray SDK for Go

Installing the X-Ray SDK for Go
Use the following command to install the X-Ray SDK for Go. (The SDK's non-testing dependencies will be
included).
go get -u github.com/aws/aws-xray-sdk-go/...

If you want to include the test dependencies, use the following command:
go get -u -t github.com/aws/aws-xray-sdk-go/...

You can also use Glide to manage dependencies.
glide install

Conﬁguring the X-Ray SDK for Go
The following code sample illustrates how to conﬁgure the X-Ray SDK for Go in your Lambda function:
import (
"github.com/aws/aws-xray-sdk-go/xray"
)
func myHandlerFunction(ctx context.Context, sample string) {
xray.Configure(xray.Config{
LogLevel:
"info",
// default
ServiceVersion:
"1.2.3",
})
... //remaining handler code
}

Create a subsegment
The following code illustrates how to start a subsegment:
// Start a subsegment
ctx, subSeg := xray.BeginSubsegment(ctx, "subsegment-name")
// ...
// Add metadata or annotation here if necessary
// ...
subSeg.Close(nil)

Capture
The following code illustrates how to trace and capture a critical code path:
func criticalSection(ctx context.Context) {
// This example traces a critical code path using a custom subsegment
xray.Capture(ctx, "MyService.criticalSection", func(ctx1 context.Context) error {
var err error
section.Lock()
result := someLockedResource.Go()
section.Unlock()

314

AWS Lambda Developer Guide
Tracing HTTP Requests

xray.AddMetadata(ctx1, "ResourceResult", result)

}

})

Tracing HTTP Requests
You can also use the xray.Client() method if you want to trace an HTTP client, as shown below:
func myFunction (ctx context.Context) ([]byte, error) {
resp, err := ctxhttp.Get(ctx, xray.Client(nil), "https://aws.amazon.com")
if err != nil {
return nil, err
}
return ioutil.ReadAll(resp.Body), nil
}

Using Environment Variables
To access AWS Lambda Environment Variables (p. 23) in Go, use the Getenv function.
The following explains how to do this. Note that the function imports the fmt package to format the
printed results and the os package, a platform-independent system interface that allows you to access
environment variables.
package main
import (
"fmt"
"os"
"github.com/aws/aws-lambda-go/lambda"
)
func main() {
fmt.Printf("%s is %s. years old\n", os.Getenv("NAME"), os.Getenv("AGE"))
}

Lambda conﬁgures the following environment variables by default: Environment Variables Available to
Lambda Functions (p. 92).

315

AWS Lambda Developer Guide
Deployment Package

Building Lambda Functions with C#
The following sections explain how common programming patterns and core concepts apply when
authoring Lambda function code in C#.

.NET Runtimes
Name

Identiﬁer

Languages

.NET Core 2.1

dotnetcore2.1

C#
PowerShell Core 6.0

.NET Core 2.0

dotnetcore2.0

C#

.NET Core 1.0

dotnetcore1.0

C#

Topics
• AWS Lambda Deployment Package in C# (p. 316)
• AWS Lambda Function Handler in C# (p. 325)
• AWS Lambda Context Object in C# (p. 329)
• AWS Lambda Function Logging in C# (p. 330)
• AWS Lambda Function Errors in C# (p. 331)
Additionally, note that AWS Lambda provides the following:
• Amazon.Lambda.Core – This library provides a static Lambda logger, serialization interfaces and a
context object. The Context object (AWS Lambda Context Object in C# (p. 329)) provides runtime
information about your Lambda function.
• Amazon.Lambda.Serialization.Json – This an implementation of the serialization interface in
Amazon.Lambda.Core.
• Amazon.Lambda.Logging.AspNetCore – This provides a library for logging from ASP.NET.
• Event objects (POCOs) for several AWS services, including:
• Amazon.Lambda.APIGatewayEvents
• Amazon.Lambda.CognitoEvents
• Amazon.Lambda.ConﬁgEvents
• Amazon.Lambda.DynamoDBEvents
• Amazon.Lambda.KinesisEvents
• Amazon.Lambda.S3Events
• Amazon.Lambda.SQSEvents
• Amazon.Lambda.SNSEvents
These packages are available at Nuget Packages.

AWS Lambda Deployment Package in C#
A .NET Core Lambda deployment package is a zip ﬁle of your function's compiled assembly along
with all of its assembly dependencies. The package also contains a proj.deps.json ﬁle. This signals

316

AWS Lambda Developer Guide
.NET Core CLI

to the .NET Core runtime all of your function's dependencies and a proj.runtimeconfig.json
ﬁle, which is used to conﬁgure the .NET Core runtime. The .NET CLI’s publish command can
create a folder with all of these ﬁles, but by default the proj.runtimeconfig.json will not
be included because a Lambda project is typically conﬁgured to be a class library. To force the
proj.runtimeconfig.json to be written as part of the publish process, pass in the command line
argument: /p:GenerateRuntimeConfigurationFiles=true to the publish command.

Note

Although it is possible to create the deployment package with the dotnet publish command,
we suggest you create the deployment package with either the AWS Toolkit for Visual
Studio (p. 324) or the .NET Core CLI (p. 317). These are tools optimized speciﬁcally for
Lambda to ensure the lambda-project.runtimeconfig.json ﬁle exists and optimizes the
package bundle, including the removal of any non-Linux-based dependencies.

.NET Core CLI
The .NET Core CLI oﬀers a cross-platform way for you to create .NET-based Lambda applications. This
section assumes you have installed the .NET Core CLI. If you haven't, do so here.
In the .NET CLI, you use the new command to create .NET projects from a command line. This is
particularly useful if you want to create a platform-independent project outside of Visual Studio. To view
a list of the available project types, open a command line and navigate to where you installed the .NET
Core runtime and enter the following:
dotnet new -all

You should see the following:
dotnet new -all
Usage: new [options]
Options:
-h, --help
Displays help for this command.
-l, --list
Lists templates containing the specified name. If no name is
specified, lists all templates.
-n, --name
The name for the output being created. If no name is specified, the
name of the current directory is used.
-o, --output
Location to place the generated output.
-i, --install
Installs a source or a template pack.
-u, --uninstall
Uninstalls a source or a template pack.
--nuget-source
Specifies a NuGet source to use during install.
--type
Filters templates based on available types. Predefined values are
"project", "item" or "other".
--force
Forces content to be generated even if it would change existing
files.
-lang, --language
Filters templates based on language and specifies the language of the
template to create.
Templates

Short Name

Language

Tags

------------------------------------------------------------------------------------------------------Console Application
console
[C#], F#, VB
Common/Console
Class library
classlib
[C#], F#, VB
Common/Library
Unit Test Project
mstest
[C#], F#, VB
Test/MSTest
xUnit Test Project
xunit
[C#], F#, VB
Test/xUnit
Razor Page
page
[C#]
Web/
ASP.NET

317

AWS Lambda Developer Guide
.NET Core CLI
MVC ViewImports
ASP.NET
MVC ViewStart
ASP.NET
ASP.NET Core Empty
Empty
ASP.NET Core Web App (Model-View-Controller)
MVC
ASP.NET Core Web App
MVC/Razor Pages
ASP.NET Core with Angular
MVC/SPA
ASP.NET Core with React.js
MVC/SPA
ASP.NET Core with React.js and Redux
MVC/SPA
Razor Class Library
Razor/Library/Razor Class Library
ASP.NET Core Web API
WebAPI
global.json file
Config
NuGet Config
Config
Web Config
Config
Solution File
Solution

viewimports

[C#]

Web/

viewstart

[C#]

Web/

web

[C#], F#

Web/

mvc

[C#], F#

Web/

razor

[C#]

Web/

angular

[C#]

Web/

react

[C#]

Web/

reactredux

[C#]

Web/

razorclasslib

[C#]

Web/

webapi

[C#], F#

Web/

globaljson
nugetconfig
webconfig
sln

Examples:
dotnet new mvc --auth Individual
dotnet new viewstart
dotnet new --help

So, for example, if you wanted to create a console project, you would do the following:
1.
2.

Make a directory where your project will be created using the following command: mkdir example
Navigate to that directory using the following command: cd example

3.

Enter the following command: dotnet new console -o myproject
This will create the following ﬁles in your example directory:
• Program.cs, which is where you write your Lambda function code.
• MyProject.csproj, an XML ﬁle that lists the ﬁles and dependencies that comprise your.NET
application.

AWS Lambda oﬀers additional templates via the Amazon.Lambda.Templates nuget package. To install
this package, run the following command:
dotnet new -i Amazon.Lambda.Templates

Once the install is complete, the Lambda templates show up as part of dotnet new. To verify this, again
run the following command:
dotnet new -all

You should now see the following:
dotnet new -all
Usage: new [options]

318

AWS Lambda Developer Guide
.NET Core CLI

Options:
-h, --help
Displays help for this command.
-l, --list
Lists templates containing the specified name. If no name is
specified, lists all templates.
-n, --name
The name for the output being created. If no name is specified, the
name of the current directory is used.
-o, --output
Location to place the generated output.
-i, --install
Installs a source or a template pack.
-u, --uninstall
Uninstalls a source or a template pack.
--nuget-source
Specifies a NuGet source to use during install.
--type
Filters templates based on available types. Predefined values are
"project", "item" or "other".
--force
Forces content to be generated even if it would change existing
files.
-lang, --language
Filters templates based on language and specifies the language of the
template to create.

Templates
Short Name
Language
Tags
------------------------------------------------------------------------------------------------------Order Flowers Chatbot Tutorial
lambda.OrderFlowersChatbot
[C#]
AWS/Lambda/Function
Lambda Detect Image Labels
lambda.DetectImageLabels
[C#], F#
AWS/Lambda/Function
Lambda Empty Function
lambda.EmptyFunction
[C#], F#
AWS/Lambda/Function
Lex Book Trip Sample
lambda.LexBookTripSample
[C#]
AWS/Lambda/Function
Lambda Simple DynamoDB Function
lambda.DynamoDB
[C#], F#
AWS/Lambda/Function
Lambda Simple Kinesis Firehose Function
lambda.KinesisFirehose
[C#]
AWS/Lambda/Function
Lambda Simple Kinesis Function
lambda.Kinesis
[C#], F#
AWS/Lambda/Function
Lambda Simple S3 Function
lambda.S3
[C#], F#
AWS/Lambda/Function
Lambda ASP.NET Core Web API
serverless.AspNetCoreWebAPI
[C#], F#
AWS/Lambda/Serverless
Lambda ASP.NET Core Web Application with Razor Pages
serverless.AspNetCoreWebApp
[C#]
AWS/Lambda/Serverless
Serverless Detect Image Labels
serverless.DetectImageLabels
[C#], F#
AWS/Lambda/Serverless
Lambda DynamoDB Blog API
serverless.DynamoDBBlogAPI
[C#]
AWS/Lambda/Serverless
Lambda Empty Serverless
serverless.EmptyServerless
[C#], F#
AWS/Lambda/Serverless
Lambda Giraffe Web App
serverless.Giraffe
F#
AWS/Lambda/Serverless
Serverless Simple S3 Function
serverless.S3
[C#], F#
AWS/Lambda/Serverless
Step Functions Hello World
serverless.StepFunctionsHelloWorld
[C#], F#
AWS/Lambda/Serverless
Console Application
console
[C#], F#, VB
Common/Console
Class library
classlib
[C#], F#, VB
Common/Library
Unit Test Project
mstest
[C#], F#, VB
Test/MSTest
xUnit Test Project
xunit
[C#], F#, VB
Test/xUnit
Razor Page
page
[C#]
Web/ASP.NET
MVC ViewImports
viewimports
[C#]
Web/ASP.NET

319

AWS Lambda Developer Guide
.NET Core CLI
MVC ViewStart
viewstart
[C#]
Web/ASP.NET
ASP.NET Core Empty
web
[C#], F#
Web/Empty
ASP.NET Core Web App (Model-View-Controller)
mvc
[C#], F#
Web/MVC
ASP.NET Core Web App
razor
[C#]
Web/MVC/Razor Pages
ASP.NET Core with Angular
angular
[C#]
Web/MVC/SPA
ASP.NET Core with React.js
react
[C#]
Web/MVC/SPA
ASP.NET Core with React.js and Redux
reactredux
[C#]
Web/MVC/SPA
Razor Class Library
razorclasslib
[C#]
Web/Razor/Library/Razor Class Library
ASP.NET Core Web API
webapi
[C#], F#
Web/WebAPI
global.json file
globaljson
Config
NuGet Config
nugetconfig
Config
Web Config
webconfig
Config
Solution File
sln
Solution
Examples:
dotnet new mvc --auth Individual
dotnet new viewimports --namespace
dotnet new --help

To examine details about a particular template, use the following command:
dotnet new lambda.EmptyFunction --help

Note the following:
-p|--profile The AWS credentials profile set in aws-lambda-tools-defaults.json and used
as the default profile when interacting with AWS.
string - Optional
-r|--region
The AWS region set in aws-lambda-tools-defaults.json and used as the default
region when interacting with AWS.
string - Optional

These are optional values you can set when you create your Lambda function and will then be
automatically written to the aws-lambda-tools-defaults.json ﬁle, which is built as part of the
function-creation process. The following explains what they mean:
• --proﬁle: Your execution role.
To create an IAM role (execution role):
1.
2.

Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
Follow the steps in IAM Roles in the IAM User Guide to create an IAM role (execution role). As you
follow the steps to create a role, note the following:
• In Select Role Type, choose AWS Service Roles, and then choose AWS Lambda.
• In Attach Policy, choose the policy that best ﬁts your Lambda function's requirements.
If it's not interacting with any other AWS services, you would would choose

320

AWS Lambda Developer Guide
.NET Core CLI

AWSLambdaBasicExecutionRole. However, say your Lambda function is interacting with
Kinesis, then you would choose the AWSLambdaKinesisExecutionRole.
• --region: The Amazon Region in which your function will reside.
For example, to create a Lambda function, run the following command, substituting the values of the -region parameter with the region of your choice and --profile with your IAM proﬁle:

Note

For more information on Lambda function requirements, see CreateFunction (p. 368)
dotnet new lambda.EmptyFunction --name MyFunction --profile default --region region

This should create a directory structure similar to the following:
myfunction
/src/myfunction
/test/myfunction

Under the src/myfunction directory, examine the following ﬁles:
• aws-lambda-tools-defaults.json: This is where you specify the command line options when deploying
your Lambda function. For example:
"profile":"iam profile"",
"region" : "region",
"configuration" : "Release",
"framework" : "netcoreapp2.1",
"function-runtime":"dotnetcore2.1",
"function-memory-size" : 256,
"function-timeout" : 30,
"function-handler" : "MyFunction::MyFunction.Function::FunctionHandler"

• Function.cs: Your Lambda handler function code. It's a C# template that includes the default
Amazon.Lambda.Core library and a default LambdaSerializer attribute. For more information on
serialization requirements and options, see Serializing Lambda Functions (p. 323). It also includes a
sample function that you can edit to apply your Lambda function code.
using
using
using
using

System;
System.Collections.Generic;
System.Linq;
System.Threading.Tasks;

using Amazon.Lambda.Core;
// Assembly attribute to enable the Lambda function's JSON input to be converted into
a .NET class.
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.Json.JsonSerializer))]
namespace MyFunction
{
public class Function
{

}

}

public string FunctionHandler1(string input, ILambdaContext context)
{
return input?.ToUpper();
}

321

AWS Lambda Developer Guide
.NET Core CLI

• MyFunction.csproj: An MSBuild ﬁle that lists the ﬁles and assemblies that comprise your application.


netcoreapp2.1







• Readme: Use this ﬁle to document your Lambda function.
Under the myfunction/test directory, examine the following files:
• myFunction.Tests.csproj: As noted above, this is an MSBuild ﬁle that lists the ﬁles and assemblies that
comprise your test project. Note also that it includes the Amazon.Lambda.Core library, allowing you
to seamlesssly integrate any Lambda templates required to test your function.

...

...

• FunctionTest.cs: The same C# code template ﬁle that it is included in the src directory. Edit this ﬁle
to mirror your function's production code and test it before uploading your Lambda function to a
production environment.
using
using
using
using

System;
System.Collections.Generic;
System.Linq;
System.Threading.Tasks;

using Xunit;
using Amazon.Lambda.Core;
using Amazon.Lambda.TestUtilities;
using MyFunction;
namespace MyFunction.Tests
{
public class FunctionTest
{
[Fact]
public void TestToUpperFunction()
{
// Invoke the lambda function and confirm the string was upper cased.
var function = new Function();
var context = new TestLambdaContext();
var upperCase = function.FunctionHandler("hello world", context);

}

}

}

Assert.Equal("HELLO WORLD", upperCase);

322

AWS Lambda Developer Guide
.NET Core CLI

Once your function has passed its tests, you can build and deploy using the Amazon.Lambda.Tools .NET
Core Global Tool. To install the .NET Core Global Tool run the following command.
dotnet tool install -g Amazon.Lambda.Tools

If you already have the tool installed you can make sure you are using the latest version with the
following command.
dotnet tool update -g Amazon.Lambda.Tools

For more information about the Amazon.Lambda.Tools .NET Core Global see its GitHub repository.
With the Amazon.Lambda.Tools installed you can deploy your function with the following command:
dotnet lambda deploy-function MyFunction –-function-role role

After deployment, you can re-test it in a production environment with the following command and pass
in a diﬀerent value to your Lambda function handler:
dotnet lambda invoke-function MyFunction --payload "Just Checking If Everything is OK"

Presuming everything was successful, you should see the following:
dotnet lambda invoke-function MyFunction --payload "Just Checking If Everything is OK"
Payload:
"JUST CHECKING IF EVERYTHING IS OK"
Log Tail:
START RequestId: id Version: $LATEST
END RequestId: id
REPORT RequestId: id Duration: 0.99 ms
256 MB
Max Memory Used: 12 MB

Billed Duration: 100 ms

Memory Size:

Serializing Lambda Functions
For any Lambda functions that use input or output types other than a Stream object, you will need to
add a serialization library to your application. You can do this in the following ways:
• Use Json.NET. Lambda will provide an implementation for JSON serializer using JSON.NET as a NuGet
package.
• Create your own serialization library by implementing the ILambdaSerializer interface, which is
available as part of the Amazon.Lambda.Core library. The interface deﬁnes two methods:
• T Deserialize(Stream requestStream);
You implement this method to deserialize the request payload from the Invoke API into the object
that is passed to the Lambda function handler.
• T Serialize(T response, Stream responseStream);.
You implement this method to serialize the result returned from the Lambda function handler into
the response payload that is returned by the Invoke API.
You use whichever serializer you wish by adding it as a dependency to your MyProject.csproj ﬁle.
...

323

AWS Lambda Developer Guide
AWS Toolkit for Visual Studio





You then add it to your AssemblyInfo.cs ﬁle. For example, if you are using the default Json.NET serializer,
this is what you would add:
[assembly:LambdaSerializer(typeof(Amazon.Lambda.Serialization.Json.JsonSerializer))]

Note

You can deﬁne a custom serialization attribute at the method level, which will override the
default serializer speciﬁed at the assembly level. For more information, see Handling Standard
Data Types (p. 326).

AWS Toolkit for Visual Studio
You can build .NET-based Lambda applications using the Lambda plugin to the AWS Toolkit for Visual
Studio. The plugin is available as part of a Nuget package.

Step 1: Create and Build a Project
1.

2.

Launch Microsoft Visual Studio and choose New project.
a.

From the File menu, choose New, and then choose Project.

b.

In the New Project window, choose AWS Lambda Project (.NET Core) and then choose OK.

c.

In the Select Blueprint window, you will be presented with the option of selecting from a list of
sample applications that will provide you with sample code to get started with creating a .NETbased Lambda application.

d.

To create a Lambda application from scratch, choose Blank Function and then choose Finish.

Examine the aws-lambda-tools-defaults.json ﬁle, which is created as part of your project.
You can set the options in this ﬁle, which is read by the Lambda tooling by default. The project
templates created in Visual Studio set many of these ﬁelds with default values. Note the following
ﬁelds:
• proﬁle: The IAM role required for your Lambda function's execution. If you have not yet created an
execution role, do the following:
1.

Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.

2.

Follow the steps in Creating a Role to Delegate Permissions to an AWS Service in the IAM User
Guide to create an IAM role (execution role). As you follow the steps to create a role, note the
following:
• In Role Name, use a name that is unique within your AWS account.
• In Select Role Type, choose AWS Service Roles, and then choose a service role that grants
that service permissions to assume the role.
• In Attach Policy, choose a permissions policy that is suitable to execute your Lambda
function.

• function-handler: This is where the function handler is speciﬁed, which is why you don't
have to set it in the wizard. However, whenever you rename the Assembly, Namespace, Class
or Function in your function code, you will need to update the corresponding ﬁelds in the awslambda-tools-defaults.json file.
{

324

AWS Lambda Developer Guide
Handler

}

"profile":"iam-execution-profile"",
"region" : "region",
"configuration" : "Release",
"framework" : "netcoreapp2.1",
"function-runtime":"dotnetcore2.1",
"function-memory-size" : 256,
"function-timeout" : 30,
"function-handler" : "Assembly::Namespace.Class::Function"

3.

Open the Function.cs ﬁle. You will be provided with a template to implement your Lambda function
handler code.

4.

Once you have written the code that represents your Lambda function, you can upload it by rightclicking the Project node in your application and then choosing Publish to AWS Lambda.

5.

In the Upload Lambda Function window, type a name for the function or select a previously
published function to republish. Then choose Next

6.

In the Advanced Function Details window, do the following:
• Specify the Role Name:, the IAM role mentioned previously.
• (Optional) In Environment:: specify any environment variables you wish to use. For more
information, see AWS Lambda Environment Variables (p. 23).
• (Optional) Specify the Memory (MB): or Timeout (Secs): conﬁgurations.
• (Optional) Specify any VPC: conﬁgurations if your Lambda function needs to access resources
running inside a VPC. For more information, see Conﬁguring a Lambda Function to Access
Resources in an Amazon VPC (p. 52).
• Choose Next and then choose Upload to deploy your application.

For more information, see Deploying an AWS Lambda Project with the .NET Core CLI.

AWS Lambda Function Handler in C#
When you create a Lambda function, you specify a handler that AWS Lambda can invoke when the
service executes the function on your behalf.
You deﬁne a Lambda function handler as an instance or static method in a class. If you want access to
the Lambda context object, it is available by deﬁning a method parameter of type ILambdaContext, an
325

AWS Lambda Developer Guide
Handling Streams

interface you can use to access information about the current execution, such as the name of the current
function, the memory limit, execution time remaining, and logging.
returnType handler-name(inputType input, ILambdaContext context) {
...
}

In the syntax, note the following:
• inputType – The ﬁrst handler parameter is the input to the handler, which can be event data
(published by an event source) or custom input that you provide such as a string or any custom data
object.
• returnType – If you plan to invoke the Lambda function synchronously (using the
RequestResponse invocation type), you can return the output of your function using any of the
supported data types. For example, if you use a Lambda function as a mobile application backend, you
are invoking it synchronously. Your output data type will be serialized into JSON.
If you plan to invoke the Lambda function asynchronously (using the Event invocation type), the
returnType should be void. For example, if you use AWS Lambda with event sources such as
Amazon S3 or Amazon SNS, these event sources invoke the Lambda function using the Event
invocation type.

Handling Streams
Only the System.IO.Stream type is supported as an input parameter by default.
For example, consider the following C# example code.
using System.IO;
namespace Example
{
public class Hello
{
public Stream MyHandler(Stream stream)
{
//function logic
}
}

In the example C# code, the ﬁrst handler parameter is the input to the handler (MyHandler), which can
be event data (published by an event source such as Amazon S3) or custom input you provide such as a
Stream (as in this example) or any custom data object. The output is of type Stream.

Handling Standard Data Types
All other types, as listed below, require you to specify a serializer.
• Primitive .NET types (such as string or int).
• Collections and maps - IList, IEnumerable, IList, Array, IDictionary, IDictionary
• POCO types (Plain old CLR objects)
• Predeﬁned AWS event types
• For asynchronous invocations the return-type will be ignored by Lambda. The return type may be set
to void in such cases.

326

AWS Lambda Developer Guide
Handler Signatures

• If you are using .NET asynchronous programming, the return type can be Task and Task types and
use async and await keywords. For more information, see Using Async in C# Functions with AWS
Lambda (p. 328).
Unless your function input and output parameters are of type System.IO.Stream, you will need to
serialize them. AWS Lambda provides a default serializer that can be applied at the assembly or method
level of your application, or you can deﬁne your own by implementing the ILambdaSerializer
interface provided by the Amazon.Lambda.Core library. For more information, see AWS Lambda
Deployment Package in C# (p. 316).
To add the default serializer attribute to a method, ﬁrst add a dependency on
Amazon.Lambda.Serialization.Json in your project.json ﬁle.
{

}

"version": "1.0.0-*",
"dependencies":{
"Microsoft.NETCore.App": {
"type": "platform",
"version": "1.0.1"
},
"Amazon.Lambda.Serialization.Json": "1.3.0"
},
"frameworks": {
"netcoreapp1.0": {
"imports": "dnxcore50"
}
}

The example below illustrates the ﬂexibility you can leverage by specifying the default Json.NET
serializer on one method and another of your choosing on a diﬀerent method:
public class ProductService{
[LambdaSerializer(typeof(Amazon.Lambda.Serialization.Json.JsonSerializer))]
public Product DescribeProduct(DescribeProductRequest request)
{
return catalogService.DescribeProduct(request.Id);
}

}

[LambdaSerializer(typeof(MyJsonSerializer))]
public Customer DescribeCustomer(DescribeCustomerRequest request)
{
return customerService.DescribeCustomer(request.Id);
}

Handler Signatures
When creating Lambda functions, you have to provide a handler string that tells AWS Lambda where to
look for the code to invoke. In C#, the format is:
ASSEMBLY::TYPE::METHOD where:
• ASSEMBLY is the name of the .NET assembly ﬁle for your application. When using the .NET Core CLI to
build your application, if you haven't set the assembly name using the buildOptions.outputName
setting in project.json, the ASSEMBLY name will be the name of the folder that contains your
project.json ﬁle. For more information, see .NET Core CLI (p. 317). In this case, let's assume the folder
name is HelloWorldApp.

327

AWS Lambda Developer Guide
Lambda Function Handler Restrictions

• TYPE is the full name of the handler type, which consists of the Namespace and the ClassName. In
this case Example.Hello.
• METHOD is name of the function handler, in this case MyHandler.
Ultimately, the signature will be of this format: Assembly::Namespace.ClassName::MethodName
Again, consider the following example:
using System.IO;
namespace Example
{
public class Hello
{
public Stream MyHandler(Stream stream)
{
//function logic
}
}

The handler string would be: HelloWorldApp::Example.Hello::MyHandler

Important

If the method speciﬁed in your handler string is overloaded, you must provide the exact
signature of the method Lambda should invoke. AWS Lambda will reject an otherwise valid
signature if the resolution would require selecting among multiple (overloaded) signatures.

Lambda Function Handler Restrictions
Note that there are some restrictions on the handler signature.
• It may not be unsafe and use pointer types in the handler signature, though unsafe context can
be used inside the handler method and its dependencies. For more information, see unsafe (C#
Reference).
• It may not pass a variable number of parameters using the params keyword, or use ArgIterator as
an input or return parameter which is used to support variable number of parameters.
• The handler may not be a generic method (e.g. IList Sort(IList input)).
• Async handlers with signature async void are not supported.

Using Async in C# Functions with AWS Lambda
If you know your Lambda function will require a long-running process, such as uploading large ﬁles to
Amazon S3 or reading a large stream of records from DynamoDB, you can take advantage of the async/
await pattern. When you use this signature, Lambda executes the function synchronously and waits for
the function to return a response or for execution to time out (p. 22).
public async Task ProcessS3ImageResizeAsync(SimpleS3Event input)
{
var response = await client.DoAsyncWork(input);
return response;
}

If you use this pattern, there are some considerations you must take into account:
• AWS Lambda does not support async void methods.

328

AWS Lambda Developer Guide
Context

• If you create an async Lambda function without implementing the await operator, .NET will issue
a compiler warning and you will observe unexpected behavior. For example, some async actions will
execute while others won't. Or some async actions won't complete before the function execution is
complete.
public async Task ProcessS3ImageResizeAsync(SimpleS3Event event) // Compiler warning
{
client.DoAsyncWork(input);
}

• Your Lambda function can include multiple async calls, which can be invoked in parallel. You can
use the Task.WhenAll and Task.WhenAny methods to work with multiple tasks. To use the
Task.WhenAll method, you pass a list of the operations as an array to the method. Note that in the
example below, if you neglect to include any operation to the array, that call may return before its
operation completes.
public async Task DoesNotWaitForAllTasks1()
{
// In Lambda, Console.WriteLine goes to CloudWatch Logs.
var task1 = Task.Run(() => Console.WriteLine("Test1"));
var task2 = Task.Run(() => Console.WriteLine("Test2"));
var task3 = Task.Run(() => Console.WriteLine("Test3"));

}

// Lambda may return before printing "Test2" since we never wait on task2.
await Task.WhenAll(task1, task3);

To use the Task.WhenAny method, you again pass a list of operations as an array to the method. The
call returns as soon as the ﬁrst operation completes, even if the others are still running.
public async Task DoesNotWaitForAllTasks2()
{
// In Lambda, Console.WriteLine goes to CloudWatch Logs.
var task1 = Task.Run(() => Console.WriteLine("Test1"));
var task2 = Task.Run(() => Console.WriteLine("Test2"));
var task3 = Task.Run(() => Console.WriteLine("Test3"));
// Lambda may return before printing all tests since we're only waiting for one to
finish.
await Task.WhenAny(task1, task2, task3);

}

AWS Lambda Context Object in C#
When Lambda runs your function, it passes a context object to the handler (p. 325). This object
provides properties with information about the invocation, function, and execution environment.

Context Properties
• FunctionName – The name of the Lambda function.
• FunctionVersion – The version (p. 30) of the function.
• InvokedFunctionArn – The Amazon Resource Name (ARN) used to invoke the function. Indicates if
the invoker speciﬁed a version number or alias.
• MemoryLimitInMB – The amount of memory conﬁgured on the function.
• AwsRequestId – The identiﬁer of the invocation request.
329

AWS Lambda Developer Guide
Logging

• LogGroupName – The log group for the function.
• LogStreamName – The log stream for the function instance.
• RemainingTime (TimeSpan) – The number of milliseconds left before the execution times out.
• Identity – (mobile apps) Information about the Amazon Cognito identity that authorized the
request.
• ClientContext – (mobile apps) Client context provided to the Lambda invoker by the client
application.
• Logger The logger object (p. 330) for the function.
The following C# code snippet shows a simple handler function that prints some of the context
information.
public async Task Handler(ILambdaContext context)
{
Console.WriteLine("Function name: " + context.FunctionName);
Console.WriteLine("RemainingTime: " + context.RemainingTime);
await Task.Delay(TimeSpan.FromSeconds(0.42));
Console.WriteLine("RemainingTime after sleep: " + context.RemainingTime);
}

AWS Lambda Function Logging in C#
Your Lambda function can contain logging statements and, in turn, AWS Lambda writes these logs to
CloudWatch Logs.
In the C# programming model, there are three ways to log data in your function:
• Use the static Write or WriteLine methods provided by the C# Console class. Anything written
to standard out or standard error - using Console.Write or a similar method - will be logged in
CloudWatch Logs.
public class ProductService
{
public async Task DescribeProduct(DescribeProductRequest request)
{
Console.WriteLine("DescribeProduct invoked with Id " + request.Id);
return await catalogService.DescribeProduct(request.Id);
}
}

• Use the Log method on the Amazon.Lambda.Core.LambdaLogger class. This is a static class that
can be used anywhere in your application. To use this, you must include the Amazon.Lambda.Core
library.
using Amazon.Lambda.Core;
public class ProductService
{
public async Task DescribeProduct(DescribeProductRequest request)
{
LambdaLogger.Log("DescribeProduct invoked with Id " + request.Id);
return await catalogService.DescribeProduct(request.Id);
}
}

330

AWS Lambda Developer Guide
How to Find Logs

Each call to LambdaLogger.Log results in a CloudWatch Logs event, provided the event size is within
the allowed limits. For information about CloudWatch Logs limits, see CloudWatch Logs Limits in the
Amazon CloudWatch User Guide.
• Use the logger in ILambdaContext. The ILambdaContext object (if speciﬁed) in your method
contains a Logger property that represents a LambdaLogger. The following is an example of using
this method:
public class ProductService
{
public async Task DescribeProduct(DescribeProductRequest request,
ILambdaContext context)
{
context.Logger.Log("DescribeProduct invoked with Id " + request.Id);
return await catalogService.DescribeProduct(request.Id);
}
}

How to Find Logs
You can ﬁnd the logs that your Lambda function writes, as follows:
• Find logs in CloudWatch Logs. The ILambdaContext object provides the LogStreamName and the
LogGroupName properties. Using these properties, you can ﬁnd the speciﬁc log stream where logs are
written.
• If you invoke a Lambda function via the console, the invocation type is always RequestResponse
(that is, synchronous execution) and the console displays the logs that the Lambda function writes
using the LambdaLogger object. AWS Lambda also returns logs from Console.Write and
Console.WriteLine methods.
• If you invoke a Lambda function programmatically, you can add the LogType parameter to
retrieve the last 4 KB of log data that is written to CloudWatch Logs. For more information, see
Invoke (p. 410). AWS Lambda returns this log information in the x-amz-log-results header in the
response. If you use the AWS Command Line Interface to invoke the function, you can specify the -log-type parameter with value Tail.

AWS Lambda Function Errors in C#
When an exception occurs in your Lambda function, Lambda will report the exception information back
to you. Exceptions can occur in two diﬀerent places:
• Initialization (Lambda loading your code, validating the handler string, and creating an instance of
your class if it is non-static).
• The Lambda function invocation.
The serialized exception information is returned as the payload as a modeled JSON object and outputted
to CloudWatch logs.
In the initialization phase, exceptions can be thrown for invalid handler strings, a rule-breaking type or
method (see Lambda Function Handler Restrictions (p. 328)), or any other validation method (such as
forgetting the serializer attribute and having a POCO as your input or output type). These exceptions are
of type LambdaException. For example:
{

331

AWS Lambda Developer Guide
Errors

}

"errorType": "LambdaException",
"errorMessage": "Invalid lambda function handler: 'http://this.is.not.a.valid.handler/'.
The valid format is 'ASSEMBLY::TYPE::METHOD'."

If your constructor throws an exception, the error type is also of type LambdaException, but the
exception thrown during construction is provided in the cause property, which is itself a modeled
exception object:
{

"errorType": "LambdaException",
"errorMessage": "An exception was thrown when the constructor for type
'LambdaExceptionTestFunction.ThrowExceptionInConstructor'
was invoked. Check inner exception for more details.",
"cause":
{
"errorType": "TargetInvocationException",
"errorMessage": "Exception has been thrown by the target of an invocation.",
"stackTrace": [
"at System.RuntimeTypeHandle.CreateInstance(RuntimeType type, Boolean publicOnly,
Boolean noCheck, Boolean&canBeCached,
RuntimeMethodHandleInternal&ctor, Boolean& bNeedSecurityCheck)",
"at System.RuntimeType.CreateInstanceSlow(Boolean publicOnly, Boolean skipCheckThis,
Boolean fillCache, StackCrawlMark& stackMark)",
"at System.Activator.CreateInstance(Type type, Boolean nonPublic)",
"at System.Activator.CreateInstance(Type type)"
],
"cause":
{
"errorType": "ArithmeticException",
"errorMessage": "Sorry, 2 + 2 = 5",
"stackTrace": [
"at LambdaExceptionTestFunction.ThrowExceptionInConstructor..ctor()"
]
}
}

}

As the example shows, the inner exceptions are always preserved (as the cause property), and can be
deeply nested.
Exceptions can also occur during invocation. In this case, the exception type is preserved and the
exception is returned directly as the payload and in the CloudWatch logs. For example:
{

"errorType": "AggregateException",
"errorMessage": "One or more errors occurred. (An unknown web exception occurred!)",
"stackTrace": [
"at System.Threading.Tasks.Task.ThrowIfExceptional(Boolean
includeTaskCanceledExceptions)",
"at System.Threading.Tasks.Task`1.GetResultCore(Boolean waitCompletionNotification)",
"at lambda_method(Closure , Stream , Stream , ContextInfo )"
],
"cause":
{
"errorType": "UnknownWebException",
"errorMessage": "An unknown web exception occurred!",
"stackTrace": [
"at LambdaDemo107.LambdaEntryPoint.d__1.MoveNext()",
"--- End of stack trace from previous location where exception was thrown ---",
"at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)",
"at
System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task
task)",
"at System.Runtime.CompilerServices.TaskAwaiter`1.GetResult()",
"at LambdaDemo107.LambdaEntryPoint.d__0.MoveNext()"

332

AWS Lambda Developer Guide
Errors
],
"cause":
{
"errorType": "WebException",
"errorMessage": "An error occurred while sending the request. SSL peer certificate or
SSH remote key was not OK",
"stackTrace": [
"at System.Net.HttpWebRequest.EndGetResponse(IAsyncResult asyncResult)",
"at System.Threading.Tasks.TaskFactory`1.FromAsyncCoreLogic(IAsyncResult iar,
Func`2 endFunction, Action`1 endAction, Task`1 promise, Boolean requiresSynchronization)",
"--- End of stack trace from previous location where exception was thrown ---",
"at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)",
"at
System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task
task)",
"at System.Runtime.CompilerServices.TaskAwaiter`1.GetResult()",
"at LambdaDemo107.LambdaEntryPoint.d__1.MoveNext()"
],
"cause":
{
"errorType": "HttpRequestException",
"errorMessage": "An error occurred while sending the request.",
"stackTrace": [
"at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)",
"at
System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task
task)",
"at System.Net.Http.HttpClient.d__58.MoveNext()",
"--- End of stack trace from previous location where exception was thrown ---",
"at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)",
"at
System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task
task)",
"at System.Net.HttpWebRequest.d__63.MoveNext()",
"--- End of stack trace from previous location where exception was thrown ---",
"at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)",
"at
System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task
task)",
"at System.Net.HttpWebRequest.EndGetResponse(IAsyncResult asyncResult)"
],
"cause":
{
"errorType": "CurlException",
"errorMessage": "SSL peer certificate or SSH remote key was not OK",
"stackTrace": [
"at System.Net.Http.CurlHandler.ThrowIfCURLEError(CURLcode error)",
"at
System.Net.Http.CurlHandler.MultiAgent.FinishRequest(StrongToWeakReference`1 easyWrapper,
CURLcode messageResult)"
]
}
}
}
}

}

The method in which error information is conveyed depends on the invocation type:
• RequestResponse invocation type (that is, synchronous execution): In this case, you get the error
message back.
For example, if you invoke a Lambda function using the Lambda console, the RequestResponse is
always the invocation type and the console displays the error information returned by AWS Lambda in
the Execution result section of the console.
• Event invocation type (that is, asynchronous execution): In this case AWS Lambda does not return
anything. Instead, it logs the error information in CloudWatch Logs and CloudWatch metrics.

333

AWS Lambda Developer Guide
Function Error Handling

Depending on the event source, AWS Lambda may retry the failed Lambda function. For more
information, see AWS Lambda Retry Behavior (p. 67).

Function Error Handling
You can create custom error handling to raise an exception directly from your Lambda function and
handle it directly (Retry or Catch) within an AWS Step Functions State Machine. For more information,
see Handling Error Conditions Using a State Machine.
Consider a CreateAccount state is a task that writes a customer's details to a database using a Lambda
function.
• If the task succeeds, an account is created and a welcome email is sent.
• If a user tries to create an account for a username that already exists, the Lambda function raises an
error, causing the state machine to suggest a diﬀerent username and to retry the account-creation
process.
The following code samples demonstrate how to do this. Note that custom errors in C# must extend the
Exception class.
namespace Example {
public class AccountAlreadyExistsException : Exception {
public AccountAlreadyExistsException(String message) :
base(message) {
}
}
}
namespace Example {
public class Handler {
public static void CreateAccount() {
throw new AccountAlreadyExistsException("Account is in use!");
}
}
}

You can conﬁgure Step Functions to catch the error using a Catch rule. Lambda automatically sets the
error name to the simple class name of the exception at runtime:
{

}

"StartAt": "CreateAccount",
"States": {
"CreateAccount": {
"Type": "Task",
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:CreateAccount",
"Next": "SendWelcomeEmail",
"Catch": [
{
"ErrorEquals": ["AccountAlreadyExistsException"],
"Next": "SuggestAccountName"
}
]
},
…
}

At runtime, AWS Step Functions catches the error, transitioning to the SuggestAccountName state as
speciﬁed in the Next transition.

334

AWS Lambda Developer Guide
Function Error Handling

Custom error handling makes it easier to create serverless applications. This feature integrates with
all the languages supported by the Lambda Programming Model (p. 18), allowing you to design your
application in the programming languages of your choice, mixing and matching as you go.
To learn more about creating your own serverless applications using AWS Step Functions and AWS
Lambda, see AWS Step Functions.

335

AWS Lambda Developer Guide
Deployment Package

Building Lambda Functions with
PowerShell
The following sections explain how common programming patterns and core concepts apply when you
author Lambda function code in PowerShell.

.NET Runtimes
Name

Identiﬁer

Languages

.NET Core 2.1

dotnetcore2.1

C#
PowerShell Core 6.0

.NET Core 2.0

dotnetcore2.0

C#

.NET Core 1.0

dotnetcore1.0

C#

Note that Lambda functions in PowerShell require PowerShell Core 6.0. Windows PowerShell isn't
supported.
Before you get started, you must ﬁrst set up a PowerShell development environment. For instructions on
how to do this, see Setting Up a PowerShell Development Environment (p. 337).
To learn about how to use the AWSLambdaPSCore module to download sample PowerShell projects
from templates, create PowerShell deployment packages, and deploy PowerShell functions to the AWS
Cloud, see Using the AWSLambdaPSCore Module (p. 337).
Topics
• AWS Lambda Deployment Package in PowerShell (p. 336)
• AWS Lambda Function Handler in PowerShell (p. 339)
• AWS Lambda Context Object in PowerShell (p. 340)
• AWS Lambda Function Logging in PowerShell (p. 341)
• AWS Lambda Function Errors in PowerShell (p. 341)

AWS Lambda Deployment Package in PowerShell
A PowerShell Lambda deployment package is a ZIP ﬁle that contains your PowerShell script, PowerShell
modules that are required for your PowerShell script, and the assemblies needed to host PowerShell
Core.
AWSLambdaPSCore is a PowerShell module that you can install from the PowerShell Gallery. You use
this module to create your PowerShell Lambda deployment package.
You're required to use the #Requires statement within your PowerShell scripts to indicate the modules
that your scripts depend on. This statement performs two important tasks. 1) It communicates to
other developers which modules the script uses, and 2) it identiﬁes the dependent modules that AWS
PowerShell tools need to package with the script, as part of the deployment. For more information

336

AWS Lambda Developer Guide
Setting Up a PowerShell Development Environment

about the #Requires statement in PowerShell, see About Requires. For more information about
PowerShell deployment packages, see AWS Lambda Deployment Package in PowerShell (p. 336).
When your PowerShell Lambda function uses the AWS PowerShell cmdlets, be sure to set a #Requires
statement that references the AWSPowerShell.NetCore module, which supports PowerShell Core—
and not the AWSPowerShell module, which only supports Windows PowerShell. Also, be sure to use
version 3.3.270.0 or newer of AWSPowerShell.NetCore, which optimizes the cmdlet import process. If
you use an older version, you'll experience longer cold starts. For more information, see AWS Tools for
PowerShell.
Before you get started, you must ﬁrst set up a PowerShell development environment. For instructions on
how to do this, see Setting Up a PowerShell Development Environment (p. 337).

Setting Up a PowerShell Development Environment
To set up your development environment for writing PowerShell scripts, do the following:
1.

Install the correct version of PowerShell. Lambda's support for PowerShell is based on the crossplatform PowerShell Core 6.0 release. This means that you can develop your PowerShell Lambda
functions on Windows, Linux, or Mac. If you don’t have this version of PowerShell installed, you can
ﬁnd instructions in Installing PowerShell Core.

2.

Install the .NET Core 2.1 SDK. Because PowerShell Core is built on top of .NET Core, the Lambda
support for PowerShell uses the same .NET Core 2.1 Lambda runtime for both .NET Core and
PowerShell Lambda functions. The .NET Core 2.1 SDK is used by the new Lambda PowerShell
publishing cmdlets to create the Lambda deployment package. The .NET Core 2.1 SDK is available
at .NET downloads on the Microsoft website. Be sure to install the SDK and not the runtime
installation.
Install the AWSLambdaPSCore module. You can install this either from the PowerShell Gallery, or
you can install it by using the following PowerShell Core shell command:

3.

Install-Module AWSLambdaPSCore -Scope CurrentUser

Next Steps
• To learn about writing Lambda functions in PowerShell, see Building Lambda Functions with
PowerShell (p. 336).
• To learn about using the AWSLambdaPSCore module to download sample PowerShell projects from
templates, creating PowerShell deployment packages, and deploying PowerShell functions to the AWS
Cloud, see Using the AWSLambdaPSCore Module (p. 337).

Using the AWSLambdaPSCore Module
The AWSLambdaPSCore module has the following new cmdlets to help author and publish PowerShell
Lambda functions.
Cmdlet Name

Description

Get#AWSPowerShellLambdaTemplate

Returns a list of getting started templates.

New#AWSPowerShellLambda

Creates an initial PowerShell script based on a
template.

Publish#AWSPowerShellLambda

Publishes a given PowerShell script to Lambda.

337

AWS Lambda Developer Guide
Using the AWSLambdaPSCore Module

Cmdlet Name

Description

New#AWSPowerShellLambdaPackage

Creates a Lambda deployment package that can
be used in a CI/CD system for deployment.

To help get started writing and invoking a PowerShell script with Lambda, you can use the NewAWSPowerShellLambda cmdlet to create a starter script based on a template. You can use the
Publish-AWSPowerShellLambda cmdlet to deploy your script to AWS Lambda. Then you can test your
script either through the command line or the console.
To create a new PowerShell script, upload it, and test it, follow this procedure:
1.

View available templates.
Run the following command to view the list of available templates:
PS C:\> Get-AWSPowerShellLambdaTemplate
Template
-------Basic
CodeCommitTrigger
DetectLabels
with detected labels.
KinesisStreamProcessor
S3Event
SNSSubscription
SQSQueueProcessor

2.

Description
----------Bare bones script
Script to process AWS CodeCommit Triggers
Use Amazon Rekognition service to tag image files in Amazon S3
Script
Script
Script
Script

to
to
to
to

process an Amazon Kinesis stream
process S3 events
be subscribed to an Amazon SNS topic
be subscribed to an Amazon SQS queue

Note that new templates are being listed all the time, so this output is just an example.
Create a basic script.
Run the following command to create a sample script based on the Basic template:
New-AWSPowerShellLambda -ScriptName MyFirstPSScript -Template Basic

A new ﬁle named MyFirstPSScript.ps1 is created in a new subdirectory of the current directory.
The name of the directory is based on the -ScriptName parameter. You can use the -Directory
parameter to choose an alternative directory.
You can see that the new ﬁle has the following contents:
# PowerShell script file to be executed as a AWS Lambda function.
#
# When executing in Lambda the following variables will be predefined.
#
$LambdaInput - A PSObject that contains the Lambda function input data.
#
$LambdaContext - An Amazon.Lambda.Core.ILambdaContext object that contains
information about the currently running Lambda environment.
#
# The last item in the PowerShell pipeline will be returned as the result of the Lambda
function.
#
# To include PowerShell modules with your Lambda function, like the
AWSPowerShell.NetCore module, add a "#Requires" statement
# indicating the module and version.
#Requires -Modules @{ModuleName='AWSPowerShell.NetCore';ModuleVersion='3.3.343.0'}
# Uncomment to send the input to CloudWatch Logs

338

AWS Lambda Developer Guide
Handler
# Write-Host (ConvertTo-Json -InputObject $LambdaInput -Compress -Depth 5)

3.

Edit the sample script.
To see how log messages from your PowerShell script are sent to CloudWatch Logs, uncomment the
Write-Host line of the sample script.
To demonstrate how you can return data back from your Lambda functions, add a new line at the
end of the script with $PSVersionTable. This adds the $PSVersionTable to the PowerShell
pipeline. After the PowerShell script is complete, the last object in the PowerShell pipeline is the
return data for the Lambda function. $PSVersionTable is a PowerShell global variable that also
provides information about the running environment.
After making these changes, the last two lines of the sample script look like this:
Write-Host (ConvertTo-Json -InputObject $LambdaInput -Compress -Depth 5)
$PSVersionTable

4.

Publish to AWS Lambda.
After editing the MyFirstPSScript.ps1 ﬁle, change the directory to the script's location. Then
run the following command to publish the script to AWS Lambda:
Publish-AWSPowerShellLambda -ScriptPath .\MyFirstPSScript.ps1 -Name
Region us-east-1

MyFirstPSScript -

Note that the -Name parameter speciﬁes the Lambda function name, which appears in the Lambda
console. You can use this function to invoke your script manually.
5.

Test the Lambda function.
You can test the PowerShell Lambda function that you just published by using the dotnet command
line interface (CLI) extension or the console. The following dotnet CLI command is an example of
how to test your function:
dotnet lambda invoke-function MyFirstPSScript --region us-east-1

For more information about the dotnet CLI extension, see .NET Core CLI (p. 317).

AWS Lambda Function Handler in PowerShell
When a Lambda function is invoked, the Lambda handler invokes the PowerShell script.
When the PowerShell script is invoked, the following variables are predeﬁned:
• $LambdaInput – A PSObject that contains the input to the handler. This input can be event data
(published by an event source) or custom input that you provide, such as a string or any custom data
object.
• $LambdaContext – An Amazon.Lambda.Core.ILambdaContext object that you can use to access
information about the current execution—such as the name of the current function, the memory limit,
execution time remaining, and logging.
For example, consider the following PowerShell example code.
#Requires -Modules @{ModuleName='AWSPowerShell.NetCore';ModuleVersion='3.3.343.0'}

339

AWS Lambda Developer Guide
Returning Data
Write-Host 'Function Name:' $LambdaContext.FunctionName

This script returns the FunctionName property that's obtained from the $LambdaContext variable.

Note

You're required to use the #Requires statement within your PowerShell scripts to indicate
the modules that your scripts depend on. This statement performs two important tasks. 1)
It communicates to other developers which modules the script uses, and 2) it identiﬁes the
dependent modules that AWS PowerShell tools need to package with the script, as part of the
deployment. For more information about the #Requires statement in PowerShell, see About
Requires. For more information about PowerShell deployment packages, see AWS Lambda
Deployment Package in PowerShell (p. 336).
When your PowerShell Lambda function uses the AWS PowerShell cmdlets, be sure to set a
#Requires statement that references the AWSPowerShell.NetCore module, which supports
PowerShell Core—and not the AWSPowerShell module, which only supports Windows
PowerShell. Also, be sure to use version 3.3.270.0 or newer of AWSPowerShell.NetCore which
optimizes the cmdlet import process. If you use an older version, you'll experience longer cold
starts. For more information, see AWS Tools for PowerShell.

Returning Data
Some Lambda invocations are meant to return data back to their caller. For example, if an invocation
was in response to a web request coming from API Gateway, then our Lambda function needs to return
back the response. For PowerShell Lambda, the last object that's added to the PowerShell pipeline is the
return data from the Lambda invocation. If the object is a string, the data is returned as is. Otherwise the
object is converted to JSON by using the ConvertTo-Json cmdlet.
For example, consider the following PowerShell statement, which adds $PSVersionTable to the
PowerShell pipeline:
$PSVersionTable

After the PowerShell script is ﬁnished, the last object in the PowerShell pipeline is the return data for
the Lambda function. $PSVersionTable is a PowerShell global variable that also provides information
about the running environment.

AWS Lambda Context Object in PowerShell
When Lambda runs your function, it passes context information by making a $LambdaContext variable
available to the handler (p. 339). This variable provides methods and properties with information about
the invocation, function, and execution environment.

Context Properties
• FunctionName – The name of the Lambda function.
• FunctionVersion – The version (p. 30) of the function.
• InvokedFunctionArn – The Amazon Resource Name (ARN) used to invoke the function. Indicates if
the invoker speciﬁed a version number or alias.
•
•
•
•
•

MemoryLimitInMB – The amount of memory conﬁgured on the function.
AwsRequestId – The identiﬁer of the invocation request.
LogGroupName – The log group for the function.
LogStreamName – The log stream for the function instance.
RemainingTime – The number of milliseconds left before the execution times out.

340

AWS Lambda Developer Guide
Logging

• Identity – (mobile apps) Information about the Amazon Cognito identity that authorized the
request.
• ClientContext – (mobile apps) Client context provided to the Lambda invoker by the client
application.
• Logger – The logger object (p. 341) for the function.
The following PowerShell code snippet shows a simple handler function that prints some of the context
information.
#Requires -Modules @{ModuleName='AWSPowerShell.NetCore';ModuleVersion='3.3.343.0'}
Write-Host 'Function name:' $LambdaContext.FunctionName
Write-Host 'Remaining milliseconds:' $LambdaContext.RemainingTime.TotalMilliseconds
Write-Host 'Log group name:' $LambdaContext.LogGroupName
Write-Host 'Log stream name:' $LambdaContext.LogStreamName

AWS Lambda Function Logging in PowerShell
Your Lambda function can contain logging statements and, in turn, AWS Lambda writes these logs to
CloudWatch Logs.
In the PowerShell Lambda programming model, the Write cmdlets like Write-Host, Write-Output,
and Write-Information are all written to CloudWatch Logs.
For example, the following example code writes a message to CloudWatch Logs:
Write-Host 'Hello World. This string is written to CloudWatch logs.'

How to Find Logs
You can ﬁnd the logs that your Lambda function writes, as follows:
• Find the logs in CloudWatch Logs. The $LambdaContext variable provides the LogGroupName and
the LogStreamName properties. Using these properties, you can ﬁnd the speciﬁc log stream where the
logs are written.
• If you invoke a Lambda function programmatically, you can add the LogType parameter to
retrieve the last 4 KB of log data that's written to CloudWatch Logs. For more information, see
Invoke (p. 410). AWS Lambda returns this log information in the x-amz-log-results header in
the response. If you use the AWS Command Line Interface (AWS CLI) to invoke the function, you can
specify the --log-type parameter with the value Tail.

AWS Lambda Function Errors in PowerShell
If your Lambda function has a terminating error, AWS Lambda recognizes the failure, serializes the error
information into JSON, and returns it.
Consider the following PowerShell script example statement:
throw 'The Account is not found'

When you invoke this Lambda function, it throws a terminating error, and AWS Lambda returns the
following error message:

341

AWS Lambda Developer Guide
Function Error Handling

{
}

"errorMessage": "The Account is not found",
"errorType": "RuntimeException"

Note the errorType is RuntimeException, which is the default exception thrown by PowerShell. You
can use custom error types by throwing the error like this:
throw @{'Exception'='AccountNotFound';'Message'='The Account is not found'}

The error message is serialized with errorType set to AccountNotFound:
{
}

"errorMessage": "The Account is not found",
"errorType": "AccountNotFound"

If you don't need an error message, you can throw a string in the format of an error code. The error code
format requires that the string starts with a character and only contain letters and digits afterwards, with
no spaces or symbols.
For example, if your Lambda function contains the following:
throw 'AccountNotFound'

The error is serialized like this:
{
}

"errorMessage": "AccountNotFound",
"errorType": "AccountNotFound"

Function Error Handling
You can use a custom errorType in your Lambda function and handle function errors directly (Retry
or Catch) within an AWS Step Functions State Machine. For more information, see Handling Error
Conditions Using a State Machine.
Custom error handling makes it easier to create serverless applications. This feature integrates with all
the languages that are supported by the Lambda Programming Model (p. 18). This allows you to design
your application in the programming languages of your choice, mixing and matching as you go.
To learn more about creating your own serverless applications using AWS Step Functions and AWS
Lambda, see AWS Step Functions.

342

AWS Lambda Developer Guide

Building Lambda Functions with
Ruby
You can run Ruby code in AWS Lambda. Lambda provides a runtime (p. 91) for Ruby that executes your
code to process events. Your code runs in an environment that includes the AWS SDK for Ruby, with
credentials from an AWS Identity and Access Management (IAM) role that you manage.
Lambda supports the following Ruby runtimes:

Ruby Runtimes
Name

Identiﬁer

Ruby 2.5

ruby2.5

If you don't already have an execution role for function development, create one.

To create an execution role
1.

Open the roles page in the IAM console.

2.

Choose Create role.

3.

Create a role with the following properties.
• Trusted entity – Lambda.
• Permissions – AWSLambdaBasicExecutionRole.
• Role name – lambda-role.
The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write
logs to CloudWatch Logs.

You can add permissions to the role later, or swap it out for a diﬀerent role that's speciﬁc to a single
function.

To create a Ruby function
1.

Open the Lambda console.

2.

Choose Create function.

3.

Conﬁgure the following settings:
• Name – ruby-function.
• Runtime – Ruby 2.5.
• Role – Choose an existing role.
• Existing role – lambda-role.

4.

Choose Create function.

5.

To conﬁgure a test event, choose Test.
343

AWS Lambda Developer Guide
Handler

6.

For Event name, enter test.

7.

Choose Create.

8.

To execute the function, choose Test.

The console creates a Lambda function with a single source ﬁle named lambda_function.rb. You can
edit this ﬁle and add more ﬁles in the built-in code editor (p. 11). Choose Save to save your changes, and
choose Test to run your code.

Note

The Lambda console uses AWS Cloud9 to provide an integrated development environment
in the browser. You can also use AWS Cloud9 to develop Lambda functions in your own
environment. See Working with AWS Lambda Functions in the AWS Cloud9 user guide for more
information.
lambda_function.rb deﬁnes a function named lambda_handler that takes an event object and a
context object. This is the handler function (p. 344) that Lambda calls when the function is invoked.
The Ruby function runtime gets invocation events from Lambda and passes them to the handler.
Each time you save your function code, the Lambda console creates a deployment package, which is a
ZIP archive that contains your function code. As your function development progresses, you will want to
store your function code in source control, add libraries, and automate deployments. Start by creating a
deployment package (p. 345) and updating your code at the command line.
The function runtime passes a context object to the handler, in addition to the invocation event. The
context object (p. 347) contains additional information about the invocation, the function, and the
execution environment. Further information is available from environment variables.
Your Lambda function comes with a CloudWatch Logs log group. The function runtime sends details
about each invocation to CloudWatch Logs, and relays any logs that your function outputs (p. 348)
during invocation. If your function returns an error (p. 348), Lambda formats the error and returns it to
the invoker.
Topics
• AWS Lambda Function Handler in Ruby (p. 344)
• AWS Lambda Deployment Package in Ruby (p. 345)
• AWS Lambda Context Object in Ruby (p. 347)
• AWS Lambda Function Logging in Ruby (p. 348)
• AWS Lambda Function Errors in Ruby (p. 348)

AWS Lambda Function Handler in Ruby
Your Lambda function's handler is the method that Lambda calls when your function is invoked. In the
following example, the ﬁle function.rb deﬁnes a handler method named handler. The handler
function takes two objects as input and returns a JSON document.

Example function.rb
require 'json'
def handler(event:, context:)
{ event: JSON.generate(event), context: JSON.generate(context.inspect) }
end

344

AWS Lambda Developer Guide
Deployment Package

In your function conﬁguration, the handler setting tells Lambda where to ﬁnd the handler. For the
preceding example, the correct value for this setting is function.handler. It includes two names
separated by a dot: the name of the ﬁle and the name of the handler method.
You can also deﬁne your handler method in a class. The following example deﬁnes a handler method
named process on a class named Handler in a module named LambdaFunctions.

Example source.rb
module LambdaFunctions
class Handler
def self.process(event:,context:)
"Hello!"
end
end
end

In this case, the handler setting is source.LambdaFunctions::Handler.process.
The two objects that the handler accepts are the invocation event and context. The event is a Ruby
object that contains the payload that's provided by the invoker. If the payload is a JSON document,
the event object is a Ruby hash. Otherwise, it's a string. The context object (p. 347) has methods and
properties that provide information about the invocation, the function, and the execution environment.
The function handler is executed every time your Lambda function is invoked. Static code outside of the
handler is executed once per instance of the function. If your handler uses resources like SDK clients and
database connections, you can create them outside of the handler method to reuse them for multiple
invocations.
Each instance of your function can process multiple invocation events, but it only processes one event at
a time. The number of instances processing an event at any given time is your function's concurrency. For
more information about the Lambda execution context, see AWS Lambda Execution Context (p. 93).

AWS Lambda Deployment Package in Ruby
A deployment package is a ZIP archive that contains your function code and dependencies. You need
to create a deployment package if you use the Lambda API to manage functions, or if your code
uses libraries other than the AWS SDK. Other libraries and dependencies need to be included in the
deployment package. You can upload the package directly to Lambda, or you can use an Amazon S3
bucket, and then upload it to Lambda.
If you use the Lambda console editor (p. 11) to author your function, the console manages the
deployment package. You can use this method as long as you don't need to add any libraries. You can
also use it to update a function that already has libraries in the deployment package, as long as the total
size doesn't exceed 3 MB.
Sections
• Updating a Function with No Dependencies (p. 345)
• Updating a Function with Additional Dependencies (p. 346)

Updating a Function with No Dependencies
To create or update a function with the Lambda API, create an archive that contains your function code
and upload it with the AWS CLI.

345

AWS Lambda Developer Guide
Updating a Function with Additional Dependencies

To update a Ruby function with no dependencies
1.

Create a ZIP archive.
~/my-function$ zip function.zip function.rb

2.

Use the update-function-code command to upload the package.
~/my-function$ aws lambda update-function-code --function-name ruby25 --zip-file
fileb://function.zip
{
"FunctionName": "ruby25",
"FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:ruby25",
"Runtime": "ruby2.5",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "function.handler",
"CodeSize": 300,
"Description": "",
"Timeout": 3,
"MemorySize": 128,
"LastModified": "2018-11-23T21:00:10.248+0000",
"CodeSha256": "Qf0haXm3JtGTmcDbjMc1I2di6YFMi9niEuiYonYptAk=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "Active"
},
"RevisionId": "d1e983e3-ca8e-434b-8dc1-7add83d72ebd"
}

Updating a Function with Additional Dependencies
If your function depends on libraries other than the AWS SDK for Ruby, install them to a local directory
with Bundler, and include them in your deployment package.

To update a Ruby function with dependencies
1.

Install libraries in the vendor directory with the bundle command.
~/my-function$ bundle install --path vendor/bundle
Fetching gem metadata from https://rubygems.org/..............
Resolving dependencies...
Fetching aws-eventstream 1.0.1
Installing aws-eventstream 1.0.1
...

The --path installs the gems in the project directory instead of the system location, and sets this as
the default path for future installations. To later install gems globally, use the --system option.
2.

Create a ZIP archive.
package$ zip -r function.zip function.rb vendor
adding: function.rb (deflated 37%)
adding: vendor/ (stored 0%)
adding: vendor/bundle/ (stored 0%)
adding: vendor/bundle/ruby/ (stored 0%)
adding: vendor/bundle/ruby/2.5.0/ (stored 0%)
adding: vendor/bundle/ruby/2.5.0/build_info/ (stored 0%)
adding: vendor/bundle/ruby/2.5.0/cache/ (stored 0%)
adding: vendor/bundle/ruby/2.5.0/cache/aws-eventstream-1.0.1.gem (deflated 36%)

346

AWS Lambda Developer Guide
Context
...

3.

Update the function code.
~/my-function$ aws lambda update-function-code --function-name ruby25 --zip-file
fileb://function.zip
{
"FunctionName": "ruby25",
"FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:ruby25",
"Runtime": "ruby2.5",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "function.handler",
"CodeSize": 998918,
"Description": "",
"Timeout": 3,
"MemorySize": 128,
"LastModified": "2018-11-20T20:51:35.871+0000",
"CodeSha256": "fJ3TxYnFosnnpN483dz9/rTzcXrbOiuu4iOZx34nXZI=",
"Version": "$LATEST",
"VpcConfig": {
"SubnetIds": [],
"SecurityGroupIds": [],
"VpcId": ""
},
"TracingConfig": {
"Mode": "Active"
},
"RevisionId": "9ca7c45b-bcda-4e51-ab5f-7c42fa916e39"
}

AWS Lambda Context Object in Ruby
When Lambda runs your function, it passes a context object to the handler (p. 344). This object
provides methods and properties that provide information about the invocation, function, and execution
environment.

Context Methods
• get_remaining_time_in_millis – Returns the number of milliseconds left before the execution
times out.

Context Properties
• function_name – The name of the Lambda function.
• function_version – The version (p. 30) of the function.
• invoked_function_arn – The Amazon Resource Name (ARN) used to invoke the function. Indicates
if the invoker speciﬁed a version number or alias.
• memory_limit_in_mb – The amount of memory conﬁgured on the function.
• aws_request_id – The identiﬁer of the invocation request.
• log_group_name – The log group for the function.
• log_stream_name – The log stream for the function instance.
• deadline_ms– The date that the execution times out, in Unix time milliseconds.
• identity – (mobile apps) Information about the Amazon Cognito identity that authorized the
request.

347

AWS Lambda Developer Guide
Logging

• client_context– (mobile apps) Client context provided to the Lambda invoker by the client
application.

AWS Lambda Function Logging in Ruby
Your Lambda function comes with a CloudWatch Logs log group, with a log stream for each instance of
your function. The runtime sends details about each invocation to the log stream, and relays logs and
other output from your function's code.

To view your Lambda function's logs
1.

Open the Logs page of the CloudWatch console.

2.

Choose the log group for your function (/aws/lambda/function-name).

3.

Choose the ﬁrst stream in the list.

To output logs from your function code, you can use puts statements, or any logging library that writes
to stdout or stderr.
To get logs for an invocation from the command line, use the --log-type option. The response
includes a LogResult ﬁeld that contains up to 4 KB of base64-encoded logs from the invocation.
$ aws lambda invoke --function-name ruby-function out --log-type Tail
{
"StatusCode": 200,
"LogResult":
"U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
"ExecutedVersion": "$LATEST"
}

You can use the base64 utility to decode the logs.
$ aws lambda invoke --function-name ruby-function out --log-type Tail \
--query 'LogResult' --output text | base64 -d
START RequestId: 8e827ab1-f155-11e8-b06d-018ab046158d Version: $LATEST
Processing event...
END RequestId: 8e827ab1-f155-11e8-b06d-018ab046158d
REPORT RequestId: 8e827ab1-f155-11e8-b06d-018ab046158d Duration: 29.40 ms
Duration: 100 ms
Memory Size: 128 MB
Max Memory Used: 19 MB

Billed

base64 is available on Linux, macOS, and Ubuntu on Windows. For macOS, the command is base64 -D.

AWS Lambda Function Errors in Ruby
When your code raises an error, Lambda generates a JSON representation of the error. This error
document appears in the invocation log and, for a synchronous invocation, in the output.

Example function.rb
def handler(event:, context:)
puts "Processing event..."
[1, 2, 3].first("two")
"Success"
end

348

AWS Lambda Developer Guide
Errors

This code results in a type error. Lambda catches the error and generates a JSON document with ﬁelds
for the error message, the type, and the stack trace.
{

}

"errorMessage": "no implicit conversion of String into Integer",
"errorType": "Function",
"stackTrace": [
"/var/task/function.rb:3:in `first'",
"/var/task/function.rb:3:in `handler'"
]

When you invoke the function from the command line, the status code doesn't change, but the response
includes a FunctionError ﬁeld, and the output includes the error document.
$ aws lambda invoke --function-name ruby-function out
{
"StatusCode": 200,
"FunctionError": "Unhandled",
"ExecutedVersion": "$LATEST"
}
$ cat out
{"errorMessage":"no implicit conversion of String into
Integer","errorType":"Function","stackTrace":["/var/task/function.rb:3:in
`first'","/var/task/function.rb:3:in `handler'"]}

To view the error in the error log, use the --log-type option and decode the base64 string in the
response.
$ aws lambda invoke --function-name ruby-function out --log-type Tail \
--query 'LogResult' --output text | base64 -d
START RequestId: 5ce6a15a-f156-11e8-b8aa-25371a5ca2a3 Version: $LATEST
Processing event...
Error raised from handler method
{
"errorMessage": "no implicit conversion of String into Integer",
"errorType": "Function",
"stackTrace": [
"/var/task/function.rb:3:in `first'",
"/var/task/function.rb:3:in `handler'"
]
}
END RequestId: 5ce6a15a-f156-11e8-b8aa-25371a5ca2a3
REPORT RequestId: 5ce6a15a-f156-11e8-b8aa-25371a5ca2a3 Duration: 22.74 ms
Duration: 100 ms
Memory Size: 128 MB
Max Memory Used: 18 MB

For more information, see AWS Lambda Function Logging in Ruby (p. 348).

349

Billed

AWS Lambda Developer Guide
Actions

API Reference
This section contains the AWS Lambda API Reference documentation. When making the API calls, you
will need to authenticate your request by providing a signature. AWS Lambda supports signature version
4. For more information, see Signature Version 4 Signing Process in the Amazon Web Services General
Reference.
For an overview of the service, see What Is AWS Lambda? (p. 1).
You can use the AWS CLI to explore the AWS Lambda API. This guide provides several tutorials that use
the AWS CLI.
Topics
• Actions (p. 350)
• Data Types (p. 479)

Actions
The following actions are supported:
• AddLayerVersionPermission (p. 352)
• AddPermission (p. 356)
• CreateAlias (p. 360)
• CreateEventSourceMapping (p. 364)
• CreateFunction (p. 368)
• DeleteAlias (p. 376)
• DeleteEventSourceMapping (p. 378)
• DeleteFunction (p. 381)
• DeleteFunctionConcurrency (p. 383)
• DeleteLayerVersion (p. 385)
• GetAccountSettings (p. 387)
• GetAlias (p. 389)
• GetEventSourceMapping (p. 392)
• GetFunction (p. 395)
• GetFunctionConﬁguration (p. 398)
• GetLayerVersion (p. 403)
• GetLayerVersionPolicy (p. 406)
• GetPolicy (p. 408)
• Invoke (p. 410)
• InvokeAsync (p. 415)
• ListAliases (p. 417)
• ListEventSourceMappings (p. 420)
• ListFunctions (p. 423)
• ListLayers (p. 426)
• ListLayerVersions (p. 428)

350

AWS Lambda Developer Guide
Actions

• ListTags (p. 431)
• ListVersionsByFunction (p. 433)
• PublishLayerVersion (p. 436)
• PublishVersion (p. 440)
• PutFunctionConcurrency (p. 446)
• RemoveLayerVersionPermission (p. 449)
• RemovePermission (p. 451)
• TagResource (p. 454)
• UntagResource (p. 456)
• UpdateAlias (p. 458)
• UpdateEventSourceMapping (p. 462)
• UpdateFunctionCode (p. 466)
• UpdateFunctionConﬁguration (p. 472)

351

AWS Lambda Developer Guide
AddLayerVersionPermission

AddLayerVersionPermission
Adds permissions to the resource-based policy of a version of an AWS Lambda layer. Use this action to
grant layer usage permission to other accounts. You can grant permission to a single account, all AWS
accounts, or all accounts in an organization.
To revoke permission, call RemoveLayerVersionPermission (p. 449) with the statement ID that you
speciﬁed when you added it.

Request Syntax
POST /2018-10-31/layers/LayerName/versions/VersionNumber/policy?RevisionId=RevisionId
HTTP/1.1
Content-type: application/json
{

}

"Action": "string",
"OrganizationId": "string",
"Principal": "string",
"StatementId": "string"

URI Request Parameters
The request requires the following URI parameters.
LayerName (p. 352)
The name or Amazon Resource Name (ARN) of the layer.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+)|
[a-zA-Z0-9-_]+
RevisionId (p. 352)
Only update the policy if the revision ID matches the ID speciﬁed. Use this option to avoid modifying
a policy that has changed since you last read it.
VersionNumber (p. 352)
The version number.

Request Body
The request accepts the following data in JSON format.
Action (p. 352)
The API action that grants access to the layer. For example, lambda:GetLayerVersion.
Type: String
Pattern: lambda:GetLayerVersion
Required: Yes

352

AWS Lambda Developer Guide
AddLayerVersionPermission

OrganizationId (p. 352)
With the principal set to *, grant permission to all accounts in the speciﬁed organization.
Type: String
Pattern: o-[a-z0-9]{10,32}
Required: No
Principal (p. 352)
An account ID, or * to grant permission to all AWS accounts.
Type: String
Pattern: \d{12}|\*|arn:(aws[a-zA-Z-]*):iam::\d{12}:root
Required: Yes
StatementId (p. 352)
An identiﬁer that distinguishes the policy from others on the same layer version.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 100.
Pattern: ([a-zA-Z0-9-_]+)
Required: Yes

Response Syntax
HTTP/1.1 201
Content-type: application/json
{
}

"RevisionId": "string",
"Statement": "string"

Response Elements
If the action is successful, the service sends back an HTTP 201 response.
The following data is returned in JSON format by the service.
RevisionId (p. 353)
A unique identiﬁer for the current revision of the policy.
Type: String
Statement (p. 353)
The permission statement.
Type: String

353

AWS Lambda Developer Guide
AddLayerVersionPermission

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
PolicyLengthExceededException
Lambda function access policy is limited to 20 KB.
HTTP Status Code: 400
PreconditionFailedException
The RevisionId provided does not match the latest RevisionId for the Lambda function or alias. Call
the GetFunction or the GetAlias API to retrieve the latest RevisionId for your resource.
HTTP Status Code: 412
ResourceConﬂictException
The resource already exists.
HTTP Status Code: 409
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
•
•
•
•
•

AWS SDK for .NET
AWS SDK for C++
AWS SDK for Go
AWS SDK for Java
AWS SDK for JavaScript

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

354

AWS Lambda Developer Guide
AddLayerVersionPermission

355

AWS Lambda Developer Guide
AddPermission

AddPermission
Grants an AWS service or another account permission to use a function. You can apply the policy at the
function level, or specify a qualiﬁer to restrict access to a single version or alias. If you use a qualiﬁer, the
invoker must use the full Amazon Resource Name (ARN) of that version or alias to invoke the function.
To grant permission to another account, specify the account ID as the Principal. For AWS services,
the principal is a domain-style identiﬁer deﬁned by the service, like s3.amazonaws.com or
sns.amazonaws.com. For AWS services, you can also specify the ARN or owning account of the
associated resource as the SourceArn or SourceAccount. If you grant permission to a service principal
without specifying the source, other accounts could potentially conﬁgure resources in their account to
invoke your Lambda function.
This action adds a statement to a resource-based permission policy for the function. For more
information about function policies, see Lambda Function Policies.

Request Syntax
POST /2015-03-31/functions/FunctionName/policy?Qualifier=Qualifier HTTP/1.1
Content-type: application/json
{

}

"Action": "string",
"EventSourceToken": "string",
"Principal": "string",
"RevisionId": "string",
"SourceAccount": "string",
"SourceArn": "string",
"StatementId": "string"

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 356)
The name of the Lambda function, version, or alias.

Name formats
• Function name - my-function (name-only), my-function:v1 (with alias).
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
You can append a version number or alias to any of the formats. The length constraint applies only
to the full ARN. If you specify only the function name, it is limited to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Qualiﬁer (p. 356)
Specify a version or alias to add permissions to a published version of the function.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (|[a-zA-Z0-9$_-]+)

356

AWS Lambda Developer Guide
AddPermission

Request Body
The request accepts the following data in JSON format.
Action (p. 356)
The action that the principal can use on the function. For example, lambda:InvokeFunction or
lambda:GetFunction.
Type: String
Pattern: (lambda:[*]|lambda:[a-zA-Z]+|[*])
Required: Yes
EventSourceToken (p. 356)
For Alexa Smart Home functions, a token that must be supplied by the invoker.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Pattern: [a-zA-Z0-9._\-]+
Required: No
Principal (p. 356)
The AWS service or account that invokes the function. If you specify a service, use SourceArn or
SourceAccount to limit who can invoke the function through that service.
Type: String
Pattern: .*
Required: Yes
RevisionId (p. 356)
Only update the policy if the revision ID matches the ID speciﬁed. Use this option to avoid modifying
a policy that has changed since you last read it.
Type: String
Required: No
SourceAccount (p. 356)
For AWS services, the ID of the account that owns the resource. Use instead of SourceArn to grant
permission to resources owned by another account (e.g. all of an account's Amazon S3 buckets). Or
use together with SourceArn to ensure that the resource is owned by the speciﬁed account. For
example, an Amazon S3 bucket could be deleted by its owner and recreated by another account.
Type: String
Pattern: \d{12}
Required: No
SourceArn (p. 356)
For AWS services, the ARN of the AWS resource that invokes the function. For example, an Amazon
S3 bucket or Amazon SNS topic.

357

AWS Lambda Developer Guide
AddPermission

Type: String
Pattern: arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+\d{1})?:(\d{12})?:(.*)
Required: No
StatementId (p. 356)
A statement identiﬁer that diﬀerentiates the statement from others in the same policy.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 100.
Pattern: ([a-zA-Z0-9-_]+)
Required: Yes

Response Syntax
HTTP/1.1 201
Content-type: application/json
{
}

"Statement": "string"

Response Elements
If the action is successful, the service sends back an HTTP 201 response.
The following data is returned in JSON format by the service.
Statement (p. 358)
The permission statement added to the function policy.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
PolicyLengthExceededException
Lambda function access policy is limited to 20 KB.
HTTP Status Code: 400
PreconditionFailedException
The RevisionId provided does not match the latest RevisionId for the Lambda function or alias. Call
the GetFunction or the GetAlias API to retrieve the latest RevisionId for your resource.

358

AWS Lambda Developer Guide
AddPermission

HTTP Status Code: 412
ResourceConﬂictException
The resource already exists.
HTTP Status Code: 409
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

359

AWS Lambda Developer Guide
CreateAlias

CreateAlias
Creates an alias for a Lambda function version. Use aliases to provide clients with a function identiﬁer
that you can update to invoke a diﬀerent version.
You can also map an alias to split invocation requests between two versions. Use the RoutingConfig
parameter to specify a second version and the percentage of invocation requests that it receives.

Request Syntax
POST /2015-03-31/functions/FunctionName/aliases HTTP/1.1
Content-type: application/json
{

}

"Description": "string",
"FunctionVersion": "string",
"Name": "string",
"RoutingConfig": {
"AdditionalVersionWeights": {
"string" : number
}
}

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 360)
The name of the lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

Request Body
The request accepts the following data in JSON format.
Description (p. 360)
A description of the alias.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.

360

AWS Lambda Developer Guide
CreateAlias

Required: No
FunctionVersion (p. 360)
The function version that the alias invokes.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
Required: Yes
Name (p. 360)
The name of the alias.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (?!^[0-9]+$)([a-zA-Z0-9-_]+)
Required: Yes
RoutingConﬁg (p. 360)
The routing conﬁguration of the alias.
Type: AliasRoutingConﬁguration (p. 484) object
Required: No

Response Syntax
HTTP/1.1 201
Content-type: application/json
{

}

"AliasArn": "string",
"Description": "string",
"FunctionVersion": "string",
"Name": "string",
"RevisionId": "string",
"RoutingConfig": {
"AdditionalVersionWeights": {
"string" : number
}
}

Response Elements
If the action is successful, the service sends back an HTTP 201 response.
The following data is returned in JSON format by the service.
AliasArn (p. 361)
The Amazon Resource Name (ARN) of the alias.

361

AWS Lambda Developer Guide
CreateAlias

Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
Description (p. 361)
A description of the alias.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
FunctionVersion (p. 361)
The function version that the alias invokes.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
Name (p. 361)
The name of the alias.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (?!^[0-9]+$)([a-zA-Z0-9-_]+)
RevisionId (p. 361)
A unique identiﬁer that changes when you update the alias.
Type: String
RoutingConﬁg (p. 361)
The routing conﬁguration of the alias.
Type: AliasRoutingConﬁguration (p. 484) object

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceConﬂictException
The resource already exists.
HTTP Status Code: 409
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.

362

AWS Lambda Developer Guide
CreateAlias

HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

363

AWS Lambda Developer Guide
CreateEventSourceMapping

CreateEventSourceMapping
Creates a mapping between an event source and an AWS Lambda function. Lambda reads items from the
event source and triggers the function.
For details about each event source type, see the following topics.
• Using AWS Lambda with Amazon Kinesis
• Using AWS Lambda with Amazon SQS
• Using AWS Lambda with Amazon DynamoDB

Request Syntax
POST /2015-03-31/event-source-mappings/ HTTP/1.1
Content-type: application/json
{

}

"BatchSize": number,
"Enabled": boolean,
"EventSourceArn": "string",
"FunctionName": "string",
"StartingPosition": "string",
"StartingPositionTimestamp": number

URI Request Parameters
The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.
BatchSize (p. 364)
The maximum number of items to retrieve in a single batch.
• Amazon Kinesis - Default 100. Max 10,000.
• Amazon DynamoDB Streams - Default 100. Max 1,000.
• Amazon Simple Queue Service - Default 10. Max 10.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10000.
Required: No
Enabled (p. 364)
Disables the event source mapping to pause polling and invocation.
Type: Boolean
Required: No
EventSourceArn (p. 364)
The Amazon Resource Name (ARN) of the event source.

364

AWS Lambda Developer Guide
CreateEventSourceMapping

• Amazon Kinesis - The ARN of the data stream or a stream consumer.
• Amazon DynamoDB Streams - The ARN of the stream.
• Amazon Simple Queue Service - The ARN of the queue.
Type: String
Pattern: arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+\d{1})?:(\d{12})?:(.*)
Required: Yes
FunctionName (p. 364)
The name of the Lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Version or Alias ARN - arn:aws:lambda:uswest-2:123456789012:function:MyFunction:PROD.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it's limited
to 64 characters in length.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Required: Yes
StartingPosition (p. 364)
The position in a stream from which to start reading. Required for Amazon Kinesis and Amazon
DynamoDB Streams sources. AT_TIMESTAMP is only supported for Amazon Kinesis streams.
Type: String
Valid Values: TRIM_HORIZON | LATEST | AT_TIMESTAMP
Required: No
StartingPositionTimestamp (p. 364)
With StartingPosition set to AT_TIMESTAMP, the time from which to start reading, in Unix time
seconds.
Type: Timestamp
Required: No

Response Syntax
HTTP/1.1 202
Content-type: application/json

365

AWS Lambda Developer Guide
CreateEventSourceMapping
{

}

"BatchSize": number,
"EventSourceArn": "string",
"FunctionArn": "string",
"LastModified": number,
"LastProcessingResult": "string",
"State": "string",
"StateTransitionReason": "string",
"UUID": "string"

Response Elements
If the action is successful, the service sends back an HTTP 202 response.
The following data is returned in JSON format by the service.
BatchSize (p. 365)
The maximum number of items to retrieve in a single batch.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10000.
EventSourceArn (p. 365)
The Amazon Resource Name (ARN) of the event source.
Type: String
Pattern: arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+\d{1})?:(\d{12})?:(.*)
FunctionArn (p. 365)
The ARN of the Lambda function.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
LastModiﬁed (p. 365)
The date that the event source mapping was last updated, in Unix time seconds.
Type: Timestamp
LastProcessingResult (p. 365)
The result of the last AWS Lambda invocation of your Lambda function.
Type: String
State (p. 365)
The state of the event source mapping. It can be one of the following: Creating, Enabling,
Enabled, Disabling, Disabled, Updating, or Deleting.
Type: String
StateTransitionReason (p. 365)
The cause of the last state change, either User initiated or Lambda initiated.

366

AWS Lambda Developer Guide
CreateEventSourceMapping

Type: String
UUID (p. 365)
The identiﬁer of the event source mapping.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceConﬂictException
The resource already exists.
HTTP Status Code: 409
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
•
•
•
•

AWS SDK for .NET
AWS SDK for C++
AWS SDK for Go
AWS SDK for Java

•
•
•
•

AWS SDK for JavaScript
AWS SDK for PHP V3
AWS SDK for Python
AWS SDK for Ruby V2

367

AWS Lambda Developer Guide
CreateFunction

CreateFunction
Creates a Lambda function. To create a function, you need a deployment package and an execution role.
The deployment package contains your function code. The execution role grants the function permission
to use AWS services such as Amazon CloudWatch Logs for log streaming and AWS X-Ray for request
tracing.
A function has an unpublished version, and can have published versions and aliases. A published version
is a snapshot of your function code and conﬁguration that can not be changed. An alias is a named
resource that maps to a version, and can be changed to map to a diﬀerent version. Use the Publish
parameter to create version 1 of your function from its initial conﬁguration.
The other parameters let you conﬁgure version-speciﬁc and function-level settings. You can modify
version-speciﬁc settings later with UpdateFunctionConﬁguration (p. 472). Function-level settings apply
to both the unpublished and published versions of the function and include tags (TagResource (p. 454))
and per-function concurrency limits (PutFunctionConcurrency (p. 446)).
If another account or a AWS service invokes your function, use AddPermission (p. 356) to grant
permission by creating a resource-based IAM policy. You can grant permissions at the function level, on a
version, or on an alias.
To invoke your function directly, use Invoke (p. 410). To invoke your function in response to events in
other AWS services, create an event source mapping (CreateEventSourceMapping (p. 364)), or conﬁgure a
function trigger in the other service. For more information, see Invoking Functions.

Request Syntax
POST /2015-03-31/functions HTTP/1.1
Content-type: application/json
{

"Code": {
"S3Bucket": "string",
"S3Key": "string",
"S3ObjectVersion": "string",
"ZipFile": blob
},
"DeadLetterConfig": {
"TargetArn": "string"
},
"Description": "string",
"Environment": {
"Variables": {
"string" : "string"
}
},
"FunctionName": "string",
"Handler": "string",
"KMSKeyArn": "string",
"Layers": [ "string" ],
"MemorySize": number,
"Publish": boolean,
"Role": "string",
"Runtime": "string",
"Tags": {
"string" : "string"
},
"Timeout": number,
"TracingConfig": {
"Mode": "string"
},

368

AWS Lambda Developer Guide
CreateFunction

}

"VpcConfig": {
"SecurityGroupIds": [ "string" ],
"SubnetIds": [ "string" ]
}

URI Request Parameters
The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.
Code (p. 368)
The code for the function.
Type: FunctionCode (p. 492) object
Required: Yes
DeadLetterConﬁg (p. 368)
A dead letter queue conﬁguration that speciﬁes the queue or topic where Lambda sends
asynchronous events when they fail processing. For more information, see Dead Letter Queues.
Type: DeadLetterConﬁg (p. 486) object
Required: No
Description (p. 368)
A description of the function.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Required: No
Environment (p. 368)
Environment variables that are accessible from function code during execution.
Type: Environment (p. 487) object
Required: No
FunctionName (p. 368)
The name of the Lambda function.

Name formats
• Function name - my-function.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Type: String

369

AWS Lambda Developer Guide
CreateFunction

Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Required: Yes
Handler (p. 368)
The name of the method within your code that Lambda calls to execute your function. The format
includes the ﬁlename and can also include namespaces and other qualiﬁers, depending on the
runtime. For more information, see Programming Model.
Type: String
Length Constraints: Maximum length of 128.
Pattern: [^\s]+
Required: Yes
KMSKeyArn (p. 368)
The ARN of the AWS Key Management Service key used to encrypt your function's environment
variables. If not provided, AWS Lambda uses a default service key.
Type: String
Pattern: (arn:(aws[a-zA-Z-]*)?:[a-z0-9-.]+:.*)|()
Required: No
Layers (p. 368)
A list of function layers to add to the function's execution environment. Specify each layer by ARN,
including the version.
Type: Array of strings
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+:
[0-9]+
Required: No
MemorySize (p. 368)
The amount of memory that your function has access to. Increasing the function's memory also
increases it's CPU allocation. The default value is 128 MB. The value must be a multiple of 64 MB.
Type: Integer
Valid Range: Minimum value of 128. Maximum value of 3008.
Required: No
Publish (p. 368)
Set to true to publish the ﬁrst version of the function during creation.
Type: Boolean
Required: No

370

AWS Lambda Developer Guide
CreateFunction

Role (p. 368)
The Amazon Resource Name (ARN) of the function's execution role.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+
Required: Yes
Runtime (p. 368)
The identiﬁer of the function's runtime.
Type: String
Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided
Required: Yes
Tags (p. 368)
A list of tags to apply to the function.
Type: String to string map
Required: No
Timeout (p. 368)
The amount of time that Lambda allows a function to run before terminating it. The default is 3
seconds. The maximum allowed value is 900 seconds.
Type: Integer
Valid Range: Minimum value of 1.
Required: No
TracingConﬁg (p. 368)
Set Mode to Active to sample and trace a subset of incoming requests with AWS X-Ray.
Type: TracingConﬁg (p. 504) object
Required: No
VpcConﬁg (p. 368)
For network connectivity to AWS resources in a VPC, specify a list of security groups and subnets
in the VPC. When you connect a function to a VPC, it can only access resources and the internet
through that VPC. For more information, see VPC Settings.
Type: VpcConﬁg (p. 506) object
Required: No

Response Syntax
HTTP/1.1 201
Content-type: application/json

371

AWS Lambda Developer Guide
CreateFunction
{

}

"CodeSha256": "string",
"CodeSize": number,
"DeadLetterConfig": {
"TargetArn": "string"
},
"Description": "string",
"Environment": {
"Error": {
"ErrorCode": "string",
"Message": "string"
},
"Variables": {
"string" : "string"
}
},
"FunctionArn": "string",
"FunctionName": "string",
"Handler": "string",
"KMSKeyArn": "string",
"LastModified": "string",
"Layers": [
{
"Arn": "string",
"CodeSize": number
}
],
"MasterArn": "string",
"MemorySize": number,
"RevisionId": "string",
"Role": "string",
"Runtime": "string",
"Timeout": number,
"TracingConfig": {
"Mode": "string"
},
"Version": "string",
"VpcConfig": {
"SecurityGroupIds": [ "string" ],
"SubnetIds": [ "string" ],
"VpcId": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 201 response.
The following data is returned in JSON format by the service.
CodeSha256 (p. 371)
The SHA256 hash of the function's deployment package.
Type: String
CodeSize (p. 371)
The size of the function's deployment package in bytes.
Type: Long
DeadLetterConﬁg (p. 371)
The function's dead letter queue.

372

AWS Lambda Developer Guide
CreateFunction

Type: DeadLetterConﬁg (p. 486) object
Description (p. 371)
The function's description.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Environment (p. 371)
The function's environment variables.
Type: EnvironmentResponse (p. 489) object
FunctionArn (p. 371)
The function's Amazon Resource Name (ARN).
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_\.]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
FunctionName (p. 371)
The name of the function.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Handler (p. 371)
The function Lambda calls to begin executing your function.
Type: String
Length Constraints: Maximum length of 128.
Pattern: [^\s]+
KMSKeyArn (p. 371)
The KMS key used to encrypt the function's environment variables. Only returned if you've
conﬁgured a customer managed CMK.
Type: String
Pattern: (arn:(aws[a-zA-Z-]*)?:[a-z0-9-.]+:.*)|()
LastModiﬁed (p. 371)
The date and time that the function was last updated, in ISO-8601 format (YYYY-MMDDThh:mm:ss.sTZD).
Type: String
Layers (p. 371)
The function's layers
Type: Array of Layer (p. 498) objects

373

AWS Lambda Developer Guide
CreateFunction

MasterArn (p. 371)
For Lambda@Edge functions, the ARN of the master function.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
MemorySize (p. 371)
The memory allocated to the function
Type: Integer
Valid Range: Minimum value of 128. Maximum value of 3008.
RevisionId (p. 371)
Represents the latest updated revision of the function or alias.
Type: String
Role (p. 371)
The function's execution role.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+
Runtime (p. 371)
The runtime environment for the Lambda function.
Type: String
Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided
Timeout (p. 371)
The amount of time that Lambda allows a function to run before terminating it.
Type: Integer
Valid Range: Minimum value of 1.
TracingConﬁg (p. 371)
The function's AWS X-Ray tracing conﬁguration.
Type: TracingConﬁgResponse (p. 505) object
Version (p. 371)
The version of the Lambda function.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
VpcConﬁg (p. 371)
The function's networking conﬁguration.

374

AWS Lambda Developer Guide
CreateFunction

Type: VpcConﬁgResponse (p. 507) object

Errors
CodeStorageExceededException
You have exceeded your maximum total code size per account. Limits
HTTP Status Code: 400
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceConﬂictException
The resource already exists.
HTTP Status Code: 409
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
•
•
•
•

AWS SDK for .NET
AWS SDK for C++
AWS SDK for Go
AWS SDK for Java

•
•
•
•

AWS SDK for JavaScript
AWS SDK for PHP V3
AWS SDK for Python
AWS SDK for Ruby V2

375

AWS Lambda Developer Guide
DeleteAlias

DeleteAlias
Deletes a Lambda function alias.

Request Syntax
DELETE /2015-03-31/functions/FunctionName/aliases/Name HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 376)
The name of the lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Name (p. 376)
The name of the alias.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (?!^[0-9]+$)([a-zA-Z0-9-_]+)

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.

376

AWS Lambda Developer Guide
DeleteAlias

HTTP Status Code: 400
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

377

AWS Lambda Developer Guide
DeleteEventSourceMapping

DeleteEventSourceMapping
Deletes an event source mapping. You can get the identiﬁer of a mapping from the output of
ListEventSourceMappings (p. 420).

Request Syntax
DELETE /2015-03-31/event-source-mappings/UUID HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
UUID (p. 378)
The identiﬁer of the event source mapping.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 202
Content-type: application/json
{

}

"BatchSize": number,
"EventSourceArn": "string",
"FunctionArn": "string",
"LastModified": number,
"LastProcessingResult": "string",
"State": "string",
"StateTransitionReason": "string",
"UUID": "string"

Response Elements
If the action is successful, the service sends back an HTTP 202 response.
The following data is returned in JSON format by the service.
BatchSize (p. 378)
The maximum number of items to retrieve in a single batch.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10000.
EventSourceArn (p. 378)
The Amazon Resource Name (ARN) of the event source.
Type: String

378

AWS Lambda Developer Guide
DeleteEventSourceMapping

Pattern: arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+\d{1})?:(\d{12})?:(.*)
FunctionArn (p. 378)
The ARN of the Lambda function.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
LastModiﬁed (p. 378)
The date that the event source mapping was last updated, in Unix time seconds.
Type: Timestamp
LastProcessingResult (p. 378)
The result of the last AWS Lambda invocation of your Lambda function.
Type: String
State (p. 378)
The state of the event source mapping. It can be one of the following: Creating, Enabling,
Enabled, Disabling, Disabled, Updating, or Deleting.
Type: String
StateTransitionReason (p. 378)
The cause of the last state change, either User initiated or Lambda initiated.
Type: String
UUID (p. 378)
The identiﬁer of the event source mapping.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceInUseException
The operation conﬂicts with the resource's availability. For example, you attempted to update
an EventSource Mapping in CREATING, or tried to delete a EventSource mapping currently in the
UPDATING state.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.

379

AWS Lambda Developer Guide
DeleteEventSourceMapping

HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

380

AWS Lambda Developer Guide
DeleteFunction

DeleteFunction
Deletes a Lambda function. To delete a speciﬁc function version, use the Qualifier parameter.
Otherwise, all versions and aliases are deleted.
To delete Lambda event source mappings that invoke a function, use
DeleteEventSourceMapping (p. 378). For AWS services and resources that invoke your function directly,
delete the trigger in the service where you originally conﬁgured it.

Request Syntax
DELETE /2015-03-31/functions/FunctionName?Qualifier=Qualifier HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 381)
The name of the Lambda function or version.

Name formats
• Function name - my-function (name-only), my-function:1 (with version).
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
You can append a version number or alias to any of the formats. The length constraint applies only
to the full ARN. If you specify only the function name, it is limited to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Qualiﬁer (p. 381)
Specify a version to delete. You cannot delete a version that is referenced by an alias.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (|[a-zA-Z0-9$_-]+)

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

381

AWS Lambda Developer Guide
DeleteFunction

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceConﬂictException
The resource already exists.
HTTP Status Code: 409
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

382

AWS Lambda Developer Guide
DeleteFunctionConcurrency

DeleteFunctionConcurrency
Removes a concurrent execution limit from a function.

Request Syntax
DELETE /2017-10-31/functions/FunctionName/concurrency HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 383)
The name of the Lambda function.

Name formats
• Function name - my-function.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.

383

AWS Lambda Developer Guide
DeleteFunctionConcurrency

HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

384

AWS Lambda Developer Guide
DeleteLayerVersion

DeleteLayerVersion
Deletes a version of an AWS Lambda layer. Deleted versions can no longer be viewed or added to
functions. To avoid breaking functions, a copy of the version remains in Lambda until no functions refer
to it.

Request Syntax
DELETE /2018-10-31/layers/LayerName/versions/VersionNumber HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
LayerName (p. 385)
The name or Amazon Resource Name (ARN) of the layer.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+)|
[a-zA-Z0-9-_]+
VersionNumber (p. 385)
The version number.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Errors
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

385

AWS Lambda Developer Guide
DeleteLayerVersion

• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

386

AWS Lambda Developer Guide
GetAccountSettings

GetAccountSettings
Retrieves details about your account's limits and usage in a region.

Request Syntax
GET /2016-08-19/account-settings/ HTTP/1.1

URI Request Parameters
The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

}

"AccountLimit": {
"CodeSizeUnzipped": number,
"CodeSizeZipped": number,
"ConcurrentExecutions": number,
"TotalCodeSize": number,
"UnreservedConcurrentExecutions": number
},
"AccountUsage": {
"FunctionCount": number,
"TotalCodeSize": number
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
AccountLimit (p. 387)
Limits related to concurrency and code storage.
Type: AccountLimit (p. 480) object
AccountUsage (p. 387)
The number of functions and amount of storage in use.
Type: AccountUsage (p. 481) object

Errors
ServiceException
The AWS Lambda service encountered an internal error.

387

AWS Lambda Developer Guide
GetAccountSettings

HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

388

AWS Lambda Developer Guide
GetAlias

GetAlias
Returns details about a Lambda function alias.

Request Syntax
GET /2015-03-31/functions/FunctionName/aliases/Name HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 389)
The name of the lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Name (p. 389)
The name of the alias.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (?!^[0-9]+$)([a-zA-Z0-9-_]+)

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

"AliasArn": "string",
"Description": "string",
"FunctionVersion": "string",
"Name": "string",
"RevisionId": "string",
"RoutingConfig": {
"AdditionalVersionWeights": {
"string" : number
}
}

389

AWS Lambda Developer Guide
GetAlias
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
AliasArn (p. 389)
The Amazon Resource Name (ARN) of the alias.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
Description (p. 389)
A description of the alias.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
FunctionVersion (p. 389)
The function version that the alias invokes.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
Name (p. 389)
The name of the alias.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (?!^[0-9]+$)([a-zA-Z0-9-_]+)
RevisionId (p. 389)
A unique identiﬁer that changes when you update the alias.
Type: String
RoutingConﬁg (p. 389)
The routing conﬁguration of the alias.
Type: AliasRoutingConﬁguration (p. 484) object

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.

390

AWS Lambda Developer Guide
GetAlias

HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

391

AWS Lambda Developer Guide
GetEventSourceMapping

GetEventSourceMapping
Returns details about an event source mapping. You can get the identiﬁer of a mapping from the output
of ListEventSourceMappings (p. 420).

Request Syntax
GET /2015-03-31/event-source-mappings/UUID HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
UUID (p. 392)
The identiﬁer of the event source mapping.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

}

"BatchSize": number,
"EventSourceArn": "string",
"FunctionArn": "string",
"LastModified": number,
"LastProcessingResult": "string",
"State": "string",
"StateTransitionReason": "string",
"UUID": "string"

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
BatchSize (p. 392)
The maximum number of items to retrieve in a single batch.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10000.
EventSourceArn (p. 392)
The Amazon Resource Name (ARN) of the event source.
Type: String

392

AWS Lambda Developer Guide
GetEventSourceMapping

Pattern: arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+\d{1})?:(\d{12})?:(.*)
FunctionArn (p. 392)
The ARN of the Lambda function.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
LastModiﬁed (p. 392)
The date that the event source mapping was last updated, in Unix time seconds.
Type: Timestamp
LastProcessingResult (p. 392)
The result of the last AWS Lambda invocation of your Lambda function.
Type: String
State (p. 392)
The state of the event source mapping. It can be one of the following: Creating, Enabling,
Enabled, Disabling, Disabled, Updating, or Deleting.
Type: String
StateTransitionReason (p. 392)
The cause of the last state change, either User initiated or Lambda initiated.
Type: String
UUID (p. 392)
The identiﬁer of the event source mapping.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500

393

AWS Lambda Developer Guide
GetEventSourceMapping

TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

394

AWS Lambda Developer Guide
GetFunction

GetFunction
Returns information about function or function version, with a link to download the deployment
package that's valid for 10 minutes. If you specify a function version, only details speciﬁc to that version
are returned.

Request Syntax
GET /2015-03-31/functions/FunctionName?Qualifier=Qualifier HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 395)
The name of the Lambda function, version, or alias.

Name formats
• Function name - my-function (name-only), my-function:v1 (with alias).
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
You can append a version number or alias to any of the formats. The length constraint applies only
to the full ARN. If you specify only the function name, it is limited to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Qualiﬁer (p. 395)
Specify a version or alias to get details about a published version of the function.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (|[a-zA-Z0-9$_-]+)

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

"Code": {
"Location": "string",
"RepositoryType": "string"
},
"Concurrency": {
"ReservedConcurrentExecutions": number

395

AWS Lambda Developer Guide
GetFunction

}

},
"Configuration": {
"CodeSha256": "string",
"CodeSize": number,
"DeadLetterConfig": {
"TargetArn": "string"
},
"Description": "string",
"Environment": {
"Error": {
"ErrorCode": "string",
"Message": "string"
},
"Variables": {
"string" : "string"
}
},
"FunctionArn": "string",
"FunctionName": "string",
"Handler": "string",
"KMSKeyArn": "string",
"LastModified": "string",
"Layers": [
{
"Arn": "string",
"CodeSize": number
}
],
"MasterArn": "string",
"MemorySize": number,
"RevisionId": "string",
"Role": "string",
"Runtime": "string",
"Timeout": number,
"TracingConfig": {
"Mode": "string"
},
"Version": "string",
"VpcConfig": {
"SecurityGroupIds": [ "string" ],
"SubnetIds": [ "string" ],
"VpcId": "string"
}
},
"Tags": {
"string" : "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
Code (p. 395)
The deployment package of the function or version.
Type: FunctionCodeLocation (p. 493) object
Concurrency (p. 395)
The function's reserved concurrency.

396

AWS Lambda Developer Guide
GetFunction

Type: Concurrency (p. 485) object
Conﬁguration (p. 395)
The conﬁguration of the function or version.
Type: FunctionConﬁguration (p. 494) object
Tags (p. 395)
The function's tags.
Type: String to string map

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
•
•
•
•

AWS SDK for .NET
AWS SDK for C++
AWS SDK for Go
AWS SDK for Java

•
•
•
•

AWS SDK for JavaScript
AWS SDK for PHP V3
AWS SDK for Python
AWS SDK for Ruby V2

397

AWS Lambda Developer Guide
GetFunctionConﬁguration

GetFunctionConﬁguration
Returns a the version-speciﬁc settings of a Lambda function or version. The output includes
only options that can vary between versions of a function. To modify these settings, use
UpdateFunctionConﬁguration (p. 472).
To get all of a function's details, including function-level settings, use GetFunction (p. 395).

Request Syntax
GET /2015-03-31/functions/FunctionName/configuration?Qualifier=Qualifier HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 398)
The name of the Lambda function, version, or alias.

Name formats
• Function name - my-function (name-only), my-function:v1 (with alias).
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
You can append a version number or alias to any of the formats. The length constraint applies only
to the full ARN. If you specify only the function name, it is limited to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Qualiﬁer (p. 398)
Specify a version or alias to get details about a published version of the function.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (|[a-zA-Z0-9$_-]+)

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

"CodeSha256": "string",
"CodeSize": number,
"DeadLetterConfig": {
"TargetArn": "string"
},

398

AWS Lambda Developer Guide
GetFunctionConﬁguration

}

"Description": "string",
"Environment": {
"Error": {
"ErrorCode": "string",
"Message": "string"
},
"Variables": {
"string" : "string"
}
},
"FunctionArn": "string",
"FunctionName": "string",
"Handler": "string",
"KMSKeyArn": "string",
"LastModified": "string",
"Layers": [
{
"Arn": "string",
"CodeSize": number
}
],
"MasterArn": "string",
"MemorySize": number,
"RevisionId": "string",
"Role": "string",
"Runtime": "string",
"Timeout": number,
"TracingConfig": {
"Mode": "string"
},
"Version": "string",
"VpcConfig": {
"SecurityGroupIds": [ "string" ],
"SubnetIds": [ "string" ],
"VpcId": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
CodeSha256 (p. 398)
The SHA256 hash of the function's deployment package.
Type: String
CodeSize (p. 398)
The size of the function's deployment package in bytes.
Type: Long
DeadLetterConﬁg (p. 398)
The function's dead letter queue.
Type: DeadLetterConﬁg (p. 486) object
Description (p. 398)
The function's description.

399

AWS Lambda Developer Guide
GetFunctionConﬁguration

Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Environment (p. 398)
The function's environment variables.
Type: EnvironmentResponse (p. 489) object
FunctionArn (p. 398)
The function's Amazon Resource Name (ARN).
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_\.]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
FunctionName (p. 398)
The name of the function.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Handler (p. 398)
The function Lambda calls to begin executing your function.
Type: String
Length Constraints: Maximum length of 128.
Pattern: [^\s]+
KMSKeyArn (p. 398)
The KMS key used to encrypt the function's environment variables. Only returned if you've
conﬁgured a customer managed CMK.
Type: String
Pattern: (arn:(aws[a-zA-Z-]*)?:[a-z0-9-.]+:.*)|()
LastModiﬁed (p. 398)
The date and time that the function was last updated, in ISO-8601 format (YYYY-MMDDThh:mm:ss.sTZD).
Type: String
Layers (p. 398)
The function's layers
Type: Array of Layer (p. 498) objects
MasterArn (p. 398)
For Lambda@Edge functions, the ARN of the master function.

400

AWS Lambda Developer Guide
GetFunctionConﬁguration

Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
MemorySize (p. 398)
The memory allocated to the function
Type: Integer
Valid Range: Minimum value of 128. Maximum value of 3008.
RevisionId (p. 398)
Represents the latest updated revision of the function or alias.
Type: String
Role (p. 398)
The function's execution role.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+
Runtime (p. 398)
The runtime environment for the Lambda function.
Type: String
Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided
Timeout (p. 398)
The amount of time that Lambda allows a function to run before terminating it.
Type: Integer
Valid Range: Minimum value of 1.
TracingConﬁg (p. 398)
The function's AWS X-Ray tracing conﬁguration.
Type: TracingConﬁgResponse (p. 505) object
Version (p. 398)
The version of the Lambda function.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
VpcConﬁg (p. 398)
The function's networking conﬁguration.
Type: VpcConﬁgResponse (p. 507) object

401

AWS Lambda Developer Guide
GetFunctionConﬁguration

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

402

AWS Lambda Developer Guide
GetLayerVersion

GetLayerVersion
Returns information about a version of an AWS Lambda layer, with a link to download the layer archive
that's valid for 10 minutes.

Request Syntax
GET /2018-10-31/layers/LayerName/versions/VersionNumber HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
LayerName (p. 403)
The name or Amazon Resource Name (ARN) of the layer.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+)|
[a-zA-Z0-9-_]+
VersionNumber (p. 403)
The version number.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

}

"CompatibleRuntimes": [ "string" ],
"Content": {
"CodeSha256": "string",
"CodeSize": number,
"Location": "string"
},
"CreatedDate": "string",
"Description": "string",
"LayerArn": "string",
"LayerVersionArn": "string",
"LicenseInfo": "string",
"Version": number

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.

403

AWS Lambda Developer Guide
GetLayerVersion

CompatibleRuntimes (p. 403)
The layer's compatible runtimes.
Type: Array of strings
Array Members: Maximum number of 5 items.
Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided
Content (p. 403)
Details about the layer version.
Type: LayerVersionContentOutput (p. 501) object
CreatedDate (p. 403)
The date that the layer version was created, in ISO-8601 format (YYYY-MM-DDThh:mm:ss.sTZD).
Type: String
Description (p. 403)
The description of the version.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
LayerArn (p. 403)
The ARN of the layer.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+
LayerVersionArn (p. 403)
The ARN of the layer version.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+:
[0-9]+
LicenseInfo (p. 403)
The layer's software license.
Type: String
Length Constraints: Maximum length of 512.
Version (p. 403)
The version number.
Type: Long

404

AWS Lambda Developer Guide
GetLayerVersion

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

405

AWS Lambda Developer Guide
GetLayerVersionPolicy

GetLayerVersionPolicy
Returns the permission policy for a version of an AWS Lambda layer. For more information, see
AddLayerVersionPermission (p. 352).

Request Syntax
GET /2018-10-31/layers/LayerName/versions/VersionNumber/policy HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
LayerName (p. 406)
The name or Amazon Resource Name (ARN) of the layer.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+)|
[a-zA-Z0-9-_]+
VersionNumber (p. 406)
The version number.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{
}

"Policy": "string",
"RevisionId": "string"

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
Policy (p. 406)
The policy document.
Type: String
RevisionId (p. 406)
A unique identiﬁer for the current revision of the policy.
Type: String

406

AWS Lambda Developer Guide
GetLayerVersionPolicy

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

407

AWS Lambda Developer Guide
GetPolicy

GetPolicy
Returns the resource-based IAM policy for a function, version, or alias.

Request Syntax
GET /2015-03-31/functions/FunctionName/policy?Qualifier=Qualifier HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 408)
The name of the Lambda function, version, or alias.

Name formats
• Function name - my-function (name-only), my-function:v1 (with alias).
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
You can append a version number or alias to any of the formats. The length constraint applies only
to the full ARN. If you specify only the function name, it is limited to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Qualiﬁer (p. 408)
Specify a version or alias to get the policy for that resource.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (|[a-zA-Z0-9$_-]+)

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{
}

"Policy": "string",
"RevisionId": "string"

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

408

AWS Lambda Developer Guide
GetPolicy

The following data is returned in JSON format by the service.
Policy (p. 408)
The resource-based policy.
Type: String
RevisionId (p. 408)
A unique identiﬁer for the current revision of the policy.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
•
•
•
•

AWS SDK for .NET
AWS SDK for C++
AWS SDK for Go
AWS SDK for Java

•
•
•
•

AWS SDK for JavaScript
AWS SDK for PHP V3
AWS SDK for Python
AWS SDK for Ruby V2

409

AWS Lambda Developer Guide
Invoke

Invoke
Invokes a Lambda function. You can invoke a function synchronously and wait for the response, or
asynchronously. To invoke a function asynchronously, set InvocationType to Event.
For synchronous invocation, details about the function response, including errors, are included in the
response body and headers. For either invocation type, you can ﬁnd more information in the execution
log and trace. To record function errors for asynchronous invocations, conﬁgure your function with a
dead letter queue.
The status code in the API response does not reﬂect function errors. Error codes are reserved
for errors that prevent your function from executing, such as permissions errors, limit
errors, or issues with your function's code and conﬁguration. For example, Lambda returns
TooManyRequestsException if executing the function would cause you to exceed a concurrency
limit at either the account level (ConcurrentInvocationLimitExceeded) or function level
(ReservedFunctionConcurrentInvocationLimitExceeded).
For functions with a long timeout, your client may be disconnected during synchronous invocation while
it waits for a response. Conﬁgure your HTTP client, SDK, ﬁrewall, proxy, or operating system to allow for
long connections with timeout or keep-alive settings.
This operation requires permission for the lambda:InvokeFunction action.

Request Syntax
POST /2015-03-31/functions/FunctionName/invocations?Qualifier=Qualifier HTTP/1.1
X-Amz-Invocation-Type: InvocationType
X-Amz-Log-Type: LogType
X-Amz-Client-Context: ClientContext
Payload

URI Request Parameters
The request requires the following URI parameters.
ClientContext (p. 410)
Up to 3583 bytes of base64-encoded data about the invoking client to pass to the function in the
context object.
FunctionName (p. 410)
The name of the Lambda function, version, or alias.

Name formats
• Function name - my-function (name-only), my-function:v1 (with alias).
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
You can append a version number or alias to any of the formats. The length constraint applies only
to the full ARN. If you specify only the function name, it is limited to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

410

AWS Lambda Developer Guide
Invoke

InvocationType (p. 410)
Choose from the following options.
• RequestResponse (default) - Invoke the function synchronously. Keep the connection open until
the function returns a response or times out. The API response includes the function response and
additional data.
• Event - Invoke the function asynchronously. Send events that fail multiple times to the function's
dead-letter queue (if conﬁgured). The API response only includes a status code.
• DryRun - Validate parameter values and verify that the user or role has permission to invoke the
function.
Valid Values: Event | RequestResponse | DryRun
LogType (p. 410)
Set to Tail to include the execution log in the response.
Valid Values: None | Tail
Qualiﬁer (p. 410)
Specify a version or alias to invoke a published version of the function.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (|[a-zA-Z0-9$_-]+)

Request Body
The request accepts the following binary data.
Payload (p. 410)
JSON that you want to provide to your Lambda function as input.

Response Syntax
HTTP/1.1 StatusCode
X-Amz-Function-Error: FunctionError
X-Amz-Log-Result: LogResult
X-Amz-Executed-Version: ExecutedVersion
Payload

Response Elements
If the action is successful, the service sends back the following HTTP response.
StatusCode (p. 411)
The HTTP status code will be in the 200 range for successful request. For the RequestResponse
invocation type this status code will be 200. For the Event invocation type this status code will be
202. For the DryRun invocation type the status code will be 204.
The response returns the following HTTP headers.

411

AWS Lambda Developer Guide
Invoke

ExecutedVersion (p. 411)
The version of the function that executed. When you invoke a function with an alias, indicates which
version the alias resolved to.
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
FunctionError (p. 411)
If present, indicates that an error occured during function execution. Details about the error are
included in the response payload.
• Handled - The runtime caught an error thrown by the function and formatted it into a JSON
document.
• Unhandled - The runtime did not handle the error. For example, the function ran out of memory
or timed out.
LogResult (p. 411)
The last 4 KB of the execution log, base64 encoded.
The response returns the following as the HTTP body.
Payload (p. 411)
The response from the function, or an error object.

Errors
EC2AccessDeniedException
Need additional permissions to conﬁgure VPC settings.
HTTP Status Code: 502
EC2ThrottledException
AWS Lambda was throttled by Amazon EC2 during Lambda function initialization using the
execution role provided for the Lambda function.
HTTP Status Code: 502
EC2UnexpectedException
AWS Lambda received an unexpected EC2 client exception while setting up for the Lambda function.
HTTP Status Code: 502
ENILimitReachedException
AWS Lambda was not able to create an Elastic Network Interface (ENI) in the VPC, speciﬁed as part
of Lambda function conﬁguration, because the limit for network interfaces has been reached.
HTTP Status Code: 502
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400

412

AWS Lambda Developer Guide
Invoke

InvalidRequestContentException
The request body could not be parsed as JSON.
HTTP Status Code: 400
InvalidRuntimeException
The runtime or runtime version speciﬁed is not supported.
HTTP Status Code: 502
InvalidSecurityGroupIDException
The Security Group ID provided in the Lambda function VPC conﬁguration is invalid.
HTTP Status Code: 502
InvalidSubnetIDException
The Subnet ID provided in the Lambda function VPC conﬁguration is invalid.
HTTP Status Code: 502
InvalidZipFileException
AWS Lambda could not unzip the deployment package.
HTTP Status Code: 502
KMSAccessDeniedException
Lambda was unable to decrypt the environment variables because KMS access was denied. Check the
Lambda function's KMS permissions.
HTTP Status Code: 502
KMSDisabledException
Lambda was unable to decrypt the environment variables because the KMS key used is disabled.
Check the Lambda function's KMS key settings.
HTTP Status Code: 502
KMSInvalidStateException
Lambda was unable to decrypt the environment variables because the KMS key used is in an invalid
state for Decrypt. Check the function's KMS key settings.
HTTP Status Code: 502
KMSNotFoundException
Lambda was unable to decrypt the environment variables because the KMS key was not found.
Check the function's KMS key settings.
HTTP Status Code: 502
RequestTooLargeException
The request payload exceeded the Invoke request body JSON input limit. For more information, see
Limits.
HTTP Status Code: 413
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.

413

AWS Lambda Developer Guide
Invoke

HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
SubnetIPAddressLimitReachedException
AWS Lambda was not able to set up VPC access for the Lambda function because one or more
conﬁgured subnets has no available IP addresses.
HTTP Status Code: 502
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429
UnsupportedMediaTypeException
The content type of the Invoke request body is not JSON.
HTTP Status Code: 415

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

414

AWS Lambda Developer Guide
InvokeAsync

InvokeAsync
This action has been deprecated.

Important

For asynchronous function invocation, use Invoke (p. 410).
Invokes a function asynchronously.

Request Syntax
POST /2014-11-13/functions/FunctionName/invoke-async/ HTTP/1.1
InvokeArgs

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 415)
The name of the Lambda function.

Name formats
• Function name - my-function.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

Request Body
The request accepts the following binary data.
InvokeArgs (p. 415)
JSON that you want to provide to your Lambda function as input.

Response Syntax
HTTP/1.1 Status

Response Elements
If the action is successful, the service sends back the following HTTP response.

415

AWS Lambda Developer Guide
InvokeAsync

Status (p. 415)
It will be 202 upon success.

Errors
InvalidRequestContentException
The request body could not be parsed as JSON.
HTTP Status Code: 400
InvalidRuntimeException
The runtime or runtime version speciﬁed is not supported.
HTTP Status Code: 502
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

416

AWS Lambda Developer Guide
ListAliases

ListAliases
Returns a list of aliases for a Lambda function.

Request Syntax
GET /2015-03-31/functions/FunctionName/aliases?
FunctionVersion=FunctionVersion&Marker=Marker&MaxItems=MaxItems HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 417)
The name of the lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
FunctionVersion (p. 417)
Specify a function version to only list aliases that invoke that version.
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
Marker (p. 417)
Specify the pagination token returned by a previous request to retrieve the next page of results.
MaxItems (p. 417)
Limit the number of aliases returned.
Valid Range: Minimum value of 1. Maximum value of 10000.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

417

AWS Lambda Developer Guide
ListAliases

{

}

"Aliases": [
{
"AliasArn": "string",
"Description": "string",
"FunctionVersion": "string",
"Name": "string",
"RevisionId": "string",
"RoutingConfig": {
"AdditionalVersionWeights": {
"string" : number
}
}
}
],
"NextMarker": "string"

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
Aliases (p. 417)
A list of aliases.
Type: Array of AliasConﬁguration (p. 482) objects
NextMarker (p. 417)
Pagination token included if more results are available.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.

418

AWS Lambda Developer Guide
ListAliases

HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

419

AWS Lambda Developer Guide
ListEventSourceMappings

ListEventSourceMappings
Lists event source mappings. Specify an EventSourceArn to only show event source mappings for a
single event source.

Request Syntax
GET /2015-03-31/event-source-mappings/?
EventSourceArn=EventSourceArn&FunctionName=FunctionName&Marker=Marker&MaxItems=MaxItems
HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
EventSourceArn (p. 420)
The Amazon Resource Name (ARN) of the event source.
• Amazon Kinesis - The ARN of the data stream or a stream consumer.
• Amazon DynamoDB Streams - The ARN of the stream.
• Amazon Simple Queue Service - The ARN of the queue.
Pattern: arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+\d{1})?:(\d{12})?:(.*)
FunctionName (p. 420)
The name of the Lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Version or Alias ARN - arn:aws:lambda:uswest-2:123456789012:function:MyFunction:PROD.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it's limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Marker (p. 420)
A pagination token returned by a previous call.
MaxItems (p. 420)
The maximum number of event source mappings to return.
Valid Range: Minimum value of 1. Maximum value of 10000.

Request Body
The request does not have a request body.

420

AWS Lambda Developer Guide
ListEventSourceMappings

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

}

"EventSourceMappings": [
{
"BatchSize": number,
"EventSourceArn": "string",
"FunctionArn": "string",
"LastModified": number,
"LastProcessingResult": "string",
"State": "string",
"StateTransitionReason": "string",
"UUID": "string"
}
],
"NextMarker": "string"

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
EventSourceMappings (p. 421)
A list of event source mappings.
Type: Array of EventSourceMappingConﬁguration (p. 490) objects
NextMarker (p. 421)
A pagination token that's returned when the response doesn't contain all event source mappings.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500

421

AWS Lambda Developer Guide
ListEventSourceMappings

TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

422

AWS Lambda Developer Guide
ListFunctions

ListFunctions
Returns a list of Lambda functions, with the version-speciﬁc conﬁguration of each.
Set FunctionVersion to ALL to include all published versions of each function in addition to the
unpublished version. To get more information about a function or version, use GetFunction (p. 395).

Request Syntax
GET /2015-03-31/functions/?
FunctionVersion=FunctionVersion&Marker=Marker&MasterRegion=MasterRegion&MaxItems=MaxItems
HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionVersion (p. 423)
Set to ALL to include entries for all published versions of each function.
Valid Values: ALL
Marker (p. 423)
Specify the pagination token returned by a previous request to retrieve the next page of results.
MasterRegion (p. 423)
For Lambda@Edge functions, the region of the master function. For example, us-east-2 or ALL. If
speciﬁed, you must set FunctionVersion to ALL.
Pattern: ALL|[a-z]{2}(-gov)?-[a-z]+-\d{1}
MaxItems (p. 423)
Specify a value between 1 and 50 to limit the number of functions in the response.
Valid Range: Minimum value of 1. Maximum value of 10000.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

"Functions": [
{
"CodeSha256": "string",
"CodeSize": number,
"DeadLetterConfig": {
"TargetArn": "string"
},
"Description": "string",
"Environment": {
"Error": {

423

AWS Lambda Developer Guide
ListFunctions
"ErrorCode": "string",
"Message": "string"

},
"Variables": {
"string" : "string"
}

},
"FunctionArn": "string",
"FunctionName": "string",
"Handler": "string",
"KMSKeyArn": "string",
"LastModified": "string",
"Layers": [
{
"Arn": "string",
"CodeSize": number
}
],
"MasterArn": "string",
"MemorySize": number,
"RevisionId": "string",
"Role": "string",
"Runtime": "string",
"Timeout": number,
"TracingConfig": {
"Mode": "string"
},
"Version": "string",
"VpcConfig": {
"SecurityGroupIds": [ "string" ],
"SubnetIds": [ "string" ],
"VpcId": "string"
}

}

}
],
"NextMarker": "string"

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
Functions (p. 423)
A list of Lambda functions.
Type: Array of FunctionConﬁguration (p. 494) objects
NextMarker (p. 423)
Pagination token included if more results are available.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.

424

AWS Lambda Developer Guide
ListFunctions

HTTP Status Code: 400
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

425

AWS Lambda Developer Guide
ListLayers

ListLayers
Lists AWS Lambda layers and shows information about the latest version of each. Specify a runtime
identiﬁer to list only layers that indicate that they're compatible with that runtime.

Request Syntax
GET /2018-10-31/layers?CompatibleRuntime=CompatibleRuntime&Marker=Marker&MaxItems=MaxItems
HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
CompatibleRuntime (p. 426)
A runtime identiﬁer. For example, go1.x.
Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided
Marker (p. 426)
A pagination token returned by a previous call.
MaxItems (p. 426)
The maximum number of layers to return.
Valid Range: Minimum value of 1. Maximum value of 50.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

}

"Layers": [
{
"LatestMatchingVersion": {
"CompatibleRuntimes": [ "string" ],
"CreatedDate": "string",
"Description": "string",
"LayerVersionArn": "string",
"LicenseInfo": "string",
"Version": number
},
"LayerArn": "string",
"LayerName": "string"
}
],
"NextMarker": "string"

426

AWS Lambda Developer Guide
ListLayers

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
Layers (p. 426)
A list of function layers.
Type: Array of LayersListItem (p. 499) objects
NextMarker (p. 426)
A pagination token returned when the response doesn't contain all layers.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
•
•
•
•
•

AWS SDK for Java
AWS SDK for JavaScript
AWS SDK for PHP V3
AWS SDK for Python
AWS SDK for Ruby V2

427

AWS Lambda Developer Guide
ListLayerVersions

ListLayerVersions
Lists the versions of an AWS Lambda layer. Versions that have been deleted aren't listed. Specify a
runtime identiﬁer to list only versions that indicate that they're compatible with that runtime.

Request Syntax
GET /2018-10-31/layers/LayerName/versions?
CompatibleRuntime=CompatibleRuntime&Marker=Marker&MaxItems=MaxItems HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
CompatibleRuntime (p. 428)
A runtime identiﬁer. For example, go1.x.
Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided
LayerName (p. 428)
The name or Amazon Resource Name (ARN) of the layer.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+)|
[a-zA-Z0-9-_]+
Marker (p. 428)
A pagination token returned by a previous call.
MaxItems (p. 428)
The maximum number of versions to return.
Valid Range: Minimum value of 1. Maximum value of 50.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

"LayerVersions": [
{
"CompatibleRuntimes": [ "string" ],
"CreatedDate": "string",
"Description": "string",
"LayerVersionArn": "string",
"LicenseInfo": "string",

428

AWS Lambda Developer Guide
ListLayerVersions

}

}

"Version": number

],
"NextMarker": "string"

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
LayerVersions (p. 428)
A list of versions.
Type: Array of LayerVersionsListItem (p. 502) objects
NextMarker (p. 428)
A pagination token returned when the response doesn't contain all versions.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++

429

AWS Lambda Developer Guide
ListLayerVersions

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

430

AWS Lambda Developer Guide
ListTags

ListTags
Returns a function's tags. You can also view tags with GetFunction (p. 395).

Request Syntax
GET /2017-03-31/tags/ARN HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
Resource (p. 431)
The function's Amazon Resource Name (ARN).
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

}

"Tags": {
"string" : "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
Tags (p. 431)
The function's tags.
Type: String to string map

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.

431

AWS Lambda Developer Guide
ListTags

HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

432

AWS Lambda Developer Guide
ListVersionsByFunction

ListVersionsByFunction
Returns a list of versions, with the version-speciﬁc conﬁguration of each.

Request Syntax
GET /2015-03-31/functions/FunctionName/versions?Marker=Marker&MaxItems=MaxItems HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 433)
The name of the lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Marker (p. 433)
Specify the pagination token returned by a previous request to retrieve the next page of results.
MaxItems (p. 433)
Limit the number of versions returned.
Valid Range: Minimum value of 1. Maximum value of 10000.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

"NextMarker": "string",
"Versions": [
{
"CodeSha256": "string",
"CodeSize": number,
"DeadLetterConfig": {
"TargetArn": "string"
},
"Description": "string",
"Environment": {

433

AWS Lambda Developer Guide
ListVersionsByFunction
"Error": {
"ErrorCode": "string",
"Message": "string"
},
"Variables": {
"string" : "string"
}

}

]

}

},
"FunctionArn": "string",
"FunctionName": "string",
"Handler": "string",
"KMSKeyArn": "string",
"LastModified": "string",
"Layers": [
{
"Arn": "string",
"CodeSize": number
}
],
"MasterArn": "string",
"MemorySize": number,
"RevisionId": "string",
"Role": "string",
"Runtime": "string",
"Timeout": number,
"TracingConfig": {
"Mode": "string"
},
"Version": "string",
"VpcConfig": {
"SecurityGroupIds": [ "string" ],
"SubnetIds": [ "string" ],
"VpcId": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
NextMarker (p. 433)
Pagination token included if more results are available.
Type: String
Versions (p. 433)
A list of Lambda function versions.
Type: Array of FunctionConﬁguration (p. 494) objects

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.

434

AWS Lambda Developer Guide
ListVersionsByFunction

HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

435

AWS Lambda Developer Guide
PublishLayerVersion

PublishLayerVersion
Creates an AWS Lambda layer from a ZIP archive. Each time you call PublishLayerVersion with the
same version name, a new version is created.
Add layers to your function with CreateFunction (p. 368) or UpdateFunctionConﬁguration (p. 472).

Request Syntax
POST /2018-10-31/layers/LayerName/versions HTTP/1.1
Content-type: application/json
{

}

"CompatibleRuntimes": [ "string" ],
"Content": {
"S3Bucket": "string",
"S3Key": "string",
"S3ObjectVersion": "string",
"ZipFile": blob
},
"Description": "string",
"LicenseInfo": "string"

URI Request Parameters
The request requires the following URI parameters.
LayerName (p. 436)
The name or Amazon Resource Name (ARN) of the layer.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+)|
[a-zA-Z0-9-_]+

Request Body
The request accepts the following data in JSON format.
CompatibleRuntimes (p. 436)
A list of compatible function runtimes. Used for ﬁltering with ListLayers (p. 426) and
ListLayerVersions (p. 428).
Type: Array of strings
Array Members: Maximum number of 5 items.
Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided
Required: No
Content (p. 436)
The function layer archive.

436

AWS Lambda Developer Guide
PublishLayerVersion

Type: LayerVersionContentInput (p. 500) object
Required: Yes
Description (p. 436)
The description of the version.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Required: No
LicenseInfo (p. 436)
The layer's software license. It can be any of the following:
• An SPDX license identiﬁer. For example, MIT.
• The URL of a license hosted on the internet. For example, https://opensource.org/
licenses/MIT.
• The full text of the license.
Type: String
Length Constraints: Maximum length of 512.
Required: No

Response Syntax
HTTP/1.1 201
Content-type: application/json
{

}

"CompatibleRuntimes": [ "string" ],
"Content": {
"CodeSha256": "string",
"CodeSize": number,
"Location": "string"
},
"CreatedDate": "string",
"Description": "string",
"LayerArn": "string",
"LayerVersionArn": "string",
"LicenseInfo": "string",
"Version": number

Response Elements
If the action is successful, the service sends back an HTTP 201 response.
The following data is returned in JSON format by the service.
CompatibleRuntimes (p. 437)
The layer's compatible runtimes.
Type: Array of strings
Array Members: Maximum number of 5 items.

437

AWS Lambda Developer Guide
PublishLayerVersion

Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided
Content (p. 437)
Details about the layer version.
Type: LayerVersionContentOutput (p. 501) object
CreatedDate (p. 437)
The date that the layer version was created, in ISO-8601 format (YYYY-MM-DDThh:mm:ss.sTZD).
Type: String
Description (p. 437)
The description of the version.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
LayerArn (p. 437)
The ARN of the layer.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+
LayerVersionArn (p. 437)
The ARN of the layer version.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+:
[0-9]+
LicenseInfo (p. 437)
The layer's software license.
Type: String
Length Constraints: Maximum length of 512.
Version (p. 437)
The version number.
Type: Long

Errors
CodeStorageExceededException
You have exceeded your maximum total code size per account. Limits

438

AWS Lambda Developer Guide
PublishLayerVersion

HTTP Status Code: 400
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

439

AWS Lambda Developer Guide
PublishVersion

PublishVersion
Creates a version from the current code and conﬁguration of a function. Use versions to create a
snapshot of your function code and conﬁguration that doesn't change.
AWS Lambda does not publish a version if the function's conﬁguration and code hasn't changed since the
last version. Use UpdateFunctionCode (p. 466) or UpdateFunctionConﬁguration (p. 472) to update
the function prior to publishing a version.
Clients can invoke versions directly or with an alias. To create an alias, use CreateAlias (p. 360).

Request Syntax
POST /2015-03-31/functions/FunctionName/versions HTTP/1.1
Content-type: application/json
{

}

"CodeSha256": "string",
"Description": "string",
"RevisionId": "string"

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 440)
The name of the lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

Request Body
The request accepts the following data in JSON format.
CodeSha256 (p. 440)
Only publish a version if the hash matches the value speciﬁed. Use this option to avoid publishing
a version if the function code has changed since you last updated it. You can get the hash for the
version you uploaded from the output of UpdateFunctionCode (p. 466).
Type: String
Required: No

440

AWS Lambda Developer Guide
PublishVersion

Description (p. 440)
Specify a description for the version to override the description in the function conﬁguration.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Required: No
RevisionId (p. 440)
Only update the function if the revision ID matches the ID speciﬁed. Use this option to avoid
publishing a version if the function conﬁguration has changed since you last updated it.
Type: String
Required: No

Response Syntax
HTTP/1.1 201
Content-type: application/json
{

"CodeSha256": "string",
"CodeSize": number,
"DeadLetterConfig": {
"TargetArn": "string"
},
"Description": "string",
"Environment": {
"Error": {
"ErrorCode": "string",
"Message": "string"
},
"Variables": {
"string" : "string"
}
},
"FunctionArn": "string",
"FunctionName": "string",
"Handler": "string",
"KMSKeyArn": "string",
"LastModified": "string",
"Layers": [
{
"Arn": "string",
"CodeSize": number
}
],
"MasterArn": "string",
"MemorySize": number,
"RevisionId": "string",
"Role": "string",
"Runtime": "string",
"Timeout": number,
"TracingConfig": {
"Mode": "string"
},
"Version": "string",
"VpcConfig": {
"SecurityGroupIds": [ "string" ],

441

AWS Lambda Developer Guide
PublishVersion

}

}

"SubnetIds": [ "string" ],
"VpcId": "string"

Response Elements
If the action is successful, the service sends back an HTTP 201 response.
The following data is returned in JSON format by the service.
CodeSha256 (p. 441)
The SHA256 hash of the function's deployment package.
Type: String
CodeSize (p. 441)
The size of the function's deployment package in bytes.
Type: Long
DeadLetterConﬁg (p. 441)
The function's dead letter queue.
Type: DeadLetterConﬁg (p. 486) object
Description (p. 441)
The function's description.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Environment (p. 441)
The function's environment variables.
Type: EnvironmentResponse (p. 489) object
FunctionArn (p. 441)
The function's Amazon Resource Name (ARN).
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_\.]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
FunctionName (p. 441)
The name of the function.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 170.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_\.]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Handler (p. 441)
The function Lambda calls to begin executing your function.

442

AWS Lambda Developer Guide
PublishVersion

Type: String
Length Constraints: Maximum length of 128.
Pattern: [^\s]+
KMSKeyArn (p. 441)
The KMS key used to encrypt the function's environment variables. Only returned if you've
conﬁgured a customer managed CMK.
Type: String
Pattern: (arn:(aws[a-zA-Z-]*)?:[a-z0-9-.]+:.*)|()
LastModiﬁed (p. 441)
The date and time that the function was last updated, in ISO-8601 format (YYYY-MMDDThh:mm:ss.sTZD).
Type: String
Layers (p. 441)
The function's layers
Type: Array of Layer (p. 498) objects
MasterArn (p. 441)
For Lambda@Edge functions, the ARN of the master function.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
MemorySize (p. 441)
The memory allocated to the function
Type: Integer
Valid Range: Minimum value of 128. Maximum value of 3008.
RevisionId (p. 441)
Represents the latest updated revision of the function or alias.
Type: String
Role (p. 441)
The function's execution role.
Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+
Runtime (p. 441)
The runtime environment for the Lambda function.
Type: String
Valid Values: nodejs | nodejs4.3 | nodejs6.10 | nodejs8.10 | java8 | python2.7
| python3.6 | python3.7 | dotnetcore1.0 | dotnetcore2.0 | dotnetcore2.1 |
nodejs4.3-edge | go1.x | ruby2.5 | provided

443

AWS Lambda Developer Guide
PublishVersion

Timeout (p. 441)
The amount of time that Lambda allows a function to run before terminating it.
Type: Integer
Valid Range: Minimum value of 1.
TracingConﬁg (p. 441)
The function's AWS X-Ray tracing conﬁguration.
Type: TracingConﬁgResponse (p. 505) object
Version (p. 441)
The version of the Lambda function.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
VpcConﬁg (p. 441)
The function's networking conﬁguration.
Type: VpcConﬁgResponse (p. 507) object

Errors
CodeStorageExceededException
You have exceeded your maximum total code size per account. Limits
HTTP Status Code: 400
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
PreconditionFailedException
The RevisionId provided does not match the latest RevisionId for the Lambda function or alias. Call
the GetFunction or the GetAlias API to retrieve the latest RevisionId for your resource.
HTTP Status Code: 412
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500

444

AWS Lambda Developer Guide
PublishVersion

TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

445

AWS Lambda Developer Guide
PutFunctionConcurrency

PutFunctionConcurrency
Sets the maximum number of simultaneous executions for a function, and reserves capacity for that
concurrency level.
Concurrency settings apply to the function as a whole, including all published versions and the
unpublished version. Reserving concurrency both guarantees that your function has capacity to process
the speciﬁed number of events simultaneously, and prevents it from scaling beyond that level. Use
GetFunction (p. 395) to see the current setting for a function.
Use GetAccountSettings (p. 387) to see your regional concurrency limit. You can reserve concurrency
for as many functions as you like, as long as you leave at least 100 simultaneous executions unreserved
for functions that aren't conﬁgured with a per-function limit. For more information, see Managing
Concurrency.

Request Syntax
PUT /2017-10-31/functions/FunctionName/concurrency HTTP/1.1
Content-type: application/json
{
}

"ReservedConcurrentExecutions": number

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 446)
The name of the Lambda function.

Name formats
• Function name - my-function.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

Request Body
The request accepts the following data in JSON format.
ReservedConcurrentExecutions (p. 446)
The number of simultaneous executions to reserve for the function.
Type: Integer
Valid Range: Minimum value of 0.

446

AWS Lambda Developer Guide
PutFunctionConcurrency

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json
{
}

"ReservedConcurrentExecutions": number

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
ReservedConcurrentExecutions (p. 447)
The number of concurrent executions reserved for this function. For more information, see
Managing Concurrency.
Type: Integer
Valid Range: Minimum value of 0.

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

447

AWS Lambda Developer Guide
PutFunctionConcurrency

• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

448

AWS Lambda Developer Guide
RemoveLayerVersionPermission

RemoveLayerVersionPermission
Removes a statement from the permissions policy for a version of an AWS Lambda layer. For more
information, see AddLayerVersionPermission (p. 352).

Request Syntax
DELETE /2018-10-31/layers/LayerName/versions/VersionNumber/policy/StatementId?
RevisionId=RevisionId HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
LayerName (p. 449)
The name or Amazon Resource Name (ARN) of the layer.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:[a-zA-Z0-9-]+:lambda:[a-zA-Z0-9-]+:\d{12}:layer:[a-zA-Z0-9-_]+)|
[a-zA-Z0-9-_]+
RevisionId (p. 449)
Only update the policy if the revision ID matches the ID speciﬁed. Use this option to avoid modifying
a policy that has changed since you last read it.
StatementId (p. 449)
The identiﬁer that was speciﬁed when the statement was added.
Length Constraints: Minimum length of 1. Maximum length of 100.
Pattern: ([a-zA-Z0-9-_]+)
VersionNumber (p. 449)
The version number.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.

449

AWS Lambda Developer Guide
RemoveLayerVersionPermission

HTTP Status Code: 400
PreconditionFailedException
The RevisionId provided does not match the latest RevisionId for the Lambda function or alias. Call
the GetFunction or the GetAlias API to retrieve the latest RevisionId for your resource.
HTTP Status Code: 412
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

450

AWS Lambda Developer Guide
RemovePermission

RemovePermission
Revokes function use permission from an AWS service or another account. You can get the ID of the
statement from the output of GetPolicy (p. 408).

Request Syntax
DELETE /2015-03-31/functions/FunctionName/policy/StatementId?
Qualifier=Qualifier&RevisionId=RevisionId HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 451)
The name of the Lambda function, version, or alias.

Name formats
• Function name - my-function (name-only), my-function:v1 (with alias).
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
You can append a version number or alias to any of the formats. The length constraint applies only
to the full ARN. If you specify only the function name, it is limited to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Qualiﬁer (p. 451)
Specify a version or alias to remove permissions from a published version of the function.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (|[a-zA-Z0-9$_-]+)
RevisionId (p. 451)
Only update the policy if the revision ID matches the ID speciﬁed. Use this option to avoid modifying
a policy that has changed since you last read it.
StatementId (p. 451)
Statement ID of the permission to remove.
Length Constraints: Minimum length of 1. Maximum length of 100.
Pattern: ([a-zA-Z0-9-_.]+)

Request Body
The request does not have a request body.

451

AWS Lambda Developer Guide
RemovePermission

Response Syntax
HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
PreconditionFailedException
The RevisionId provided does not match the latest RevisionId for the Lambda function or alias. Call
the GetFunction or the GetAlias API to retrieve the latest RevisionId for your resource.
HTTP Status Code: 412
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

452

AWS Lambda Developer Guide
RemovePermission

453

AWS Lambda Developer Guide
TagResource

TagResource
Adds tags to a function.

Request Syntax
POST /2017-03-31/tags/ARN HTTP/1.1
Content-type: application/json
{

}

"Tags": {
"string" : "string"
}

URI Request Parameters
The request requires the following URI parameters.
Resource (p. 454)
The function's Amazon Resource Name (ARN).
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?

Request Body
The request accepts the following data in JSON format.
Tags (p. 454)
A list of tags to apply to the function.
Type: String to string map
Required: Yes

Response Syntax
HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.

454

AWS Lambda Developer Guide
TagResource

HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

455

AWS Lambda Developer Guide
UntagResource

UntagResource
Removes tags from a function.

Request Syntax
DELETE /2017-03-31/tags/ARN?tagKeys=TagKeys HTTP/1.1

URI Request Parameters
The request requires the following URI parameters.
Resource (p. 456)
The function's Amazon Resource Name (ARN).
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
TagKeys (p. 456)
A list of tag keys to remove from the function.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.

456

AWS Lambda Developer Guide
UntagResource

HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

457

AWS Lambda Developer Guide
UpdateAlias

UpdateAlias
Updates the conﬁguration of a Lambda function alias.

Request Syntax
PUT /2015-03-31/functions/FunctionName/aliases/Name HTTP/1.1
Content-type: application/json
{

}

"Description": "string",
"FunctionVersion": "string",
"RevisionId": "string",
"RoutingConfig": {
"AdditionalVersionWeights": {
"string" : number
}
}

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 458)
The name of the lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Name (p. 458)
The name of the alias.
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (?!^[0-9]+$)([a-zA-Z0-9-_]+)

Request Body
The request accepts the following data in JSON format.
Description (p. 458)
A description of the alias.

458

AWS Lambda Developer Guide
UpdateAlias

Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Required: No
FunctionVersion (p. 458)
The function version that the alias invokes.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
Required: No
RevisionId (p. 458)
Only update the alias if the revision ID matches the ID speciﬁed. Use this option to avoid modifying
an alias that has changed since you last read it.
Type: String
Required: No
RoutingConﬁg (p. 458)
The routing conﬁguration of the alias.
Type: AliasRoutingConﬁguration (p. 484) object
Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json
{

}

"AliasArn": "string",
"Description": "string",
"FunctionVersion": "string",
"Name": "string",
"RevisionId": "string",
"RoutingConfig": {
"AdditionalVersionWeights": {
"string" : number
}
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
AliasArn (p. 459)
The Amazon Resource Name (ARN) of the alias.

459

AWS Lambda Developer Guide
UpdateAlias

Type: String
Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
Description (p. 459)
A description of the alias.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
FunctionVersion (p. 459)
The function version that the alias invokes.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern: (\$LATEST|[0-9]+)
Name (p. 459)
The name of the alias.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: (?!^[0-9]+$)([a-zA-Z0-9-_]+)
RevisionId (p. 459)
A unique identiﬁer that changes when you update the alias.
Type: String
RoutingConﬁg (p. 459)
The routing conﬁguration of the alias.
Type: AliasRoutingConﬁguration (p. 484) object

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
PreconditionFailedException
The RevisionId provided does not match the latest RevisionId for the Lambda function or alias. Call
the GetFunction or the GetAlias API to retrieve the latest RevisionId for your resource.
HTTP Status Code: 412
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.

460

AWS Lambda Developer Guide
UpdateAlias

HTTP Status Code: 404
ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

461

AWS Lambda Developer Guide
UpdateEventSourceMapping

UpdateEventSourceMapping
Updates an event source mapping. You can change the function that AWS Lambda invokes, or pause
invocation and resume later from the same location.

Request Syntax
PUT /2015-03-31/event-source-mappings/UUID HTTP/1.1
Content-type: application/json
{

}

"BatchSize": number,
"Enabled": boolean,
"FunctionName": "string"

URI Request Parameters
The request requires the following URI parameters.
UUID (p. 462)
The identiﬁer of the event source mapping.

Request Body
The request accepts the following data in JSON format.
BatchSize (p. 462)
The maximum number of items to retrieve in a single batch.
• Amazon Kinesis - Default 100. Max 10,000.
• Amazon DynamoDB Streams - Default 100. Max 1,000.
• Amazon Simple Queue Service - Default 10. Max 10.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10000.
Required: No
Enabled (p. 462)
Disables the event source mapping to pause polling and invocation.
Type: Boolean
Required: No
FunctionName (p. 462)
The name of the Lambda function.

Name formats
• Function name - MyFunction.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:MyFunction.

462

AWS Lambda Developer Guide
UpdateEventSourceMapping

• Version or Alias ARN - arn:aws:lambda:uswest-2:123456789012:function:MyFunction:PROD.
• Partial ARN - 123456789012:function:MyFunction.
The length constraint applies only to the full ARN. If you specify only the function name, it's limited
to 64 characters in length.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Required: No

Response Syntax
HTTP/1.1 202
Content-type: application/json
{

}

"BatchSize": number,
"EventSourceArn": "string",
"FunctionArn": "string",
"LastModified": number,
"LastProcessingResult": "string",
"State": "string",
"StateTransitionReason": "string",
"UUID": "string"

Response Elements
If the action is successful, the service sends back an HTTP 202 response.
The following data is returned in JSON format by the service.
BatchSize (p. 463)
The maximum number of items to retrieve in a single batch.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10000.
EventSourceArn (p. 463)
The Amazon Resource Name (ARN) of the event source.
Type: String
Pattern: arn:(aws[a-zA-Z0-9-]*):([a-zA-Z0-9\-])+:([a-z]{2}(-gov)?-[a-z]+\d{1})?:(\d{12})?:(.*)
FunctionArn (p. 463)
The ARN of the Lambda function.
Type: String

463

AWS Lambda Developer Guide
UpdateEventSourceMapping

Pattern: arn:(aws[a-zA-Z-]*)?:lambda:[a-z]{2}(-gov)?-[a-z]+-\d{1}:
\d{12}:function:[a-zA-Z0-9-_]+(:(\$LATEST|[a-zA-Z0-9-_]+))?
LastModiﬁed (p. 463)
The date that the event source mapping was last updated, in Unix time seconds.
Type: Timestamp
LastProcessingResult (p. 463)
The result of the last AWS Lambda invocation of your Lambda function.
Type: String
State (p. 463)
The state of the event source mapping. It can be one of the following: Creating, Enabling,
Enabled, Disabling, Disabled, Updating, or Deleting.
Type: String
StateTransitionReason (p. 463)
The cause of the last state change, either User initiated or Lambda initiated.
Type: String
UUID (p. 463)
The identiﬁer of the event source mapping.
Type: String

Errors
InvalidParameterValueException
One of the parameters in the request is invalid. For example, if you provided an IAM role for AWS
Lambda to assume in the CreateFunction or the UpdateFunctionConfiguration API, that
AWS Lambda is unable to assume you will get this exception.
HTTP Status Code: 400
ResourceConﬂictException
The resource already exists.
HTTP Status Code: 409
ResourceInUseException
The operation conﬂicts with the resource's availability. For example, you attempted to update
an EventSource Mapping in CREATING, or tried to delete a EventSource mapping currently in the
UPDATING state.
HTTP Status Code: 400
ResourceNotFoundException
The resource (for example, a Lambda function or access policy statement) speciﬁed in the request
does not exist.
HTTP Status Code: 404

464

AWS Lambda Developer Guide
UpdateEventSourceMapping

ServiceException
The AWS Lambda service encountered an internal error.
HTTP Status Code: 500
TooManyRequestsException
Request throughput limit exceeded.
HTTP Status Code: 429

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

465

AWS Lambda Developer Guide
UpdateFunctionCode

UpdateFunctionCode
Updates a Lambda function's code.
The function's code is locked when you publish a version. You cannot modify the code of a published
version, only the unpublished version.

Request Syntax
PUT /2015-03-31/functions/FunctionName/code HTTP/1.1
Content-type: application/json
{

}

"DryRun": boolean,
"Publish": boolean,
"RevisionId": "string",
"S3Bucket": "string",
"S3Key": "string",
"S3ObjectVersion": "string",
"ZipFile": blob

URI Request Parameters
The request requires the following URI parameters.
FunctionName (p. 466)
The name of the Lambda function.

Name formats
• Function name - my-function.
• Function ARN - arn:aws:lambda:us-west-2:123456789012:function:my-function.
• Partial ARN - 123456789012:function:my-function.
The length constraint applies only to the full ARN. If you specify only the function name, it is limited
to 64 characters in length.
Length Constraints: Minimum length of 1. Maximum length of 140.
Pattern: (arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?-[a-z]+-\d{1}:)?
(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?

Request Body
The request accepts the following data in JSON format.
DryRun (p. 466)
Set to true to validate the request parameters and access permissions without modifying the
function code.
Type: Boolean
Required: No

466

AWS Lambda Developer Guide
UpdateFunctionCode

Publish (p. 466)
Set to true to publish a new version of the function after updating the code. This has the same eﬀect
as calling PublishVersion (p. 440) separately.
Type: Boolean
Required: No
RevisionId (p. 466)
Only update the function if the revision ID matches the ID speciﬁed. Use this option to avoid
modifying a function that has changed since you last read it.
Type: String
Required: No
S3Bucket (p. 466)
An Amazon S3 bucket in the same region as your function. The bucket can be in a diﬀerent AWS
account.
Type: String
Length Constraints: Minimum length of 3. Maximum length of 63.
Pattern: ^[0-9A-Za-z\.\-_]*(?
Source Exif Data: 
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
Linearized                      : Yes
Author                          : Amazon Web Services
Create Date                     : 2019:01:18 07:59:06Z
Keywords                        : Lambda, AWS Lambda, serverless, serverless applications, cloud computing, API, requests, AddLayerVersionPermission, API, requests, AddPermission, API, requests, CreateAlias, API, requests, CreateEventSourceMapping, API, requests, CreateFunction, API, requests, DeleteAlias, API, requests, DeleteEventSourceMapping, API, requests, DeleteFunction, API, requests, DeleteFunctionConcurrency, API, requests, DeleteLayerVersion, API, requests, GetAccountSettings, API, requests, GetAlias, API, requests, GetEventSourceMapping, API, requests, GetFunction, API, requests, GetFunctionConfiguration, API, requests, GetLayerVersion, API, requests, GetLayerVersionPolicy, API, requests, GetPolicy, API, requests, Invoke, API, requests, InvokeAsync, API, requests, ListAliases, API, requests, ListEventSourceMappings, API, requests, ListFunctions, API, requests, ListLayers, API, requests, ListLayerVersions, API, requests, ListTags, API, requests, ListVersionsByFunction, API, requests, PublishLayerVersion, API, requests, PublishVersion, API, requests, PutFunctionConcurrency, API, requests, RemoveLayerVersionPermission, API, requests, RemovePermission, API, requests, TagResource, API, requests, UntagResource, API, requests, UpdateAlias, API, requests, UpdateEventSourceMapping, API, requests, UpdateFunctionCode, API, requests, UpdateFunctionConfiguration, Types, AccountLimit, Types, AccountUsage, Types, AliasConfiguration, Types, AliasRoutingConfiguration, Types, Concurrency, Types, DeadLetterConfig, Types, Environment, Types, EnvironmentError, Types, EnvironmentResponse, Types, EventSourceMappingConfiguration, Types, FunctionCode, Types, FunctionCodeLocation, Types, FunctionConfiguration, Types, Layer, Types, LayersListItem, Types, LayerVersionContentInput, Types, LayerVersionContentOutput, Types, LayerVersionsListItem, Types, TracingConfig, Types, TracingConfigResponse, Types, VpcConfig, Types, VpcConfigResponse
Modify Date                     : 2019:01:19 00:01:37-06:00
Has XFA                         : No
XMP Toolkit                     : Adobe XMP Core 5.6-c016 91.163616, 2018/10/29-16:58:49
Producer                        : Apache FOP Version 2.1
PDF Version                     : 1.4
Format                          : application/pdf
Creator                         : Amazon Web Services
Title                           : AWS Lambda - Developer Guide
Language                        : en
Date                            : 2019:01:18 07:59:06Z
Creator Tool                    : ZonBook XSL Stylesheets with Apache FOP
Metadata Date                   : 2019:01:19 00:01:37-06:00
Document ID                     : uuid:d6ed4c20-95cd-4f3e-a170-e6085d1e02e2
Instance ID                     : uuid:9debafeb-d441-4ea7-a6ad-e49a34a0d441
Page Mode                       : UseOutlines
Page Count                      : 526
Profile CMM Type                : Little CMS
Profile Version                 : 2.1.0
Profile Class                   : Display Device Profile
Color Space Data                : RGB
Profile Connection Space        : XYZ
Profile Date Time               : 1998:02:09 06:49:00
Profile File Signature          : acsp
Primary Platform                : Apple Computer Inc.
CMM Flags                       : Not Embedded, Independent
Device Manufacturer             : Hewlett-Packard
Device Model                    : sRGB
Device Attributes               : Reflective, Glossy, Positive, Color
Rendering Intent                : Perceptual
Connection Space Illuminant     : 0.9642 1 0.82491
Profile Creator                 : Little CMS
Profile ID                      : 0
Profile Copyright               : Copyright (c) 1998 Hewlett-Packard Company
Profile Description             : sRGB IEC61966-2.1
Media White Point               : 0.95045 1 1.08905
Media Black Point               : 0 0 0
Red Matrix Column               : 0.43607 0.22249 0.01392
Green Matrix Column             : 0.38515 0.71687 0.09708
Blue Matrix Column              : 0.14307 0.06061 0.7141
Device Mfg Desc                 : IEC http://www.iec.ch
Device Model Desc               : IEC 61966-2.1 Default RGB colour space - sRGB
Viewing Cond Desc               : Reference Viewing Condition in IEC61966-2.1
Viewing Cond Illuminant         : 19.6445 20.3718 16.8089
Viewing Cond Surround           : 3.92889 4.07439 3.36179
Viewing Cond Illuminant Type    : D50
Luminance                       : 76.03647 80 87.12462
Measurement Observer            : CIE 1931
Measurement Backing             : 0 0 0
Measurement Geometry            : Unknown
Measurement Flare               : 0.999%
Measurement Illuminant          : D65
Technology                      : Cathode Ray Tube Display
Red Tone Reproduction Curve     : (Binary data 2060 bytes, use -b option to extract)
Green Tone Reproduction Curve   : (Binary data 2060 bytes, use -b option to extract)
Blue Tone Reproduction Curve    : (Binary data 2060 bytes, use -b option to extract)

EXIF Metadata provided by EXIF.tools
AWS Lambda Developer Guide 1.Dev [Highlighted]

Navigation menu

Versions of this User Manual:

Views

Navigation
