Definieren des Lambda-Funktions-Handlers in Java

Der Lambda-Funktionshandler ist die Methode in Ihrem Funktionscode, die Ereignisse verarbeitet. Wenn Ihre Funktion aufgerufen wird, führt Lambda die Handler-Methode aus. Ihre Funktion wird so lange ausgeführt, bis der Handler eine Antwort zurückgibt, beendet wird oder ein Timeout auftritt.

Auf dieser Seite wird beschrieben, wie Sie mit Lambda-Funktionshandlern in Java arbeiten, einschließlich Optionen für die Projekteinrichtung, Benennungskonventionen und Best Practices. Diese Seite enthält auch ein Beispiel für eine Java-Lambda-Funktion, die Informationen über eine Bestellung aufnimmt, eine Textdateiquittung erstellt und diese Datei in einem Amazon Simple Storage Service (S3) -Bucket ablegt. Informationen darüber, wie Sie Ihre Funktion nach dem Schreiben einsetzen können, finden Sie unter Bereitstellen von Java-Lambda-Funktionen mit ZIP- oder JAR-Dateiarchiven oder Bereitstellen von Java-Lambda-Funktionen mit Container-Images.

Richten Sie Ihr Java-Handler-Projekt ein

Wenn Sie mit Lambda-Funktionen in Java arbeiten, umfasst der Prozess das Schreiben Ihres Codes, das Kompilieren und das Bereitstellen der kompilierten Artefakte in Lambda. Sie können ein Java-Lambda-Projekt auf verschiedene Arten initialisieren. Sie können beispielsweise Tools wie den Maven-Archetype für Lambda-Funktionen, den AWS SAM CLI-Befehl sam init oder sogar ein Standard-Java-Projekt-Setup in Ihrer bevorzugten IDE wie IntelliJ IDEA oder Visual Studio Code verwenden. Alternativ können Sie die erforderliche Dateistruktur manuell erstellen.

Ein typisches Java-Lambda-Funktionsprojekt folgt dieser allgemeinen Struktur:

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

Sie können entweder Maven oder Gradle verwenden, um Ihr Projekt zu erstellen und Abhängigkeiten zu verwalten.

Die Haupthandler-Logik für Ihre Funktion befindet sich in einer Java-Datei unter dem Verzeichnis. src/main/java/example In dem Beispiel auf dieser Seite geben wir dieser Datei OrderHandler.java einen Namen. Neben dieser Datei können Sie bei Bedarf weitere Java-Klassen hinzufügen. Wenn Sie Ihre Funktion in Lambda bereitstellen, stellen Sie sicher, dass Sie die Java-Klasse angeben, die die Haupthandler-Methode enthält, die Lambda während eines Aufrufs aufrufen soll.

Beispiel für einen Java-Lambda-Funktionscode

Das folgende Beispiel für einen Java 21-Lambda-Funktionscode nimmt Informationen über eine Bestellung auf, erstellt eine Textdateiquittung und platziert diese Datei in einem Amazon S3 S3-Bucket.

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);
        }
    }
}

Diese OrderHandler.java-Datei enthält die folgenden Abschnitte des Codes:

Damit diese Funktion ordnungsgemäß funktioniert, muss ihre Ausführungsrolle die s3:PutObject Aktion zulassen. Stellen Sie außerdem sicher, dass Sie die RECEIPT_BUCKET-Umgebungsvariable definieren. Nach einem erfolgreichen Aufruf sollte der Amazon-S3-Bucket eine Empfangsdatei enthalten.

Gültige Klassendefinitionen für Java-Handler

Um Ihre Klasse zu definieren, definiert die aws-lambda-java-coreBibliothek zwei Schnittstellen für Handler-Methoden. Verwenden Sie die bereitgestellten Schnittstellen, um die Konfiguration des Handlers zu vereinfachen und die Methodensignatur bei der Kompilierung zu überprüfen.

Die RequestHandler-Schnittstelle ist ein generischer Typ, der zwei Parameter verwendet: den Eingabetyp und den Ausgabetyp. Beide Typen müssen Objekte sein. In diesem Beispiel implementiert unsere OrderHandler KlasseRequestHandler<OrderHandler.Order, String>. Der Eingabetyp ist der Order Datensatz, den wir innerhalb der Klasse definieren, und der Ausgabetyp istString.

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

