Definir o manipulador da função do Lambda em Java

O manipulador da função do Lambda é o método no código da função que processa eventos. Quando sua função é invocada, o Lambda executa o método do manipulador. A função é executada até que o manipulador retorne uma resposta, seja encerrado ou atinja o tempo limite.

Esta página descreve como trabalhar com manipuladores de função do Lambda em Java, incluindo opções para a configuração de projeto, as convenções de nomenclatura e as práticas recomendadas. Além disso, esta página apresenta um exemplo de uma função do Lambda em Java que aceita informações sobre um pedido, produz um recibo em formato de texto e armazena esse arquivo em um bucket do Amazon Simple Storage Service (Amazon S3). Para obter mais informações sobre como implantar a função após gravá-la, consulte Implantar funções do Lambda em Java com arquivos .zip ou JAR ou Implantar funções do Lambda em Java com imagens de contêiner.

Configuração do projeto de manipulador em Java

Ao trabalhar com funções do Lambda em Java, o processo envolve escrever seu código, compilá-lo e implantar os artefatos compilados no Lambda. Você pode inicializar um projeto Java Lambda de várias maneiras. Por exemplo, você pode usar ferramentas como o Maven Archetype para funções Lambda, a CLI do AWS SAM comando sam init, ou até mesmo uma configuração de projeto Java padrão em seu IDE preferido, como IntelliJ IDEA ou Visual Studio Code. Você também pode criar a estrutura de arquivos necessária manualmente.

Um projeto típico de função do Lambda em Java segue esta estrutura geral:

/project-root
    └ src
        └ main
            └ java
                └ example
                    └ OrderHandler.java (contains main handler)
                    └ <other_supporting_classes>
     └ build.gradle OR pom.xml

Você pode usar o Maven ou o Gradle para criar seu projeto e gerenciar dependências.

A lógica principal do manipulador da sua função reside em um arquivo Java no diretório src/main/java/example. No exemplo desta página, chamamos esse arquivo de OrderHandler.java. Além desse arquivo, você pode incluir mais classes Java conforme necessário. Ao implantar sua função no Lambda, certifique-se de especificar a classe Java que contém o método manipulador principal que o Lambda deve invocar durante uma invocação.

Exemplo de código da função do Lambda em Java

O exemplo de código apresentado a seguir para uma função do Lambda em Java 21 aceita informações sobre um pedido, produz um recibo em formato de texto e armazena esse arquivo em um bucket do Amazon S3.

package example;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;

import java.nio.charset.StandardCharsets;

/**
 * Lambda handler for processing orders and storing receipts in S3.
 */
public class OrderHandler implements RequestHandler<OrderHandler.Order, String> {

    private static final S3Client S3_CLIENT = S3Client.builder().build();

    /**
     * Record to model the input event.
     */
    public record Order(String orderId, double amount, String item) {}

    @Override
    public String handleRequest(Order event, Context context) {
        try {
            // Access environment variables
            String bucketName = System.getenv("RECEIPT_BUCKET");
            if (bucketName == null || bucketName.isEmpty()) {
                throw new IllegalArgumentException("RECEIPT_BUCKET environment variable is not set");
            }

            // Create the receipt content and key destination
            String receiptContent = String.format("OrderID: %s\nAmount: $%.2f\nItem: %s",
                    event.orderId(), event.amount(), event.item());
            String key = "receipts/" + event.orderId() + ".txt";

            // Upload the receipt to S3
            uploadReceiptToS3(bucketName, key, receiptContent);

            context.getLogger().log("Successfully processed order " + event.orderId() +
                    " and stored receipt in S3 bucket " + bucketName);
            return "Success";

        } catch (Exception e) {
            context.getLogger().log("Failed to process order: " + e.getMessage());
            throw new RuntimeException(e);
        }
    }

    private void uploadReceiptToS3(String bucketName, String key, String receiptContent) {
        try {
            PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(key)
                    .build();

            // Convert the receipt content to bytes and upload to S3
            S3_CLIENT.putObject(putObjectRequest, RequestBody.fromBytes(receiptContent.getBytes(StandardCharsets.UTF_8)));
        } catch (S3Exception e) {
            throw new RuntimeException("Failed to upload receipt to S3: " + e.awsErrorDetails().errorMessage(), e);
        }
    }
}

