Menu
Amazon Rekognition
Developer Guide

Tutorial: Creating an Amazon Rekognition Lambda Function

This tutorial shows how to get the results of a video analysis operation for label detection by using a Java Lambda function.

You can use Lambda functions with Amazon Rekognition Video operations. For example, the following diagram shows a website that uses a Lambda function to automatically start analysis of a video when it's uploaded to an Amazon S3 bucket. When the Lambda function is triggered, it calls StartLabelDetection to start detecting labels in the uploaded video. A second Lambda function is triggered when the analysis completion status is sent to the registered Amazon SNS topic. The second Lambda function calls GetLabelDetection to get the analysis results. The results are then stored in a database in preparation for displaying on a webpage.

In this tutorial, the Lambda function is triggered when Amazon Rekognition Video sends the completion status for the video analysis to the registered Amazon SNS topic. It then collects video analysis results by calling GetLabelDetection. For demonstration purposes, this tutorial writes label detection results to a CloudWatch log. In your application's Lambda function, you should store the analysis results for later use. For example, you can use Amazon DynamoDB to save the analysis results. For more information, see Working with DynamoDB.

The following procedures show you how to:

  • Create the Amazon SNS topic and set up permissions.

  • Create the Lambda function by using the AWS Management Console and subscribe it to the Amazon SNS topic.

  • Configure the Lambda function by using the AWS Management Console.

  • Add sample code to an AWS Toolkit for Eclipse project and upload it to the Lambda function.

  • Test the Lambda function by using the AWS CLI.

Prerequisites

This tutorial assumes that you're familiar with the AWS Toolkit for Eclipse. For more information, see AWS Toolkit for Eclipse.

Create the SNS Topic

The completion status of an Amazon Rekognition Video video analysis operation is sent to an Amazon SNS topic. This procedure creates the Amazon SNS topic and the IAM service role that gives Amazon Rekognition Video access to your Amazon SNS topics. For more information, see Calling Amazon Rekognition Video Operations.

To create an Amazon SNS topic

  1. If you haven't already, create an IAM service role to give Amazon Rekognition Video access to your Amazon SNS topics. Note the Amazon Resource Name (ARN). For more information, see Giving Access to Multiple Amazon SNS Topics.

  2. Create an Amazon SNS topic by using the Amazon SNS console. Prepend the topic name with AmazonRekognition. Note the topic ARN.

Create the Lambda Function

You create the Lambda function by using the AWS Management Console. Then you use an AWS Toolkit for Eclipse project to upload the Lambda function package to AWS Lambda. It's also possible to create the Lambda function with the AWS Toolkit for Eclipse. For more information, see Tutorial: How to Create, Upload, and Invoke an AWS Lambda Function.

To create the Lambda function

  1. Sign in to the AWS Management Console, and open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

  2. Choose Create function.

  3. Choose Author from scratch.

  4. In Name*, type a name for your function.

  5. In Runtime*, choose Java 8.

  6. In Role*, choose Create a custom role. A new tab is displayed for the custom role.

  7. On the new tab, do the following:

    1. Choose IAM Role, and then choose Create a new IAM Role.

    2. In Role Name, type a name for the new custom role.

    3. Choose Allow to create the new role. The custom role tab is closed, and you're returned to the Lambda creation page.

  8. In Role*, choose Choose an existing role.

  9. In Existing role*, choose the role that you created in step 7.

  10. Choose Create function.

Configure the Lambda Function

After you create the Lambda function, you configure it to be triggered by the Amazon SNS topic that you create in Create the SNS Topic. You also adjust the memory requirements and timeout period for the Lambda function.

To configure the Lambda function

  1. In Function Code, type com.amazonaws.lambda.demo.JobCompletionHandler for Handler.

  2. In Basic settings, choose 1024 for Memory.

  3. In Basic settings, choose 10 seconds for Timeout.

  4. In Designer, choose SNS from Add Triggers.

  5. In Configure triggers, choose the Amazon SNS topic that you created in Create the SNS Topic.

  6. Choose Enable trigger.

  7. To add the trigger, choose Add.

  8. Choose Save.