Wenn Sie diese Schnittstelle verwenden, deserialisiert die Java-Runtime das Ereignis in das Objekt mit dem Eingabetyp und serialisiert die Ausgabe in Text. Verwenden Sie diese Schnittstelle, wenn die integrierte Serialisierung mit Ihren Ein- und Ausgabetypen funktioniert.

Um Ihre eigene Serialisierung zu verwenden, können Sie die Schnittstelle implementieren. RequestStreamHandler Mit dieser Schnittstelle übergibt Lamda Ihrem Handler einen Eingabestream und einen Ausgabestream. Der Handler liest Bytes aus dem Eingabestream, schreibt in den Ausgabestream und gibt „void“ zurück. Ein Beispiel dafür, wie die Java 21-Runtime verwendet wird, finden Sie unter HandlerStream.java.

Wenn Sie in Ihrer Java-Funktion nur mit grundlegenden und generischen Typen (d. h. String Integer=List,, oderMap) arbeiten, müssen Sie keine Schnittstelle implementieren. Wenn Ihre Funktion beispielsweise eine Map<String, String> Eingabe aufnimmt und eine zurückgibtString, könnten Ihre Klassendefinition und Handler-Signatur wie folgt aussehen:

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

Wenn Sie keine Schnittstelle implementieren, ist das Kontextobjekt außerdem optional. Ihre Klassendefinition und Handler-Signatur könnten beispielsweise wie folgt aussehen:

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

Namenskonventionen für Handler

Wenn Sie für Lambda-Funktionen in Java entweder die RequestHandler RequestStreamHandler OR-Schnittstelle implementieren, muss Ihre Haupthandler-Methode benannt handleRequest werden. Fügen Sie außerdem das @Override Tag über Ihrer handleRequest Methode ein. Wenn Sie Ihre Funktion für Lambda bereitstellen, geben Sie den Haupthandler in der Konfiguration Ihrer Funktion im folgenden Format an:

Für Lambda-Funktionen in Java, die die RequestHandler RequestStreamHandler OR-Schnittstelle nicht implementieren, können Sie einen beliebigen Namen für den Handler verwenden. Wenn Sie Ihre Funktion für Lambda bereitstellen, geben Sie den Haupthandler in der Konfiguration Ihrer Funktion im folgenden Format an:

Definieren Sie das Eingabeereignisobjekt und greifen Sie darauf zu

JSON ist das gebräuchlichste und standardmäßigste Eingabeformat für Lambda-Funktionen. In diesem Beispiel erwartet die Funktion eine Eingabe ähnlich der folgenden:

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

Wenn Sie mit Lambda-Funktionen in Java 17 oder neuer arbeiten, können Sie die Form des erwarteten Eingabeereignisses als Java-Datensatz definieren. In diesem Beispiel definieren wir einen Datensatz innerhalb der OrderHandler Klasse, der ein Order Objekt darstellt:

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

Dieser Datensatz entspricht der erwarteten Eingabeform. Nachdem Sie Ihren Datensatz definiert haben, können Sie eine Handler-Signatur schreiben, die eine JSON-Eingabe aufnimmt, die der Datensatzdefinition entspricht. Die Java-Laufzeit deserialisiert diesen JSON automatisch in ein Java-Objekt. Sie können dann auf die Felder des Objekts zugreifen. Zum Beispiel holt event.orderId den Wert von orderId aus der ursprünglichen Eingabe.

Andere Eingabe-Ereignistypen

Es gibt viele mögliche Eingabeereignisse für Lambda-Funktionen in Java:

Zugreifen auf und Verwenden des Lambda-Kontextobjekts

Das Lambda-Kontextobjekt enthält Informationen über Aufruf, Funktion und Ausführungsumgebung. In diesem Beispiel ist das Kontextobjekt vom Typ com.amazonaws.services.lambda.runtime.Context und das zweite Argument der Haupthandlerfunktion.

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

