Lambda - Amazon IoT Core
RequirementsParametersExamplesSee also
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Lambda

A Lambda (lambda) action invokes an Amazon Lambda function, passing in an MQTT message. Amazon IoT invokes Lambda functions asynchronously.

You can follow a tutorial that shows you how to create and test a rule with a Lambda action. For more information, see Tutorial: Formatting a notification by using an Amazon Lambda function.

Requirements

This rule action has the following requirements:

  • For Amazon IoT to invoke a Lambda function, you must configure a policy that grants the lambda:InvokeFunction permission to Amazon IoT. You can only invoke a Lambda function defined in the same Amazon Web Services Region where your Lambda policy exists. Lambda functions use resource-based policies, so you must attach the policy to the Lambda function itself.

    Use the following Amazon CLI command to attach a policy that grants the lambda:InvokeFunction permission. In this command, replace:

    • function_name with the name of the Lambda function. You add a new permission to update the function's resource policy.

    • region with the Amazon Web Services Region of the function.

    • account-id with the Amazon Web Services account number where the rule is defined.

    • rule-name with the name of the Amazon IoT rule for which you are defining the Lambda action.

    • unique_id with a unique statement identifier.

    Important

    If you add a permission for an Amazon IoT principal without providing the source-arn or source-account, any Amazon Web Services account that creates a rule with your Lambda action can activate rules to invoke your Lambda function from Amazon IoT.

    For more information, see Amazon Lambda permissions.

    aws lambda add-permission \ 
    --function-name function_name \ 
    --region region \ 
    --principal iot.amazonaws.com \
    --source-arn arn:aws:iot:region:account-id:rule/rule_name \
    --source-account account-id 
    --statement-id unique_id 
    --action "lambda:InvokeFunction"

  • If you use the Amazon IoT console to create a rule for the Lambda rule action, the Lambda function is triggered automatically. If you use Amazon CloudFormation instead with the AWS::IoT::TopicRule LambdaAction, you must add an AWS::lambda::Permission resource. The resource then grants you permission to trigger the Lambda function.

    The following code shows an example of how to add this resource. In this example, replace:

    • function_name with the name of the Lambda function.

    • region with the Amazon Web Services Region of the function.

    • account-id with the Amazon Web Services account number where the rule is defined.

    • rule-name with the name of the Amazon IoT rule for which you are defining the Lambda action.

    Type: AWS::Lambda::Permission
Properties:
  Action: lambda:InvokeFunction
  FunctionName: !Ref function_name
  Principal: "iot.amazonaws.com"
  SourceAccount: account-id
  SourceArn: arn:aws:iot:region:account-id:rule/rule_name

  • If you use an Amazon KMS customer managed Amazon KMS key to encrypt data at rest in Lambda, the service must have permission to use the Amazon KMS key on the caller's behalf. For more information, see Encryption at rest in the Amazon Lambda Developer Guide.

Parameters

When you create an Amazon IoT rule with this action, you must specify the following information:

functionArn

The ARN of the Lambda function to invoke. Amazon IoT must have permission to invoke the function. For more information, see Requirements.

If you don't specify a version or alias for your Lambda function, the most recent version of the function is shut down. You can specify a version or alias if you want to shut down a specific version of your Lambda function. To specify a version or alias, append the version or alias to the ARN of the Lambda function.

arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias

For more information about versioning and aliases, and see Amazon Lambda function versioning and aliases.

Supports substitution templates: API and Amazon CLI only

Examples

The following JSON example defines a Lambda action in an Amazon IoT rule.

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'", 
        "ruleDisabled": false, 
        "awsIotSqlVersion": "2016-03-23",
        "actions": [
            {
                "lambda": {
                    "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
                 }
            }
        ]
    }
}

The following JSON example defines a Lambda action with substitution templates in an Amazon IoT rule.

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'",
        "ruleDisabled": false,
        "awsIotSqlVersion": "2016-03-23",
        "actions": [
            {
                "lambda": {
                    "functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
                }
            }
        ]
    }
}

See also