Configure the IAM Lambda Role

To call Amazon Rekognition Video operations, you add the AmazonRekognitionFullAccess AWS managed policy to the IAM Lambda role. Start operations, such as StartLabelDetection, also require pass role permissions for the IAM service role that Amazon Rekognition Video uses to access the Amazon SNS topic.

To configure the role

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles.

  3. In the list, choose the name of the custom role that you created in Create the Lambda Function.

  4. Choose the Permissions tab.

  5. Choose Attach policy.

  6. Choose AmazonRekognitionFullAccess from the list of policies.

  7. Choose Attach policy.

  8. Again, choose the custom role.

  9. Scroll to the bottom of the page, and choose Add inline policy.

  10. Choose the JSON tab.

  11. Replace the existing policy with the following policy. Replace servicerole with the IAM service role that you created in Create the SNS Topic.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "mysid", "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:servicerole" } ] }
  12. Choose Review policy.

  13. In Name*, type a name for the policy.

  14. Choose Create policy.

Create the AWS Toolkit for Eclipse Lambda Project

When the Lambda function is triggered, the following code gets the completion status from the Amazon SNS topic, and calls GetLabelDetection to get the analysis results. A count of labels detected, and a list of labels detected is written to a CloudWatch log. Your Lambda function should store the video analysis results for later use.

To create the AWS Toolkit for Eclipse Lambda project

  1. Create an AWS Toolkit for Eclipse AWS Lambda project.

    • For Project name:, type a project name of your choosing.

    • For Input type:, choose SNS Event.

    • Leave the other fields unchanged.

  2. In the Eclipse Project explorer, open the generated Lambda handler method and replace the contents with the following:

    //Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. //PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.) package com.amazonaws.lambda.demo; import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.LambdaLogger; import com.amazonaws.services.lambda.runtime.RequestHandler; import com.amazonaws.services.lambda.runtime.events.SNSEvent; import java.util.List; import com.amazonaws.regions.Regions; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.GetLabelDetectionRequest; import com.amazonaws.services.rekognition.model.GetLabelDetectionResult; import com.amazonaws.services.rekognition.model.LabelDetection; import com.amazonaws.services.rekognition.model.LabelDetectionSortBy; import com.amazonaws.services.rekognition.model.VideoMetadata; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; public class JobCompletionHandler implements RequestHandler<SNSEvent, String> { @Override public String handleRequest(SNSEvent event, Context context) { String message = event.getRecords().get(0).getSNS().getMessage(); LambdaLogger logger = context.getLogger(); // Parse SNS event for analysis results. Log results try { ObjectMapper operationResultMapper = new ObjectMapper(); JsonNode jsonResultTree = operationResultMapper.readTree(message); logger.log("Rekognition Video Operation:========================="); logger.log("Job id: " + jsonResultTree.get("JobId")); logger.log("Status : " + jsonResultTree.get("Status")); logger.log("Job tag : " + jsonResultTree.get("JobTag")); logger.log("Operation : " + jsonResultTree.get("API")); if (jsonResultTree.get("API").asText().equals("StartLabelDetection")) { if (jsonResultTree.get("Status").asText().equals("SUCCEEDED")){ GetResultsLabels(jsonResultTree.get("JobId").asText(), context); } else{ String errorMessage = "Video analysis failed for job " + jsonResultTree.get("JobId") + "State " + jsonResultTree.get("Status"); throw new Exception(errorMessage); } } else logger.log("Operation not StartLabelDetection"); } catch (Exception e) { logger.log("Error: " + e.getMessage()); throw new RuntimeException (e); } return message; } void GetResultsLabels(String startJobId, Context context) throws Exception { LambdaLogger logger = context.getLogger(); AmazonRekognition rek = AmazonRekognitionClientBuilder.standard().withRegion(Regions.US_EAST_1).build(); int maxResults = 1000; String paginationToken = null; GetLabelDetectionResult labelDetectionResult = null; String labels = ""; Integer labelsCount = 0; String label = ""; String currentLabel = ""; //Get label detection results and log them. do { GetLabelDetectionRequest labelDetectionRequest = new GetLabelDetectionRequest().withJobId(startJobId) .withSortBy(LabelDetectionSortBy.NAME).withMaxResults(maxResults).withNextToken(paginationToken); labelDetectionResult = rek.getLabelDetection(labelDetectionRequest); paginationToken = labelDetectionResult.getNextToken(); VideoMetadata videoMetaData = labelDetectionResult.getVideoMetadata(); // Add labels to log List<LabelDetection> detectedLabels = labelDetectionResult.getLabels(); for (LabelDetection detectedLabel : detectedLabels) { label = detectedLabel.getLabel().getName(); if (label.equals(currentLabel)) { continue; } labels = labels + label + " / "; currentLabel = label; labelsCount++; } } while (labelDetectionResult != null && labelDetectionResult.getNextToken() != null); logger.log("Total number of labels : " + labelsCount); logger.log("labels : " + labels); } }
  3. The Rekognition namespaces aren't resolved. To correct this:

    • Pause your mouse over the underlined portion of the line import com.amazonaws.services.rekognition.AmazonRekognition;.

    • Choose Fix project set up... .

    • Choose the latest version of the Amazon Rekognition archive.

    • Choose OK to add the archive to the project.

  4. Right-click in your Eclipse code window, choose AWS Lambda, and then choose Upload function to AWS Lambda.

  5. On the Select Target Lambda Function page, choose the AWS Region to use.

  6. Choose Choose an existing lambda function, and select the Lambda function that you created in Create the Lambda Function.

  7. Choose Next.

  8. On the Function Configuration page, select the IAM role that you created in Create the Lambda Function.

  9. Choose Finish, and the Lambda function is uploaded to AWS.

