Java の Lambda 関数ハンドラーの定義

Lambda 関数ハンドラーは、イベントを処理する関数コード内のメソッドです。関数が呼び出されると、Lambda はハンドラーメソッドを実行します。関数は、ハンドラーが応答を返すか、終了するか、タイムアウトするまで実行されます。

このページでは、プロジェクトのセットアップオプション、命名規則、ベストプラクティスなど、Java で Lambda 関数ハンドラーを使用する方法について説明します。このページには、注文に関する情報を取得し、テキストファイル受信を生成し、このファイルを Amazon Simple Storage Service (Amazon S3) バケットに配置する Java Lambda 関数の例も含まれています。関数を書き込んだ後にデプロイする方法については、「.zip または JAR ファイルアーカイブで Java Lambda 関数をデプロイする」または「コンテナイメージを使用した Java Lambda 関数のデプロイ」を参照してください。

Java ハンドラープロジェクトのセットアップ

Java で Lambda 関数を使用する場合、このプロセスにはコードの記述、コンパイル、コンパイルされたアーティファクトの Lambda へのデプロイが含まれます。Java Lambda プロジェクトはさまざまな方法で初期化できます。例えば、Lambda 関数の Maven Archetype、AWS SAM CLI sam init コマンド、または IntelliJ IDEA や Visual Studio Code といった任意の IDE での標準 Java プロジェクト設定などのツールを使用できます。または、必要なファイル構造を手動で作成することもできます。

一般的な Java Lambda 関数プロジェクトは、次の一般的な構造に従います。

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

Maven または Gradle を使用してプロジェクトを構築し、依存関係を管理できます。

関数のメインハンドラーロジックは、src/main/java/example ディレクトリの Java ファイルにあります。このページの例では、このファイルに OrderHandler.java という名前を付けます。このファイルとは別に、必要に応じて追加の Java クラスを含めることができます。関数を Lambda にデプロイする際は、呼び出し中に Lambda が呼び出すメインハンドラーメソッドを含む Java クラスを必ず指定してください。

Java Lambda 関数のコードの例

以下の Java 21 Lambda 関数コードの例では、注文に関する情報を取得し、テキストファイル受信を生成し、このファイルを 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);
        }
    }
}

この OrderHandler.java ファイルには以下のコードのセクションが含まれます:

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

この関数が正しく機能するには、実行ロールで s3:PutObject アクションを許可する必要があります。また、必ず RECEIPT_BUCKET 環境変数を定義してください。呼び出しに成功したら、Amazon S3 バケットに受信ファイルが含まれているはずです。

Java ハンドラーの有効なクラス定義

クラスを定義するために、aws-lambda-java-core ライブラリは、ハンドラーメソッドの 2 つのインターフェイスを定義します。用意されているインターフェイスを使用して、ハンドラー設定をシンプルにし、コンパイル時にメソッドシグネチャを検証します。

RequestHandler インターフェイスは、入力タイプと出力タイプの 2 つのパラメータを受け取る汎用タイプです。どちらのタイプもオブジェクトであることが必要です。この例では、OrderHandler クラスは RequestHandler<OrderHandler.Order, String> を実装します。入力タイプはクラス内で定義する Order レコードで、出力タイプは String です。

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

このインターフェイスを使用すると、Java ランタイムはイベントを入力タイプのオブジェクトに逆シリアル化し、出力をテキストにシリアル化します。組み込みのシリアル化が入力タイプと出力タイプで機能する場合は、このインターフェイスを使用します。

独自のシリアル化を使用するために、RequestStreamHandler インターフェイスを実装できます。このインターフェイスでは、Lambda はハンドラーに入力ストリームと出力ストリームを渡します。ハンドラーは、入力ストリームからバイトを読み取り、出力ストリームに書き込み、void を返します。Java 21 ランタイムを使用したこの例については、「HandlerStream.java」を参照してください。

Java 関数で基本型と汎用型 (String、Integer、=List または Map) のみを使用している場合は、インターフェイスを実装する必要はありません。例えば、関数が Map<String, String> 入力を受け取り、String を返す場合、クラス定義とハンドラー署名は次のようになります。

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

さらに、インターフェイスを実装しない場合、コンテキストオブジェクトはオプションです。例えば、クラス定義とハンドラー署名は次のようになります。

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

ハンドラーの命名規則

Java の Lambda 関数では、RequestHandler または RequestStreamHandler インターフェイスを実装する場合、メインハンドラーメソッドの名前は handleRequest である必要があります。また、handleRequest メソッドの上に @Override タグを含めます。関数を Lambda にデプロイするときは、関数の設定でメインハンドラーを次の形式で指定します。