Wenn Ihre Klasse entweder die RequestStreamHandlerSchnittstelle RequestHandleroder implementiert, ist das Kontextobjekt ein erforderliches Argument. Andernfalls ist das Kontextobjekt optional. Weitere Hinweise zu gültigen akzeptierten Handlersignaturen finden Sie unterGültige Klassendefinitionen für Java-Handler.

Wenn Sie mithilfe des AWS SDK andere Dienste aufrufen, ist das Kontextobjekt in einigen wichtigen Bereichen erforderlich. Um beispielsweise Funktionsprotokolle für Amazon zu erstellen CloudWatch, können Sie die context.getLogger() Methode verwenden, um ein LambdaLogger Objekt für die Protokollierung abzurufen. In diesem Beispiel können wir den Logger verwenden, um eine Fehlermeldung zu protokollieren, falls die Verarbeitung aus irgendeinem Grund fehlschlägt:

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

Außerhalb der Protokollierung können Sie das Kontextobjekt auch zur Funktionsüberwachung verwenden. Weitere Informationen über das Kontextobjekt finden Sie unter Verwenden des Lambda-Kontextobjekts zum Abrufen von Java-Funktionsinformationen.

Verwenden Sie das AWS SDK for Java v2 in Ihrem Handler

Oft verwenden Sie Lambda-Funktionen, um mit anderen AWS Ressourcen zu interagieren oder diese zu aktualisieren. Die einfachste Möglichkeit, eine Schnittstelle zu diesen Ressourcen herzustellen, ist die Verwendung des AWS SDK for Java v2.

Um Ihrer Funktion SDK-Abhängigkeiten hinzuzufügen, fügen Sie sie zu Ihrer build.gradle für Gradle oder Ihrer pom.xml Datei für Maven hinzu. Wir empfehlen, nur die Bibliotheken hinzuzufügen, die Sie für Ihre Funktion benötigen. Im Beispielcode zuvor haben wir die software.amazon.awssdk.services.s3 Bibliothek verwendet. In Gradle können Sie diese Abhängigkeit hinzufügen, indem Sie die folgende Zeile im Abschnitt Abhängigkeiten Ihres build.gradle hinzufügen:

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

Fügen Sie in Maven die folgenden Zeilen in den <dependencies> Abschnitt Ihres ein: pom.xml

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

Importieren Sie dann die Abhängigkeiten direkt in Ihre Java-Klasse:

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

Der Beispielcode initialisiert dann einen Amazon S3 S3-Client wie folgt:

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

In diesem Beispiel haben wir unseren Amazon S3 S3-Client außerhalb der Haupthandlerfunktion initialisiert, um zu vermeiden, dass wir ihn jedes Mal initialisieren müssen, wenn wir unsere Funktion aufrufen. Nachdem Sie Ihren SDK-Client initialisiert haben, können Sie ihn verwenden, um mit anderen Diensten zu interagieren. AWS Der Beispielcode ruft die Amazon S3 PutObject-API wie folgt auf:

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)));

Zugriff auf Umgebungsvariablen

In Ihrem Handler-Code können Sie mithilfe der System.getenv() Methode auf beliebige Umgebungsvariablen verweisen. In diesem Beispiel verweisen wir mit der folgenden Codezeile auf die definierte RECEIPT_BUCKET-Umgebungsvariable:

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

Verwenden des globalen Zustands

Lambda führt Ihren statischen Code und den Klassenkonstruktor während der Initialisierungsphase aus, bevor Ihre Funktion zum ersten Mal aufgerufen wird. Ressourcen, die während der Initialisierung erstellt wurden, bleiben zwischen Aufrufen im Speicher, sodass Sie sie nicht bei jedem Aufruf Ihrer Funktion neu erstellen müssen.

Im Beispielcode befindet sich der S3-Client-Initialisierungscode außerhalb der Haupthandler-Methode. Die Laufzeit initialisiert den Client, bevor die Funktion ihr erstes Ereignis verarbeitet, was zu längeren Verarbeitungszeiten führen kann. Nachfolgende Ereignisse sind viel schneller, da Lambda den Client nicht erneut initialisieren muss.

Bewährte Codemethoden für Java-Lambda-Funktionen

Halten Sie sich an die Richtlinien in der folgenden Liste, um beim Erstellen Ihrer Lambda-Funktionen die besten Codierungspraktiken anzuwenden: