Node.js の Lambda 関数ハンドラーの定義 - AWS Lambda
プロジェクトをセットアップする関数の例ハンドラーの命名規則入力イベントオブジェクト有効なハンドラーパターンJavaScript のための SDK の使用環境変数にアクセスするグローバルな状態を使用するベストプラクティス

Node.js の Lambda 関数ハンドラーの定義

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

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

Node.js ハンドラープロジェクトのセットアップ

Node.js Lambda プロジェクトを初期化するには、複数の方法があります。例えば、npm を使用して標準の Node.js プロジェクト、AWS SAM アプリケーション、AWS CDK アプリケーションなどを作成できます。

npm を使用してプロジェクトを作成するには:

npm init

このコマンドはプロジェクトを初期化し、プロジェクトのメタデータと依存関係を管理する package.json ファイルを生成します。

関数コードは .js または .mjs JavaScript ファイルにあります。次の例では、ES モジュールハンドラーを使用するため、このファイルに index.mjs という名前を付けます。Lambda は、ES モジュールと CommonJS ハンドラーの両方をサポートしています。詳細については、「ES モジュールとしての関数ハンドラーの指定」を参照してください。

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

/project-root
  ├── index.mjs — Contains main handler
  ├── package.json — Project metadata and dependencies
  ├── package-lock.json — Dependency lock file
  └── node_modules/ — Installed dependencies

Node.js Lambda 関数のコードの例

以下の Lambda 関数コードの例では、注文に関する情報を取得し、テキストファイル受信を生成し、このファイルを Amazon S3 バケットに配置します。

注記

この例では、ES モジュールハンドラーを使用します。Lambda は、ES モジュールと CommonJS ハンドラーの両方をサポートしています。詳細については、「ES モジュールとしての関数ハンドラーの指定」を参照してください。

例 index.mjs Lambda 関数
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

// Initialize the S3 client outside the handler for reuse
const s3Client = new S3Client();

/**
 * Lambda handler for processing orders and storing receipts in S3.
 * @param {Object} event - Input event containing order details
 * @param {string} event.order_id - The unique identifier for the order
 * @param {number} event.amount - The order amount
 * @param {string} event.item - The item purchased
 * @returns {Promise<string>} Success message
 */
export const handler = async(event) => {
    try {
        // Access environment variables
        const bucketName = process.env.RECEIPT_BUCKET;
        if (!bucketName) {
            throw new Error('RECEIPT_BUCKET environment variable is not set');
        }

        // Create the receipt content and key destination
        const receiptContent = `OrderID: ${event.order_id}\nAmount: $${event.amount.toFixed(2)}\nItem: ${event.item}`;
        const key = `receipts/${event.order_id}.txt`;

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

        console.log(`Successfully processed order ${event.order_id} and stored receipt in S3 bucket ${bucketName}`);
        return 'Success';
    } catch (error) {
        console.error(`Failed to process order: ${error.message}`);
        throw error;
    }
};

/**
 * Helper function to upload receipt to S3
 * @param {string} bucketName - The S3 bucket name
 * @param {string} key - The S3 object key
 * @param {string} receiptContent - The content to upload
 * @returns {Promise<void>}
 */
async function uploadReceiptToS3(bucketName, key, receiptContent) {
    try {
        const command = new PutObjectCommand({
            Bucket: bucketName,
            Key: key,
            Body: receiptContent
        });

        await s3Client.send(command);
    } catch (error) {
        throw new Error(`Failed to upload receipt to S3: ${error.message}`);
    }
}

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

  • import ブロック: このブロックを使用して、AWS SDK クライアントなどの Lambda 関数に必要なライブラリを含めます。

  • const s3Client 宣言: ハンドラー関数の外部で Amazon S3 クライアントを初期化します。これにより、Lambda は初期化フェーズ中にこのコードを実行します。またクライアントは、複数の呼び出しで再利用できるように保持されます。

  • JSDoc コメントブロック: JSDoc アノテーションを使用してハンドラーの入力タイプと出力タイプを定義します。

  • export const handler: Lambda が呼び出すメインハンドラー関数です。関数をデプロイするときは、ハンドラープロパティに index.handler を指定します。Handler プロパティの値は、エクスポートされたハンドラーメソッドのファイル名と名前で、ドットで区切られます。

  • uploadReceiptToS3 関数: これは、メインハンドラー関数によって参照されるヘルパー関数です。

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

