new serverless pattern - rekognition-s3-detectfaces-python

rekognition-s3-detectfaces-python/README.md

@@ -0,0 +1,66 @@
+# Amazon S3 to Amazon Rekognition through AWS EventBridge
+
+This pattern demonstrates how to create an S3 bucket which when uploaded with an object invokes a Lambda function through EventBridge. The function detect faces in an image through Amazon Rekognition. The lambda function is built using Python.
+
+Learn more about this pattern at Serverless Land Patterns: https://serverlessland.com/patterns/rekognition-s3-detectfaces-python
+
+Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
+
+## Requirements
+
+* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
+* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
+* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+* [AWS Serverless Application Model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) (AWS SAM) installed
+
+## Deployment Instructions
+
+1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
+    ``` 
+    git clone https://github.com/aws-samples/serverless-patterns
+    ```
+1. Change directory to the pattern directory:
+    ```
+    cd rekognition-s3-detectfaces-python
+    ```
+1. From the command line, use AWS SAM to deploy the AWS resources for the pattern as specified in the template.yml file:
+    ```
+    sam deploy --guided
+    ```
+1. During the prompts:
+    * Enter a stack name
+    * Enter the desired AWS Region
+    * Allow SAM CLI to create IAM roles with the required permissions.
+
+    Once you have run `sam deploy --guided` mode once and saved arguments to a configuration file (samconfig.toml), you can use `sam deploy` in future to use these defaults.
+
+1. Note the outputs from the SAM deployment process. These contain the resource names and/or ARNs which are used for testing.
+
+## How it works
+
+The Cloudformation template creates 2 S3 buckets (source and destination buckets) along with a Lambda function (Python) and an EventBridge event. The Lambda function is triggered by the EventBridge which listens to an object upload in the S3 bucket. The lambda function  makes a DetectFaces API call to detect the faces in the image and stores the output in the destination S3 bucket.
+
+## Testing
+
+Upload the file (document/image) to the input S3 <STACK_NAME>-input-bucket-<AWS_ACCOUNTID> bucket via the console or use the PutObject API call below:
+
+```
+aws s3api put-object --bucket <INPUT_BUCKET_NAME>> --key <IMAGE_FILE> --body /path/to/your/<IMAGE_FILE>
+```
+
+Replace the parameters in the above command appropriately.
+
+## Cleanup
+
+1. Delete the stack
+    ```bash
+    aws cloudformation delete-stack --stack-name STACK_NAME
+    ```
+1. Confirm the stack has been deleted
+    ```bash
+    aws cloudformation list-stacks --query "StackSummaries[?contains(StackName,'STACK_NAME')].StackStatus"
+    ```
+----
+Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: MIT-0

rekognition-s3-detectfaces-python/example-pattern.json

@@ -0,0 +1,59 @@
+{
+    "title": "S3 to Rekognition using EventBridge",
+    "description": "SAM template for S3 trigger to Lambda for detecting faces in an image using Rekognition and EventBridge",
+    "language": "python",
+    "level": "200",
+    "framework": "SAM",
+    "introBox": {
+      "headline": "How it works",
+      "text": [
+        "This pattern demonstrates how to creates two S3 buckets (source and destination) which when uploaded with an object invokes a Lambda function through EventBridge and detects faces in an image using Amazon Rekognition.",
+        "Once a file is uploaded to an S3 bucket, it is listened by the EventBridge which further invokes the lambda function",
+        "The lambda function writes the output of the detected faces using Rekognition to the destination S3 bucket."
+      ]
+    },
+    "gitHub": {
+      "template": {
+        "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/rekognition-s3-detectfaces-python",
+        "templateURL": "serverless-patterns/rekognition-s3-detectfaces-python",
+        "projectFolder": "rekognition-s3-detectfaces-python",
+        "templateFile": "template.yaml"
+      }
+    },
+    "resources": {
+      "bullets": [
+        {
+          "text": "Detecting faces using Rekognition",
+          "link": "https://docs.aws.amazon.com/rekognition/latest/dg/faces.html"
+        },
+        {
+          "text": "Amazon Rekognition",
+          "link": "https://aws.amazon.com/rekognition/"
+        }
+      ]
+    },
+    "deploy": {
+      "text": [
+        "sam deploy"
+      ]
+    },
+    "testing": {
+      "text": [
+        "See the GitHub repo for detailed testing instructions."
+      ]
+    },
+    "cleanup": {
+      "text": [
+        "Delete the stack: <code>cdk delete</code>."
+      ]
+    },
+    "authors": [
+      {
+        "name": "Abilashkumar P C",
+        "image": "https://drive.google.com/file/d/1bxOh_WBw8J_xEqvT-qRezH8WXqSBPI24/view?usp=sharing",
+        "bio": "Sr. Cloud Support Engineer @ AWS",
+        "linkedin": "abilashkumar-p-c"
+      }
+    ]
+  }
+

