TypeScriptのLambda関数

TypeScript Lambda Function ジェネレータは、既存のTypeScriptプロジェクトにLambda関数を追加する機能を提供します。

このジェネレータはAWS CDKまたはTerraformのインフラストラクチャ設定を含む新しいTypeScript Lambdaハンドラを作成します。生成されたハンドラは、AWS Lambda Powertools for TypeScriptを使用して、ロギング、AWS X-Rayトレーシング、CloudWatchメトリクスなどの観測可能性を実現し、AWS Lambda PowertoolsのParserを使用したイベントの型安全性（オプション）を提供します。

使用方法

TypeScript Lambda関数の生成

Lambda関数は2つの方法で生成できます:

VSCode

1. インストール Nx Console VSCode Plugin まだインストールしていない場合
2. VSCodeでNxコンソールを開く
3. クリック Generate (UI) "Common Nx Commands"セクションで
4. 検索 @aws/nx-plugin - ts#lambda-function
5. 必須パラメータを入力
6. クリック Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#lambda-function

yarn

yarn nx g @aws/nx-plugin:ts#lambda-function

npm

npx nx g @aws/nx-plugin:ts#lambda-function

bun

bunx nx g @aws/nx-plugin:ts#lambda-function

変更されるファイルを確認するためにドライランを実行することもできます

pnpm

pnpm nx g @aws/nx-plugin:ts#lambda-function --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#lambda-function --dry-run

npm

npx nx g @aws/nx-plugin:ts#lambda-function --dry-run

bun

bunx nx g @aws/nx-plugin:ts#lambda-function --dry-run

オプション

パラメータ	型	デフォルト	説明
project 必須	string	-	Lambda関数を追加するプロジェクト
functionName 必須	string	-	追加する関数の名前
functionPath	string	-	関数を追加するプロジェクトソースディレクトリ内のオプションのサブディレクトリ
eventSource	string	Any	Lambda関数に使用するオプションのイベントソーススキーマ
iacProvider	string	Inherit	優先するIaCプロバイダー。デフォルトでは、初期選択から継承されます。

ジェネレータの出力

ジェネレータはプロジェクトに以下のファイルを追加します:

• Directory<project-name>

  • Directorysrc/

    • <lambda-function>.ts 関数の実装

functionPathオプションが指定された場合、ジェネレータはプロジェクトのソースディレクトリ内の指定パスにハンドラを追加します:

• Directory<project-name>

  • Directorysrc/

    • Directory<custom-path>/

      • <function-name>.ts 関数の実装

インフラストラクチャ

このジェネレータは選択した iacProvider に基づいてInfrastructure as Codeを生成するため、packages/common に関連するCDKコンストラクトまたはTerraformモジュールを含むプロジェクトを作成します。

共通のInfrastructure as Codeプロジェクトは以下の構造を持ちます：

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用コンストラクト

      • …
    • Directorycore/ app 内のコンストラクトで再利用される汎用コンストラクト

      • …
    • index.ts app からコンストラクトをエクスポートするエントリーポイント
  • project.json プロジェクトのビルドターゲットと設定

生成されたプロジェクト

このプロジェクトは ts#project ジェネレータを使用して生成されているため、同じビルドターゲットを設定します。

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用Terraformモジュール

      • …
    • Directorycore/ app 内のモジュールで再利用される汎用モジュール

      • …
  • project.json プロジェクトのビルドターゲットと設定

生成されたプロジェクト

このプロジェクトは terraform#project ジェネレータを使用して生成されているため、同じビルドターゲットを設定します。

ジェネレータは選択したiacProviderに基づいて関数をデプロイするためのインフラストラクチャコードを作成します:

CDK

ジェネレータはCDKコンストラクトを作成します。このコンストラクトはpackages/common/constructs/src/app/lambda-functionsディレクトリに配置され、関数のデプロイに使用できます。

Terraform

ジェネレータはTerraformモジュールを作成します。このモジュールはpackages/common/terraform/src/app/lambda-functions/<function-name>ディレクトリに配置され、関数のデプロイに使用できます。

関数の実装

メインの関数実装は<function-name>.tsにあります。以下は実装例です:

import { parser } from '@aws-lambda-powertools/parser/middleware';
import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
import middy from '@middy/core';
import { Tracer } from '@aws-lambda-powertools/tracer';
import { captureLambdaHandler } from '@aws-lambda-powertools/tracer/middleware';
import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware';
import { Logger } from '@aws-lambda-powertools/logger';
import { Metrics } from '@aws-lambda-powertools/metrics';
import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
import { z } from 'zod';

process.env.POWERTOOLS_METRICS_NAMESPACE = 'MyFunction';
process.env.POWERTOOLS_SERVICE_NAME = 'MyFunction';

const tracer = new Tracer();
const logger = new Logger();
const metrics = new Metrics();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  logger.info('Received event', event);

  // TODO: 実装を追加
};

export const handler = middy()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .use(parser({ schema: EventBridgeSchema }))
  .handler(myFunction);

ジェネレータは以下の機能を自動的に設定します:

1. 拡張Lambda機能のためのMiddyミドルウェアスタック
2. 観測可能性のためのAWS Lambda Powertools統合
3. CloudWatchを使ったメトリクス収集
4. パーサーミドルウェアを使用した型安全性
5. Rolldownによる最適化されたデプロイパッケージのバンドリング

AWS Lambda Powertoolsによる観測可能性

ロギング

