Invoke an Amazon Lambda function with Step Functions
Learn how to use Step Functions to invoke Lambda functions either synchronously or asynchronously as part of an event-driven serverless application.
To learn about integrating with Amazon services in Step Functions, see Integrating services and Passing parameters to a service API in Step Functions.
Key features of Optimized Lambda integration
-
The
Payload
field of the response is parsed from escaped Json to Json. -
If the response contains the field
FunctionError
or an exception is raised within the Lambda function, the task fails.
For more information about managing state input, output, and results, see Processing input and output in Step Functions.
Supported Lambda APIs
-
-
Supported Parameters
Workflow Examples
The following includes a Task
state that invokes a Lambda function.
{
"StartAt":"CallLambda",
"States":{
"CallLambda":{
"Type":"Task",
"Resource":"arn:aws-cn:states:::lambda:invoke",
"Parameters":{
"FunctionName":"arn:aws-cn:lambda:us-east-1:123456789012:function:MyFunction
"
},
"End":true
}
}
}
The following includes a Task
state that implements the callback service integration pattern.
{
"StartAt":"GetManualReview",
"States":{
"GetManualReview":{
"Type":"Task",
"Resource":"arn:aws-cn:states:::lambda:invoke.waitForTaskToken",
"Parameters":{
"FunctionName":"arn:aws-cn:lambda:us-east-1:123456789012:function:get-model-review-decision
",
"Payload":{
"model.$":"$.new_model",
"token.$":"$$.Task.Token"
},
"Qualifier":"prod-v1"
},
"End":true
}
}
}
When you invoke a Lambda function, the execution will wait for the function to complete. If you invoke the Lambda function with a callback task, the heartbeat timeout does not start counting until after the Lambda function has completed executing and returned a result. As long as the Lambda function executes, the heartbeat timeout is not enforced.
It is also possible to call Lambda asynchronously using the InvocationType
parameter, as seen in the following example:
Note
For asynchronous invocations of Lambda functions, the heartbeat timeout period starts immediately.
{
"Comment": "A Hello World example of the Amazon States Language using Pass states",
"StartAt": "Hello",
"States": {
"Hello": {
"Type": "Task",
"Resource": "arn:aws-cn:states:::lambda:invoke",
"Parameters": {
"FunctionName": "arn:aws-cn:lambda:us-east-1:123456789012:function:echo
",
"InvocationType": "Event"
},
"End": true
}
}
}
When the Task
result is returned, the function output is nested inside a dictionary of metadata.
For example:
{ "ExecutedVersion":"$LATEST", "Payload":"
FUNCTION OUTPUT
", "SdkHttpMetadata":{ "HttpHeaders":{ "Connection":"keep-alive", "Content-Length":"4", "Content-Type":"application/json", "Date":"Fri, 26 Mar 2021 07:42:02 GMT", "X-Amz-Executed-Version":"$LATEST", "x-amzn-Remapped-Content-Length":"0", "x-amzn-RequestId":"0101aa0101-1111-111a-aa55-1010aaa1010", "X-Amzn-Trace-Id":"root=1-1a1a000a2a2-fe0101aa10ab;sampled=0" }, "HttpStatusCode":200 }, "SdkResponseMetadata":{ "RequestId":"6b3bebdb-9251-453a-ae45-512d9e2bf4d3" }, "StatusCode":200 }
Alternatively, you can invoke a Lambda function by specifying a function ARN directly in the "Resource" field. When you invoke a Lambda function in this way,
you can't specify .waitForTaskToken
, and the task result contains only the function output.
{
"StartAt":"CallFunction",
"States":{
"CallFunction": {
"Type":"Task",
"Resource":"arn:aws-cn:lambda:us-east-1:123456789012:function:HelloFunction
",
"End": true
}
}
}
You can invoke a specific Lambda function version or alias by specifying those options
in the ARN in the Resource
field. See the following in the Lambda
documentation:
IAM policies for calling Amazon Lambda
The following example templates show how Amazon Step Functions generates IAM policies based on the resources in your state machine definition. For more information, see How Step Functions generates IAM policies for integrated services and Discover service integration patterns in Step Functions.
Amazon Step Functions generates an IAM policy based on your state machine definition. For a state
machine with two Amazon Lambda task states that call function1
and
function2
, a policy with lambda:Invoke
permissions for the two
functions must be used.
This is shown in the following example.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:[[region]]
:[[accountId]]
:function:[[function1]]
",
"arn:aws:lambda:[[region]]
:[[accountId]]
:function:[[function2]]
"
]
}
]
}