Test the Lambda Function

Use the following AWS CLI command to test the Lambda function by starting the label detection analysis of a video. After analysis is finished, the Lambda function is triggered. Confirm that the analysis succeeded by checking the CloudWatch Logs logs.

To test the Lambda function

  1. Upload an .mp4, .mov, or .avi format video file to your S3 bucket. For test purposes, upload a video that's no longer than 30 seconds in length.

    For instructions, see Uploading Objects into Amazon S3 in the Amazon Simple Storage Service Console User Guide.

  2. Run the following AWS CLI command to start detecting labels in a video.

    aws rekognition start-label-detection --video "S3Object={Bucket="bucketname",Name="videofile"}" \ --endpoint-url Endpoint \ --notification-channel "SNSTopicArn=TopicARN,RoleArn=RoleARN" \ --region us-east-1 \ --profile RekognitionUser

    Update the following values:

    • Change bucketname and videofile to the Amazon S3 bucket name and file name of the video that you want to detect labels in.

    • Change Endpoint and us-east-1 to the AWS endpoint and region that you're using.

    • Change TopicARN to the ARN of the Amazon SNS topic that you created in Create the SNS Topic.

    • Change RoleARN to the ARN of the IAM role that you created in Create the SNS Topic.

    • Change RekognitionUser to an AWS account that has permissions to call Amazon Rekognition Video operations.

  3. Note the value of JobId in the response. The response looks similar to the following JSON example.

    { "JobId": "547089ce5b9a8a0e7831afa655f42e5d7b5c838553f1a584bf350ennnnnnnnnn" }
  4. Open the https://console.aws.amazon.com/cloudwatch/ console.

  5. When the analysis completes, a log entry for the Lambda function appears in the Log Group.

  6. Choose the Lambda function to see the log streams.

  7. Choose the latest log stream to see the log entries made by the Lambda function. If the operation succeeded, it looks similar to the following:

    The value of Jod id should match the value of JobId that you noted in step 3.