ハンドラーの命名規則

関数を設定すると、ハンドラー設定の値はファイル名とエクスポートしたハンドラーメソッドの名前をドットで区切ったものになります。コンソールで作成された関数のデフォルトと、このガイドの例では、index.handler です。これは、index.js または index.mjs ファイルからエクスポートされた handler メソッドを示します。

異なるファイル名または関数ハンドラー名を使用してコンソールで関数を作成する場合は、デフォルトのハンドラー名を編集する必要があります。

関数ハンドラー名を変更するには (コンソール)

  1. Lambda コンソールの [関数] ページを開き、関数を選択します。

  2. [コード] タブを選択します。

  3. [ランタイム設定] ペインまでスクロールして、[編集] を選択します。

  4. [ハンドラー] には、関数ハンドラーの新しい名前を入力します。

  5. [Save] を選択します。

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

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

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

Node.js で Lambda 関数を使用する場合、JSDoc アノテーションを使用して予想される入力イベントの形状を定義できます。この例では、ハンドラーの JSDoc コメントで入力構造を定義します。

/**
 * Lambda handler for processing orders and storing receipts in S3.
 * @param {Object} event - Input event containing order details
 * @param {string} event.order_id - The unique identifier for the order
 * @param {number} event.amount - The order amount
 * @param {string} event.item - The item purchased
 * @returns {Promise<string>} Success message
 */

JSDoc コメントでこれらのタイプを定義すると、コード内のイベントオブジェクトのフィールドに直接アクセスできます。例えば、event.order_id は元の入力から order_id の値を取得します。

Node.js 関数の有効なハンドラーパターン

コールバックを使用する代わりに、async/await を使用して関数ハンドラーを宣言することをお勧めします。async/await は、非同期コードを記述するための簡潔で読みやすい方法であり、ネストされたコールバックや連鎖する promise を必要としません。async/await を使用すると、非同期かつノンブロッキングでありながら、同期コードのように読み取るコードを記述できます。

