Tentukan pengendali fungsi Lambda di Java

Handler fungsi Lambda Anda adalah metode dalam kode fungsi Anda yang memproses peristiwa. Saat fungsi Anda diaktifkan, Lambda menjalankan metode handler. Fungsi Anda berjalan sampai handler mengembalikan respons, keluar, atau batas waktu.

Halaman ini menjelaskan cara bekerja dengan penangan fungsi Lambda di Java, termasuk opsi untuk penyiapan proyek, konvensi penamaan, dan praktik terbaik. Halaman ini juga menyertakan contoh fungsi Java Lambda yang mengambil informasi tentang pesanan, menghasilkan tanda terima file teks, dan menempatkan file ini dalam bucket Amazon Simple Storage Service (Amazon S3). Untuk informasi tentang cara menerapkan fungsi Anda setelah menulisnya, lihat Deploy fungsi Java Lambda dengan arsip file .zip atau JAR atauDeploy fungsi Java Lambda dengan gambar kontainer.

Menyiapkan proyek handler Java Anda

Saat bekerja dengan fungsi Lambda di Java, prosesnya melibatkan penulisan kode Anda, mengkompilasinya, dan menyebarkan artefak yang dikompilasi ke Lambda. Anda dapat menginisialisasi proyek Java Lambda dengan berbagai cara. Misalnya, Anda dapat menggunakan alat seperti Maven Archetype untuk fungsi Lambda, perintah AWS SAM CLI sam init, atau bahkan pengaturan proyek Java standar di IDE pilihan Anda, seperti IntelliJ IDEA atau Visual Studio Code. Atau, Anda dapat membuat struktur file yang diperlukan secara manual.

Proyek fungsi Java Lambda yang khas mengikuti struktur umum ini:

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

Anda dapat menggunakan Maven atau Gradle untuk membangun proyek dan mengelola dependensi.

Logika handler utama untuk fungsi Anda berada di file Java di bawah src/main/java/example direktori. Dalam contoh di halaman ini, kami memberi nama file iniOrderHandler.java. Terlepas dari file ini, Anda dapat menyertakan kelas Java tambahan sesuai kebutuhan. Saat menerapkan fungsi Anda ke Lambda, pastikan Anda menentukan kelas Java yang berisi metode handler utama yang harus dipanggil Lambda selama pemanggilan.

Contoh kode fungsi Java Lambda

Contoh berikut kode fungsi Java 21 Lambda mengambil informasi tentang pesanan, menghasilkan tanda terima file teks, dan menempatkan file ini dalam bucket 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.javaFile ini berisi bagian kode berikut:

Agar fungsi ini berfungsi dengan baik, peran pelaksanaannya harus memungkinkan s3:PutObject tindakan. Juga, pastikan Anda mendefinisikan variabel RECEIPT_BUCKET lingkungan. Setelah pemanggilan berhasil, bucket Amazon S3 harus berisi file tanda terima.

Definisi kelas yang valid untuk penangan Java

Untuk menentukan kelas Anda, pustaka aws-lambda-java-core mendefinisikan dua antarmuka untuk metode handler. Gunakan antarmuka yang disediakan untuk menyederhanakan konfigurasi handler dan memvalidasi tanda tangan metode pada waktu kompilasi.

Antarmuka RequestHandler adalah jenis generik yang mengambil dua parameter: jenis input dan jenis output. Kedua jenis tersebut harus berupa objek. Dalam contoh ini, OrderHandler kelas kami mengimplementasikanRequestHandler<OrderHandler.Order, String>. Jenis input adalah Order catatan yang kita definisikan dalam kelas, dan jenis keluarannya adalahString.

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

Ketika Anda menggunakan antarmuka ini, runtime Java mendeserialisasi peristiwa ke objek dengan tipe input, dan membuat serial output menjadi teks. Gunakan antarmuka ini saat serialisasi bawaan bekerja dengan tipe input dan output Anda.

Untuk menggunakan serialisasi Anda sendiri, Anda dapat menerapkan RequestStreamHandler antarmuka. Dengan antarmuka ini, Lambda melewatkan aliran input dan aliran output ke handler Anda. Handler membaca byte dari aliran input, menuliskan aliran output, dan mengembalikan pembatalan. Untuk contoh ini menggunakan runtime Java 21, lihat HandlerStream.java.

Jika Anda hanya bekerja dengan tipe dasar dan generik (yaituString,Integer,List, atauMap) dalam fungsi Java Anda, Anda tidak perlu mengimplementasikan antarmuka. Misalnya, jika fungsi Anda mengambil Map<String, String> input dan mengembalikan aString, definisi kelas dan tanda tangan handler Anda mungkin terlihat seperti berikut:

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

