Invoke Lambda Functions with AWS CLI - Complete Guide

avatar

Borislav Hadzhiev

Fri Sep 17 20214 min read

banner

Photo by Zoë Jonker

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 in the function name, payload and 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 the --payload parameter should be '{\"name\": \"John Smith\"}' - with the double quotes escaped.

We've 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.jsona random name for a file where the function response should be stored

The --payload parameter is the event, the lambda function gets invoked with and response.json is a file on the local filesystem where we redirect the function's response.

For a simple, Node.js lambda function that consist of the following code:

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

Executing the above command stores the following in the response.json file:

lambda sync response

Synchronously Invoke Lambda with a File Payload #

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

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

  1. Store valid json in the form of the event, the lambda function expects in a file on your local file system
  2. Invoke the lambda function, passing in 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 event.json and invoke the lambda function, passing in the event.json file as --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 the 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 alias of a lambda function, with the AWS CLI, pass the --qualifier parameter to the invoke command.

I've deployed a version 2 of the lambda function, which contains 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 in 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 the function's executed version was 2.

Asynchronously Invoke Lambda Functions with AWS CLI #

When a lambda function is invoked asynchronously, we don'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, set the --payload you must escape the double quotes in the json string: '{\"fruit\": \"tomato\"}'.

In the command we've 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.

Same as with the synchronous invocation, we've 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 the lambda function might get executed up to a total of 3 times.

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

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

For example with an event.json file with the following contents:

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. Invoking a specific version or alias of the function - use the --qualifier parameter to specify a 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 #

Join my newsletter

I'll send you 1 email a week with links to all of the articles I've written that week

Buy Me A Coffee