async/await の使用 (推奨）

async キーワードは関数を非同期としてマークし、await キーワードは Promise が解決されるまで関数の実行を一時停止します。ハンドラーは次の引数を取ります。

async/await パターンの有効な署名は次のとおりです。

  • export const handler = async (event) => { };
  • export const handler = async (event, context) => { };
注記

TypeScript 関数のコードを記述するには、ローカルの統合開発環境 (IDE) またはテキストエディタを使用します。Lambda コンソールでは TypeScript コードを作成できません。

コールバックの使用

コールバックハンドラーは、イベント、コンテキスト、コールバック引数を使用できます。有効な署名は次のとおりです。

  • export const handler = (event, callback) => { };
  • export const handler = (event, context, callback) => { };

コールバック関数は、Error とレスポンスを想定しており、JSON シリアル化可能である必要があります。関数は、イベントループが空になるか、関数がタイムアウトするまで実行を続けます。レスポンスは、すべてのイベントループタスクが完了するまで、呼び出し元に送信されません。関数がタイムアウトした場合は、エラーが返ります。すぐにレスポンスが返るようにランタイムを設定するには、context.callbackWaitsForEmptyEventLoop を false に設定します。

例 – callback を使用した HTTP リクエスト

次の例の関数では、URL をチェックし、ステータスコードを呼び出し元に返します。

import https from "https";
let url = "https://aws.amazon.com/";

export const handler = (event, context, callback) => {
  https.get(url, (res) => {
    callback(null, res.statusCode);
  }).on("error", (e) => {
    callback(Error(e));
  });
};

ハンドラーでの SDK for JavaScript v3 の使用

多くの場合、Lambda 関数を使用して、他の AWS リソースとやり取りしたり、更新したりします。これらのリソースとインターフェイスする最も簡単な方法は、AWS SDK for JavaScript を使用することです。サポートされているすべての Lambda Node.js ランタイムには、SDK for JavaScript バージョン 3 が含まれています。ただし、デプロイパッケージに必要な AWS SDK クライアントを含めることを強くお勧めします。こうすることで、将来的に Lambda ランタイムを更新する際の下位互換性が最大限保持されます。追加のパッケージを含めることができない場合にのみ、ランタイム提供の SDK を使用します (例えば、Lambda コンソールコードエディタまたはインラインコードを AWS CloudFormation テンプレートで使用する場合）。

SDK 依存関係を関数に追加するには、必要な特定の SDK クライアントに npm install コマンドを使用します。サンプルコードでは、Amazon S3 クライアントを使用しました。この依存関係を追加するには、package.json ファイルが格納されているディレクトリで以下のコマンドを実行します。

npm install @aws-sdk/client-s3

関数の例で示すように、関数コードで必要なクライアントとコマンドをインポートします。

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

次に、Amazon S3 クライアントを初期化します。

const s3Client = new S3Client();

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

const command = new PutObjectCommand({
    Bucket: bucketName,
    Key: key,
    Body: receiptContent
});

環境変数にアクセスする

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

// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
    throw new Error('RECEIPT_BUCKET environment variable is not set');
}

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

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

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

Node.js Lambda 関数のコードのベストプラクティス

Lambda 関数を構築するときは、次のガイドラインに従ってください。

  • Lambda ハンドラーをコアロジックから分離します。これにより、関数の単体テストが実行しやすくなります。

  • 関数のデプロイパッケージ内で依存関係を制御します。AWS Lambda 実行環境には多数のライブラリが含まれています。Node.js および Python ランタイムの場合、ライブラリには AWS SDK が含まれます。最新の機能やセキュリティ更新プログラムを有効にするために、Lambda はこれらのライブラリを定期的に更新します。この更新により、Lambda 関数の動作が微妙に変化する場合があります。関数で使用する依存関係を完全に制御するには、すべての依存関係をデプロイパッケージでパッケージングします。

  • 依存関係の複雑さを最小限に抑えます。フレームワークを単純化して、実行環境起動時のロードを高速化します。

  • デプロイパッケージをランタイムに必要な最小限のサイズにします。これにより、呼び出しに先立ってデプロイパッケージをダウンロードして解凍する所要時間が短縮されます。

  • 実行環境の再利用を活用して関数のパフォーマンスを向上させます。関数ハンドラー外で SDK クライアントとデータベース接続を初期化し、静的なアセットを /tmp ディレクトリにローカルにキャッシュします。関数の同じインスタンスで処理された後続の呼び出しは、これらのリソースを再利用できます。これにより、関数の実行時間が短縮され、コストが節約されます。

    呼び出し間でデータが漏れるのを防ぐため、実行環境を使用してセキュリティ上の懸念があるユーザーデータ、イベント、またはその他の情報を保存しないでください。関数がハンドラー内のメモリに保存できない変更可能な状態に依存している場合は、ユーザーごとに個別の関数または個別のバージョンの関数を作成することを検討してください。

  • keep-alive ディレクティブを使用して永続的な接続を維持します。Lambda は、時間の経過とともにアイドル状態の接続を消去します。関数を呼び出すときにアイドル状態の接続を再利用しようとすると、接続エラーが発生します。永続的な接続を維持するには、ランタイムに関連付けられている keep-alive ディレクティブを使用します。例については、「Node.js で Keep-alive を使用して接続を再利用する」を参照してください。

  • 環境変数を使用して、オペレーショナルパラメータを関数に渡します。たとえば、Amazon S3 バケットに書き込む場合、書き込み先のバケット名はハードコーディングせずに、環境変数として設定します。

  • Lambda 関数では、再帰呼び出しを使用しないでください。関数が自身を呼び出すこともあれば、新たに開始されたプロセスで関数が再度呼び出される可能性もあります。これを行うと意図しないボリュームで関数が呼び出され、料金が急増する可能性があります。意図しない呼び出しがいくつも見つかった場合は、すぐに関数の予約済同時実行数を 0 に設定して、コードを更新している間のすべての関数の呼び出しをスロットリングします。

  • Lambda 関数コードで文書化されていない非公開の API を使用しないでください。AWS Lambda マネージドランタイムでは、Lambda が Lambda の内部 API にセキュリティと機能面の更新を定期的に適用します。これらの内部 API 更新には後方互換性がないことがあり、関数にこれらの非公開 API に対する依存関係がある場合、呼び出しの失敗などの意図しない結果につながります。公開されている API のリストについては、「API リファレンス」を参照してください。

  • 冪等性コードを記述します。関数の記述に冪等性コードを使用すると、重複するイベントが同じ方法で処理されるようになります。コードでは、イベントを適切に検証し、重複するイベントを適切に処理する必要があります。詳細については、「Lambda 関数を冪等にするにはどうすればよいですか?」を参照してください。