Invoke Lambda Functions with AWS CLI - Complete Guide

avatar

Borislav Hadzhiev

Last updated: Jul 29, 2022

banner

Photo from Unsplash

Table of Contents #

  1. Synchronously Invoke Lambda Functions with the AWS CLI
  2. Synchronously Invoke Lambda with a File Payload
  3. Synchronously Invoke Different Versions of Lambda
  4. Asynchronously Invoke Lambda Functions with AWS CLI

Synchronously Invoke Lambda Functions with the AWS CLI #

To invoke a lambda function synchronously, use the invoke command, passing it the function name, the payload and the output filename as parameters.

shell
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --payload '{"name": "John Smith"}' response.json

invoke lambda sync

If you're on Windows, escape the double quotes of the --payload parameter, e.g. '{\"name\": \"John Smith\"}'.

We passed the following parameters to the invoke command.

NameDescription
function-namethe name of the lambda function
cli-binary-formatby default, AWS CLI v2 takes base64 input, but we're passing a raw json string
payloadthe event the function gets invoked with
response.jsonan arbitrary file name where the function's response should be stored

The --payload parameter is the event the lambda function gets invoked with.

response.json is a file on the local filesystem where we redirect the function's response.

Here is the code for the Node.js lambda function I'll invoke with the next command.

index.js
exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify(`Hello ${event.name}!`), }; return response; };

By running the above command, I get the following output (stored in a response.json file).

lambda sync response

Synchronously Invoke Lambda with a File Payload #

Sometimes the payload is too complex to be directly passed using the CLI.

To invoke a lambda function, passing it a file as a payload:

  1. Create a file on your local system that stores valid json in the form of the event your lambda function expects.
  2. Invoke the lambda function, passing it the file as the --payload parameter

Create a file called event.json with the following json in it.

event.json
{ "name": "John Doe" }

Open your terminal in the directory where you stored the event.json file. Then invoke the lambda function, passing it the event.json file as the --payload.

shell
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --payload file://event.json response.json

invoke lambda sync with file

When passing local files as --parameters to an AWS CLI command, prefix the path with file:// for human-readable files, or with fileb:// for binary (non human-readable) files.

Take a look at the response.json file to make sure the response matches your expectations.

lambda sync file response

The statusCode the AWS CLI responds with is not the status code from the function's response. The statusCode property of the CLI response relates to permission, limit or configuration errors.

For instance, if I update the code of my lambda function to respond with a 400 status code.

index.js
exports.handler = async (event) => { const response = { statusCode: 400, body: JSON.stringify(`Hello ${event.name}!`), }; return response; };

The statusCode in the CLI response would still be 200.

lambda sync status 200

However, the response.json file stores the lambda function's response with status code of 400.

lambda sync status 400

Synchronously Invoke Different Versions of Lambda #

To invoke a specific version or an alias of a lambda function using the AWS CLI, pass the --qualifier parameter to the invoke command.

I've deployed a version 2 of the lambda function. The new version consists of the following code:

index.js
exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify(`Goodbye ${event.name}!`), }; return response; };

Let's invoke version 2 of the lambda function, passing it the --qualifier parameter:

shell
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --payload file://event.json --qualifier 2 response.json

lambda sync version 2

The response shows that version 2 of the function ran.

Asynchronously Invoke Lambda Functions with AWS CLI #

When a lambda function is invoked asynchronously, the CLI doesn't wait for the function's response. The request is sent to lambda, which queues the events and sends them to the function.

We will invoke a lambda function that's written in Node.js and contains the following code.

index.js
exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify(`Favorite fruit: ${event.fruit}`), }; return response; };

To asynchronously invoke a lambda function with the AWS CLI, set the --invocation-type parameter to Event.

shell
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --invocation-type Event --payload '{"fruit": "tomato"}' response.json

invoke lambda async

If you are on Windows, you must escape the double quotes in the json string, e.g. '{\"fruit\": \"tomato\"}'.

We set the --invocation-type parameter to Event to mark the invocation as asynchronous.

The response.json file where the lambda function's response is stored is empty because the CLI returns instantly and doesn't wait for the function to respond.

We also set the --cli-binary-format parameter to raw-in-base64-out to be able to pass a raw json string as --payload.

When an asynchronous lambda invocation errors out, the lambda function might get invoked up to a total of 3 times.

All the other scenarios are the same as invoking a lambda function synchronously:

  1. To invoke the function with a file, store valid json in a file on your local file system and prefix the --payload parameter with file://

Here is the event.json file I'll use for the next command.

event.json
{ "fruit": "avocado" }

Open your terminal in the directory where the event.json file is stored and run the invoke command:

shell
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --invocation-type Event --payload file://event.json response.json

invoke lambda async with file

  1. To invoke a specific version or an alias of the function, use the --qualifier parameter to specify the version of the function you want to invoke
shell
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --invocation-type Event --qualifier 2 --payload file://event.json response.json

invoke lambda async with version

Further Reading #

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.
book cover
You can use the search field on my Home Page to filter through all of my articles.