rekognition-s3-detectfaces-python/src/lambda_function.py

@@ -0,0 +1,41 @@
+import boto3
+import json
+import os
+s3 = boto3.client('s3')
+rekognition = boto3.client('rekognition')
+
+def handler(event, context):
+            # Extract bucket and key from the EventBridge event
+            detail = event['detail']
+            bucket = detail['bucket']['name']
+            key = detail['object']['key']
+
+            # Call Rekognition to detect faces
+            response = rekognition.detect_faces(
+                Image={
+                    'S3Object': {
+                        'Bucket': bucket,
+                        'Name': key
+                    }
+                }
+            )
+
+            # Write the Rekognition output to the output bucket
+            output_key = f"rekognition-output-{key}"
+            output_key = output_key[:output_key.rfind('.')]
+            output_key = output_key + ".json"
+            print(output_key)
+
+            faceDetection=response['FaceDetails']
+            print(response)
+
+            s3.put_object(
+                Bucket=os.environ['OUTPUT_BUCKET'],
+                Key=output_key,
+                Body=json.dumps(faceDetection)
+            )
+
+            return {
+                'statusCode': 200,
+                'body': json.dumps('Document processed successfully')
+            }

rekognition-s3-detectfaces-python/template.yaml

@@ -0,0 +1,85 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: 'SAM template for S3 trigger to Lambda for detecting faces in an image using Rekognition and EventBridge'
+
+Resources:
+  # Input S3 bucket
+  InputBucket:
+    Type: AWS::S3::Bucket
+    Properties:
+      BucketName: !Sub '${AWS::StackName}-input-bucket-${AWS::AccountId}'
+      NotificationConfiguration:
+        EventBridgeConfiguration:
+          EventBridgeEnabled: true
+
+  # Output S3 bucket  
+  OutputBucket:
+    Type: AWS::S3::Bucket
+    Properties:
+      BucketName: !Sub '${AWS::StackName}-output-bucket-${AWS::AccountId}'
+
+  # Lambda function
+  RekognitionFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      FunctionName: !Sub '${AWS::StackName}-rekognition-function'
+      Handler: lambda_function.handler
+      Runtime: python3.8
+      Timeout: 30
+      Environment:
+        Variables:
+          OUTPUT_BUCKET: !Ref OutputBucket
+      Policies:
+        - S3ReadPolicy:
+            BucketName: !Ref InputBucket
+        - S3WritePolicy:
+            BucketName: !Ref OutputBucket
+        - Statement:
+            - Effect: Allow
+              Action: 
+                - rekognition:DetectFaces
+              Resource: '*'
+      CodeUri: src/
+
+
+  # EventBridge Rule
+  S3ObjectCreatedRule:
+    Type: AWS::Events::Rule
+    Properties:
+      Description: "Rule to capture S3 object created events"
+      EventPattern:
+        source:
+          - aws.s3
+        detail-type:
+          - Object Created
+        detail:
+          bucket:
+            name:
+              - !Ref InputBucket
+      State: "ENABLED"
+      Targets: 
+        - Arn: !GetAtt RekognitionFunction.Arn
+          Id: "RekognitionFunctionTarget"
+
+  # Permission for EventBridge to invoke Lambda
+  RekognitionFunctionPermission:
+    Type: AWS::Lambda::Permission
+    Properties:
+      FunctionName: !Ref RekognitionFunction
+      Action: "lambda:InvokeFunction"
+      Principal: "events.amazonaws.com"
+      SourceArn: !GetAtt S3ObjectCreatedRule.Arn
+
+Outputs:
+  InputBucketName:
+    Description: 'Name of the input S3 bucket'
+    Value: !Ref InputBucket
+  OutputBucketName:
+    Description: 'Name of the output S3 bucket'
+    Value: !Ref OutputBucket
+  RekognitionFunctionName:
+    Description: 'Name of the Rekognition Lambda function'
+    Value: !Ref RekognitionFunction
+  RekognitionFunctionArn:
+    Description: 'ARN of the Rekognition Lambda function'
+    Value: !GetAtt RekognitionFunction.Arn