Selain itu, ketika Anda tidak mengimplementasikan antarmuka, objek konteks bersifat opsional. Misalnya, definisi kelas dan tanda tangan handler Anda mungkin terlihat seperti berikut:

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

Konvensi penamaan handler

Untuk fungsi Lambda di Java, jika Anda mengimplementasikan RequestStreamHandler antarmuka RequestHandler or, metode handler utama Anda harus diberi handleRequest nama. Juga, sertakan @Override tag di atas handleRequest metode Anda. Saat Anda menerapkan fungsi Anda ke Lambda, tentukan handler utama dalam konfigurasi fungsi Anda dalam format berikut:

Untuk fungsi Lambda di Java yang tidak mengimplementasikan RequestStreamHandler antarmuka RequestHandler or, Anda dapat menggunakan nama apa pun untuk handler. Saat Anda menerapkan fungsi Anda ke Lambda, tentukan handler utama dalam konfigurasi fungsi Anda dalam format berikut:

Mendefinisikan dan mengakses objek peristiwa input

JSON adalah format input yang paling umum dan standar untuk fungsi Lambda. Dalam contoh ini, fungsi mengharapkan input yang mirip dengan berikut ini:

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

Saat bekerja dengan fungsi Lambda di Java 17 atau yang lebih baru, Anda dapat menentukan bentuk peristiwa input yang diharapkan sebagai catatan Java. Dalam contoh ini, kita mendefinisikan catatan dalam OrderHandler kelas untuk mewakili Order objek:

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

Catatan ini cocok dengan bentuk input yang diharapkan. Setelah Anda menentukan catatan Anda, Anda dapat menulis tanda tangan handler yang mengambil input JSON yang sesuai dengan definisi rekaman. Runtime Java secara otomatis mendeserialisasi JSON ini menjadi objek Java. Anda kemudian dapat mengakses bidang objek. Misalnya, event.orderId mengambil nilai orderId dari input asli.

Jenis acara masukan lainnya

Ada banyak kemungkinan peristiwa input untuk fungsi Lambda di Java:

Mengakses dan menggunakan objek konteks Lambda

Objek konteks Lambda berisi informasi tentang pemanggilan, fungsi, dan lingkungan eksekusi. Dalam contoh ini, objek konteks adalah tipecom.amazonaws.services.lambda.runtime.Context, dan merupakan argumen kedua dari fungsi handler utama.

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

Jika kelas Anda mengimplementasikan RequestStreamHandler antarmuka RequestHandler atau, objek konteks adalah argumen yang diperlukan. Jika tidak, objek konteks bersifat opsional. Untuk informasi selengkapnya tentang tanda tangan penangan yang diterima yang valid, lihatDefinisi kelas yang valid untuk penangan Java.

Jika Anda melakukan panggilan ke layanan lain menggunakan AWS SDK, objek konteks diperlukan di beberapa area utama. Misalnya, untuk menghasilkan log fungsi untuk Amazon CloudWatch, Anda dapat menggunakan context.getLogger() metode untuk mendapatkan LambdaLogger objek untuk logging. Dalam contoh ini, kita dapat menggunakan logger untuk mencatat pesan kesalahan jika pemrosesan gagal karena alasan apa pun:

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

Di luar logging, Anda juga dapat menggunakan objek konteks untuk pemantauan fungsi. Untuk informasi selengkapnya tentang objek konteks, lihatMenggunakan objek konteks Lambda untuk mengambil informasi fungsi Java.

Menggunakan AWS SDK untuk Java v2 di handler Anda

Seringkali, Anda akan menggunakan fungsi Lambda untuk berinteraksi dengan atau membuat pembaruan ke AWS sumber daya lain. Cara paling sederhana untuk berinteraksi dengan sumber daya ini adalah dengan menggunakan AWS SDK untuk Java v2.

Untuk menambahkan dependensi SDK ke fungsi Anda, tambahkan dependensi tersebut di build.gradle untuk Gradle atau pom.xml file untuk Maven. Kami menyarankan hanya menambahkan pustaka yang Anda butuhkan untuk fungsi Anda. Dalam contoh kode sebelumnya, kami menggunakan per software.amazon.awssdk.services.s3 pustakaan. Di Gradle, Anda dapat menambahkan dependensi ini dengan menambahkan baris berikut di bagian dependensi Anda: build.gradle

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

Di Maven, tambahkan baris berikut di <dependencies> bagian Andapom.xml:

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

Kemudian, impor dependensi langsung di kelas Java Anda:

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

Kode contoh kemudian menginisialisasi klien Amazon S3 sebagai berikut:

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