ジェネレータはMiddyミドルウェアを通じた自動コンテキスト注入付きの構造化ロギングを設定します。

export const handler = middy()
  .use(injectLambdaContext(logger))
  .handler(myFunction);

トレーシング

AWS X-RayトレーシングはcaptureLambdaHandlerミドルウェアで自動設定されます。カスタムサブセグメントを追加できます:

const tracer = new Tracer();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  // 新しいサブセグメントを作成
  const subsegment = tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // ここにロジックを実装
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

export const handler = middy()
  .use(captureLambdaHandler(tracer))
  .handler(myFunction);

メトリクス

CloudWatchメトリクスはlogMetricsミドルウェアでリクエストごとに自動収集されます。カスタムメトリクスを追加できます:

const metrics = new Metrics();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  metrics.addMetric("CustomMetric", MetricUnit.Count, 1);
  metrics.addMetric("ProcessingTime", MetricUnit.Milliseconds, processingTime);
};

export const handler = middy()
  .use(logMetrics(metrics))
  .handler(myFunction);

型安全性

Lambda関数生成時にeventSourceを選択した場合、関数はAWS Lambda Powertoolsのparserミドルウェアで計装されます。例:

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  event.detail // <- IDEのオートコンプリートが効く型安全なアクセス
};

export const handler = middy()
  .use(parser({ schema: EventBridgeSchema }))
  .handler(myFunction);

これにより、コンパイル時の型安全性とランタイムバリデーションが提供されます。

エラーハンドリング

イベントがスキーマに適合しない場合にハンドラがエラーをスローしないようにするには、safeParseオプションを使用できます。

カスタムイベントデータ

DynamoDBストリームやEventBridgeイベント内のカスタムデータなど、ネストされたカスタムデータがある場合は、Envelopesを使用して型安全性を確保できます。

イベントの型指定を希望しない場合、eventSourceにAnyを選択すると、イベントパラメータはany型になります。

バンドリング

ジェネレーターは自動的に Rolldown を使用する bundle ターゲットを設定します。このターゲットはデプロイメントパッケージの作成に使用されます：

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Rolldownの設定はrolldown.config.tsに記述され、生成するバンドルごとにエントリを定義します。Rolldownは定義された複数のバンドルを並行して作成する処理を管理します。

カスタム設定

rolldown.config.tsでRolldownの設定を調整可能です。例えばファイルパスに依存するためバンドルできない依存関係がある場合、externalモジュールのリストに追加できます。

関数のデプロイ

このジェネレータは選択した iacProvider に基づいてCDKまたはTerraformのインフラストラクチャーコードを生成します。生成されたコードを使用して関数をデプロイできます。

CDK

このジェネレータは common/constructs フォルダに関数をデプロイするためのCDKコンストラクトを作成します。CDKアプリケーションで以下のように使用できます：

import { MyProjectMyFunction } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // スタックに関数を追加
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

これにより以下が設定されます：

1. AWS Lambda関数
2. CloudWatchロググループ
3. X-Rayトレーシング設定
4. CloudWatchメトリクスネームスペース

この関数は任意のLambdaイベントソースのターゲットとして使用できます：

イベントソースの一致

ハンドラー関数内でイベントが適切に処理されるよう、イベントソースが選択した eventSource オプションと一致していることを確認してください。

以下の例はEventBridgeを使用してスケジュールでLambda関数を起動するCDKコードを示しています：

import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
import { MyProjectMyFunction } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // スタックに関数を追加
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // EventBridgeスケジュールルールに関数を追加
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}

Terraform

このジェネレータは common/terraform フォルダに関数をデプロイするためのTerraformモジュールを作成します。Terraform設定で以下のように使用できます：

module "my_project_my_function" {
  source = "../../common/terraform/src/app/lambda-functions/my-project-my-function"

  # Lambda関数の環境変数
  env = {
    SOME_VARIABLE = "some value"
  }

  # 追加のIAMポリシーが必要な場合
  additional_iam_policy_statements = [
    # 関数に必要な追加の権限を記述
  ]
}

これにより以下が設定されます：

1. AWS Lambda関数
2. CloudWatchロググループ
3. X-Rayトレーシング設定
4. CloudWatchメトリクスネームスペース

この関数は任意のLambdaイベントソースのターゲットとして使用できます。以下の例はEventBridgeを使用してスケジュールでLambda関数を起動するTerraformコードを示しています：

# スケジュール実行用EventBridgeルール
resource "aws_cloudwatch_event_rule" "my_function_schedule" {
  name                = "my-function-schedule"
  description         = "15分毎に関数を起動"
  schedule_expression = "cron(15 * * * ? *)"
}

# EventBridgeターゲット
resource "aws_cloudwatch_event_target" "lambda_target" {
  rule      = aws_cloudwatch_event_rule.my_function_schedule.name
  target_id = "MyFunctionTarget"
  arn       = module.my_project_my_function.function_arn
}

# EventBridgeがLambda関数を起動するための権限
resource "aws_lambda_permission" "allow_eventbridge" {
  statement_id  = "AllowExecutionFromEventBridge"
  action        = "lambda:InvokeFunction"
  function_name = module.my_project_my_function.function_name
  principal     = "events.amazonaws.com"
  source_arn    = aws_cloudwatch_event_rule.my_function_schedule.arn
}

イベントソースの一致

ハンドラー関数内でイベントが適切に処理されるよう、イベントソースが選択した eventSource オプションと一致していることを確認してください。