RequestHandler または RequestStreamHandler インターフェイスを実装しない Java の Lambda 関数の場合、ハンドラーには任意の名前を使用できます。関数を Lambda にデプロイするときは、関数の設定でメインハンドラーを次の形式で指定します。

入力イベントオブジェクトの定義とアクセス

JSON は Lambda 関数の最も一般的な標準入力形式です。この例では、関数は以下のような入力を想定しています:

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

Java 17 以降で Lambda 関数を使用する場合、予想される入力イベントの形状を Java レコードとして定義できます。この例では、Order オブジェクトを表すレコードを OrderHandler クラス内で定義します。

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

このレコードは、予想される入力形状と一致します。レコードを定義したら、レコード定義に準拠する JSON 入力を取り込むハンドラー署名を記述できます。Java ランタイムは、この JSON を Java オブジェクトに自動的に逆シリアル化します。その後、オブジェクトのフィールドにアクセスできます。例えば、event.orderId は元の入力から orderId の値を取得します。

その他の入力イベントタイプ

Java の Lambda 関数には、多くの入力イベントが考えられます。

Lambda コンテキストオブジェクトへのアクセスと使用

Lambda コンテキストオブジェクトには、呼び出し、関数、および実行環境に関する情報が含まれます。この例では、コンテキストオブジェクトは com.amazonaws.services.lambda.runtime.Context 型で、メインハンドラー関数の 2 番目の引数です。

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

クラスで RequestHandler インターフェイスまたは RequestStreamHandler インターフェイスを実装する場合、コンテキストオブジェクトは必須引数です。それ以外の場合、コンテキストオブジェクトはオプションです。有効な受理されたハンドラー署名の詳細については、「Java ハンドラーの有効なクラス定義」を参照してください。

AWS SDK を使用して他のサービスを呼び出す場合、コンテキストオブジェクトはいくつかの重要な領域で必要です。例えば、Amazon CloudWatch の関数ログを生成するには、context.getLogger() メソッドを使用してログ記録用の LambdaLogger オブジェクトを取得できます。この例では、何らかの理由で処理が失敗した場合、ロガーを使用してエラーメッセージをログに記録できます。

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

ログ記録以外では、関数のモニタリングにコンテキストオブジェクトを使用することもできます。コンテキストオブジェクトの詳細については、「Lambda コンテキストオブジェクトを使用して Java 関数の情報を取得する」を参照してください。

ハンドラーでの AWS SDK for Java v2 の使用

多くの場合、Lambda 関数を使用して、他の AWS リソースとやり取りしたり、更新したりします。これらのリソースとインターフェイスする最も簡単な方法は、AWS SDK for Java v2 を使用することです。

SDK 依存関係を関数に追加するには、Gradle の場合は build.gradle に、Maven の場合は pom.xml ファイルに追加します。関数に必要なライブラリのみを追加することをお勧めします。前のコード例では、software.amazon.awssdk.services.s3 ライブラリを使用しました。Gradle では、build.gradle の依存関係セクションに次の行を追加することで、この依存関係を追加できます。

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

Maven で、pom.xml の <dependencies> セクションに次の行を追加します。

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

次に、依存関係を Java クラスに直接インポートします。

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

次に、コード例は次のように Amazon S3 クライアントを初期化します。

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

この例では、関数を呼び出すたびに Amazon S3 クライアントを初期化する必要がないように、メインハンドラー関数の外で Amazon S3 クライアントを初期化しました。SDK クライアントを初期化したら、SDK クライアントを使用して他の AWS サービスとやり取りできます。サンプルコードは、以下のように Amazon S3 PutObject API を呼び出します。

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

環境変数にアクセスする

ハンドラーコードでは、System.getenv() メソッドを使用して任意の環境変数を参照できます。この例では、以下のコード行を使用して、定義された RECEIPT_BUCKET 環境変数を参照します:

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

グローバルな状態を使用する

Lambda は、関数を初めて呼び出す前の初期化フェーズで静的コードとクラスコンストラクターを実行します。初期化中に作成されたリソースは呼び出し間でメモリに保持されるため、関数を呼び出すたびにリソースを作成する必要がなくなります。

コード例では、S3 クライアント初期化コードはメインハンドラーメソッドの外にあります。ランタイムは、関数が最初のイベントを処理する前にクライアントを初期化し、クライアントはすべての呼び出しで再利用できます。

Java Lambda 関数のコードのベストプラクティス

Lambda 関数をビルドするときは、次のリストのガイドラインに従って、コーディングのベストプラクティスを実行してください。