Dalam contoh ini, kami menginisialisasi klien Amazon S3 kami di luar fungsi handler utama untuk menghindari keharusan menginisialisasi setiap kali kami memanggil fungsi kami. Setelah menginisialisasi klien SDK, Anda kemudian dapat menggunakannya untuk berinteraksi dengan AWS layanan lain. Kode contoh memanggil PutObject API Amazon S3 sebagai berikut:

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

Mengakses variabel lingkungan

Dalam kode handler Anda, Anda dapat mereferensikan variabel lingkungan apa pun dengan menggunakan System.getenv() metode ini. Dalam contoh ini, kita mereferensi RECEIPT_BUCKET kan variabel lingkungan yang ditentukan menggunakan baris kode berikut:

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

Menggunakan status global

Lambda menjalankan kode statis Anda dan konstruktor kelas selama fase in isialisasi sebelum memanggil fungsi Anda untuk pertama kalinya. Sumber daya yang dibuat selama inisialisasi tetap berada di memori di antara pemanggilan, sehingga Anda dapat menghindari keharusan membuatnya setiap kali Anda memanggil fungsi Anda.

Dalam kode contoh, kode inisialisasi klien S3 berada di luar metode handler utama. Runtime menginisialisasi klien sebelum fungsi menangani peristiwa pertamanya, dan klien tetap tersedia untuk digunakan kembali di semua pemanggilan.

Praktik kode terbaik untuk fungsi Java Lambda

Patuhi pedoman dalam daftar berikut untuk menggunakan praktik pengkodean terbaik saat membangun fungsi Lambda Anda:

Manfaatkan penggunaan kembali lingkungan eksekusi untuk meningkatkan kinerja fungsi Anda. Inisialisasi klien SDK dan koneksi basis data di luar fungsi handler, dan lakukan caching aset statis secara lokal di direktori /tmp. Invokasi selanjutnya yang diproses oleh instans yang sama dari fungsi Anda dapat menggunakan kembali sumber daya ini. Ini menghemat biaya dengan mengurangi waktu pengoperasian fungsi.

Untuk menghindari potensi kebocoran data di seluruh invokasi, jangan menggunakan lingkungan eksekusi untuk menyimpan data pengguna, peristiwa, atau informasi lainnya implikasi keamanan. Jika fungsi Anda bergantung pada status yang dapat disenyapkan yang tidak dapat disimpan dalam memori di dalam handler, pertimbangkan untuk membuat fungsi terpisah atau versi terpisah dari fungsi untuk setiap pengguna.

Gunakan direktif keep-alive untuk mempertahankan koneksi yang persisten. Lambda membersihkan koneksi idle dari waktu ke waktu. Mencoba menggunakan ulang koneksi idle saat mengidentifikasi suatu fungsi akan menyebabkan kesalahan koneksi. Untuk mempertahankan koneksi yang persisten, gunakan arahan tetap aktif yang berkaitan dengan runtime Anda. Sebagai contoh, lihat Menggunakan Kem bali Koneksi dengan Keep-Alive in Node.js.

Gunakan variabel lingkungan untuk meneruskan parameter operasional ke fungsi Anda. Misalnya, jika Anda ingin menulis ke bucket Amazon S3 alih-alih melakukan hard-coding nama bucket yang Anda tulis, konfigurasikan nama bucket sebagai variabel lingkungan.

Hindari menggunakan pemanggilan rekursif dalam fungsi Lambda Anda, di mana fungsi memanggil dirinya sendiri atau memulai proses yang dapat memanggil fungsi lagi. Hal ini dapat menyebabkan volume invokasi fungsi yang tidak diinginkan dan peningkatan biaya. Jika Anda melihat volume pemanggilan yang tidak diinginkan, setel fungsi reservasi konkurensi ke 0 segera untuk membatasi semua pemanggilan ke fungsi, saat Anda memperbarui kode.

Jangan gunakan API non-publik yang tidak terdokumentasi dalam kode fungsi Lambda Anda. Untuk runtime AWS Lambda terkelola, Lambda secara berkala menerapkan pembaruan keamanan dan fungsional ke API internal Lambda. Pembaruan API internal ini mungkin tidak kompatibel ke belakang, yang menyebabkan konsekuensi yang tidak diinginkan seperti kegagalan pemanggilan jika fungsi Anda memiliki ketergantungan pada API non-publik ini. Lihat referensi API untuk daftar API yang tersedia untuk umum.

Tulis kode idempotent. Menulis kode idempotent untuk fungsi Anda memastikan bahwa peristiwa duplikat ditangani dengan cara yang sama. Kode Anda harus memvalidasi peristiwa dengan benar dan menangani peristiwa duplikat dengan anggun. Untuk informasi lebih lanjut, lihat Bagaimana cara membuat fungsi Lambda saya idempoten? .