Borislav Hadzhiev
Fri Sep 17 2021·4 min read
Photo by Zoë Jonker
To invoke a lambda function synchronously use the invoke
command, passing in
the function name, payload and output filename as parameters.
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --payload '{"name": "John Smith"}' response.json
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.
Name | Description |
---|---|
function-name | the name of the lambda function |
cli-binary-format | by default AWS CLI v2 takes base64 input, but we're passing a raw json string |
payload | the event , the function gets invoked with |
response.json | a 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:
exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify(`Hello ${event.name}!`), }; return response; };
Running the above command stores the following in the response.json
file:
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:
json
in the form of the event
, the lambda function expects
in a file on your local file system--payload
parameterCreate a file called event.json
with the following json in it:
{ "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
.
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --payload file://event.json response.json
--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:
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:
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
:
However, the response.json
file stores the lambda function's response with
status code of 400
:
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:
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:
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --payload file://event.json --qualifier 2 response.json
The response shows that the version of the function that ran was 2
.
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:
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
.
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --invocation-type Event --payload '{"fruit": "tomato"}' response.json
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
.
All of the other scenarios are the same as invoking a lambda function synchronously:
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:
{ "fruit": "avocado" }
Open your terminal in the directory where the event.json
file is stored and
run the invoke
command:
aws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --invocation-type Event --payload file://event.json response.json
--qualifier
parameter to specify a version of the function you want to
invokeaws lambda invoke --function-name testFunction --cli-binary-format raw-in-base64-out --invocation-type Event --qualifier 2 --payload file://event.json response.json