Este arquivo OrderHandler.java contém as seguintes seções de código:

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.amazonaws:aws-lambda-java-core:1.2.3'
    implementation 'software.amazon.awssdk:s3:2.28.29'
    implementation 'org.slf4j:slf4j-nop:2.0.16'
}

task buildZip(type: Zip) {
    from compileJava
    from processResources
    into('lib') {
        from configurations.runtimeClasspath
    }
}

java {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

build.dependsOn buildZip

Para que esta função funcione corretamente, seu perfil de execução deve permitir a ação s3:PutObject. Além disso, certifique-se de definir a variável de ambiente RECEIPT_BUCKET. Após uma invocação com êxito, o bucket do Amazon S3 deve conter um arquivo de recibo.

Definições de classe válidas para manipuladores Java

Para definir sua classe, a biblioteca aws-lambda-java-core define duas interfaces para métodos do manipulador. Use as interfaces fornecidas para simplificar a configuração do manipulador e validar a assinatura do método no momento da compilação.

A interface RequestHandler é um tipo genérico que usa dois parâmetros: o tipo de entrada e o tipo de saída. Ambos os tipos devem ser objetos. Neste exemplo, nossa classe OrderHandler implementa RequestHandler<OrderHandler.Order, String>. O tipo de entrada é o registro Order que definimos dentro da classe, e o tipo de saída é String.

public class OrderHandler implements RequestHandler<OrderHandler.Order, String> {
    ...
}

Quando você usa essa interface, o runtime do Java desserializa o evento no objeto com o tipo de entrada e serializa a saída em texto. Use essa interface quando a serialização interna funcionar com seus tipos de entrada e saída.

Para usar sua própria serialização, você pode implemente a interface RequestStreamHandler. Com essa interface, o Lambda transmite ao seu manipulador uma transmissão de entrada e uma de saída. O manipulador lê bytes do fluxo de entrada, grava no fluxo de saída e retorna um void. Para ver um exemplo disso usando o runtime do Java 21, consulte HandlerStream.java.

Se você estiver trabalhando somente com tipos básicos e genéricos (ou seja, String, Integer, =List ou Map) em sua função Java, não precisará implementar uma interface. Por exemplo, se sua função recebe uma entrada Map<String, String> e retorna um String, sua definição de classe e assinatura do manipulador podem ter a seguinte aparência:

public class ExampleHandler {
    public String handleRequest(Map<String, String> input, Context context) {
        ...
    }
}

Além disso, quando você não implementa uma interface, o objeto de contexto é opcional. Por exemplo, sua definição de classe e assinatura de manipulador podem ter a seguinte aparência:

public class NoContextHandler {
   public String handleRequest(Map<String, String> input) {
        ...
   }
}

Convenções de nomenclatura para manipuladores

Para funções do Lambda em Java, se você estiver implementando a interface RequestHandler ou RequestStreamHandler, seu método de manipulador principal deverá ser nomeado handleRequest. Além disso, inclua a tag @Override acima do seu método handleRequest. Ao implantar sua função no Lambda, especifique o manipulador principal na configuração da sua função no seguinte formato:

Para funções do Lambda em Java que não implementam a interface RequestHandler ou RequestStreamHandler, você pode usar qualquer nome para o manipulador. Ao implantar sua função no Lambda, especifique o manipulador principal na configuração da sua função no seguinte formato:

Definição e acesso ao objeto do evento de entrada

O formato de entrada JSON é o mais comum e padrão para funções do Lambda. Neste exemplo, a função espera uma entrada semelhante à seguinte:

{
    "orderId": "12345",
    "amount": 199.99,
    "item": "Wireless Headphones"
}

Ao trabalhar com funções do Lambda em Java 17, é possível definir o formato do evento de entrada esperado como um registro em Java. Neste exemplo, definimos um registro dentro da classe OrderHandler para representar um objeto Order:

public record Order(String orderId, double amount, String item) {}

Esse registro corresponde ao formato de entrada esperado. Após definir o registro, você pode escrever uma assinatura de manipulador que aceita uma entrada JSON que está em conformidade com a definição do registro. O runtime do Java automaticamente desserializa esse JSON em um objeto Java. Em seguida, você pode acessar os campos do objeto. Por exemplo, event.orderId recupera o valor de orderId da entrada original.

Outros tipos de eventos de entrada

Há muitos eventos de entrada possíveis para funções do Lambda em Java:

Acesso e uso do objeto de contexto do Lambda

O objeto de contexto do Lambda contém informações sobre a invocação, a função e o ambiente de execução. Neste exemplo, o objeto de contexto é do tipo com.amazonaws.services.lambda.runtime.Context e é o segundo argumento da função principal do manipulador.

public String handleRequest(Order event, Context context) {
    ...
}

Se sua classe implementa a interface RequestHandler ou RequestStreamHandler, o objeto de contexto é um argumento obrigatório. Caso contrário, o objeto de contexto é opcional. Para obter mais informações sobre as assinaturas de manipulador válidas e aceitas, consulte Definições de classe válidas para manipuladores Java.

Se você realizar chamadas a outros serviços usando o AWS SDK, o objeto de contexto será necessário em algumas áreas importantes. Por exemplo, para produzir logs de funções para o Amazon CloudWatch, você pode usar o método context.getLogger() para obter um objeto LambdaLogger para registro em log. Neste exemplo, podemos usar o logger para registrar uma mensagem de erro se o processamento falhar por qualquer motivo:

context.getLogger().log("Failed to process order: " + e.getMessage());

Fora do registro em log, é possível usar o objeto de contexto para realizar o monitoramento da função. Para obter mais informações sobre o objeto de contexto, consulte Usar o objeto de contexto do Lambda para recuperar informações das funções em Java.

Uso do SDK da AWS para Java v2 em seu manipulador

Frequentemente, você usará as funções do Lambda para interagir com ou fazer atualizações em outros recursos da AWS. A maneira mais simples de interagir com esses recursos é usar o SDK da AWS para Java v2.

Para adicionar dependências do SDK à sua função, adicione-as em seu arquivo build.gradle para Gradle ou pom.xml para Maven. Recomendamos adicionar somente as bibliotecas necessárias para sua função. No código de exemplo anterior, usamos a biblioteca software.amazon.awssdk.services.s3. No Gradle, você pode adicionar essa dependência adicionando a seguinte linha na seção de dependências do seu build.gradle:

implementation 'software.amazon.awssdk:s3:2.28.29'

No Maven, adicione as seguintes linhas na seção <dependencies> do seu pom.xml:

    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
        <version>2.28.29</version>
    </dependency>

Em seguida, importe as dependências diretamente na sua classe Java:

import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;

O código de exemplo então inicializa um cliente do Amazon S3 da seguinte maneira:

private static final S3Client S3_CLIENT = S3Client.builder().build();

Neste exemplo, inicializamos nosso cliente do Amazon S3 fora da função do manipulador principal para evitar a necessidade que inicializá-lo a cada vez que nossa função é invocada. Após inicializar o cliente do SDK, você pode usá-lo para interagir com outros serviços da AWS. O código de exemplo chama a API PutObject do Amazon S3 da seguinte forma:

PutObjectRequest putObjectRequest = PutObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build();

// Convert the receipt content to bytes and upload to S3
S3_CLIENT.putObject(putObjectRequest, RequestBody.fromBytes(receiptContent.getBytes(StandardCharsets.UTF_8)));

Acesso a variáveis de ambiente

No código do manipulador, você pode fazer referência a qualquer variável de ambiente ao usar o método System.getenv(). Neste exemplo, referenciamos a variável de ambiente RECEIPT_BUCKET definida usando a seguinte linha de código:

String bucketName = System.getenv("RECEIPT_BUCKET");
if (bucketName == null || bucketName.isEmpty()) {
    throw new IllegalArgumentException("RECEIPT_BUCKET environment variable is not set");
}

Usar o estado global

O Lambda executa seu código estático e o construtor de classe durante a fase de inicialização antes de invocar a função pela primeira vez. Os recursos criados durante a inicialização permanecem na memória entre as invocações, para que você possa evitar ter que criá-los toda vez que invocar sua função.

No código de exemplo, o código de inicialização do cliente do S3 está fora do método do manipulador principal. O runtime inicializa o cliente antes que a função manipule seu primeiro evento e o cliente permanece disponível para reutilização em todas as invocações.

Práticas recomendadas de código para as funções do Lambda em Java

Adote as diretrizes da lista a seguir para usar as práticas recomendadas de codificação ao compilar suas funções do Lambda: