aws-lambda-durable-functions

AWS Lambda 耐久関数

中断が発生しても確実に進行状況を維持しながら、最大 1 年間実行できる、回復性の高い複数ステップのアプリケーションや AI ワークフローを構築します。

最適な組み合わせは AWS MCP サーバー ですが、必須ではありません。このスキルでの AWS とのやり取りには、AWS 認証情報が設定されていればどの環境でも使用できる標準の AWS CLI コマンドを使用します。

重要なルール

コードを書く前に、以下をお読みください。これらの制約に違反すると、関数が予期せず動作しなくなります。

1. 耐久実行は関数の作成時に有効にする必要があります。後から追加することはできません。 新しい Lambda 関数は、耐久実行を有効にして作成する必要があります。ロジックを新しい関数に移行してください。既存の関数に SDK をインストールしてハンドラーをラップし、それで動作すると期待してはいけません。
2. 耐久関数は修飾 ARN を指定して呼び出す必要があります。 特定のバージョン、エイリアス、またはリテラルの $LATEST サフィックスを指定します。修飾されていない関数名では失敗します。例については、以下の呼び出し要件セクションを参照してください。
3. 耐久オペレーションをネストすることはできません。 別のステップのコールバック内から context.step()、context.wait()、context.invoke() を呼び出すことはできません。オペレーションをまとめるには context.runInChildContext() を使用してください。
4. 非決定的なコードはすべてステップ内で実行する必要があります。 ステップ外での Date.now()、Math.random()、UUID の生成、API 呼び出し、データベースクエリは、リプレイ時に異なる値を生成し、実行状態を破損させます。
5. リプレイ時にクロージャの変更は失われます - ステップから値を返してください
6. ステップ外の副作用は繰り返されます - context.logger（リプレイに対応）を使用してください

リファレンスファイルを読み込むタイミング

ユーザーが取り組んでいる内容に応じて、適切なリファレンスファイルを読み込んでください。

• 入門、基本設定、例、ESLint、または Jest の設定 -> getting-started.md を参照してください
• リプレイモデル、決定性、または 非決定的なエラーを理解する -> replay-model-rules.md を参照してください
• ステップの作成、アトミックなオペレーション、または 再試行ロジック -> step-operations.md を参照してください
• 待機、遅延、コールバック、外部システム、または ポーリング -> wait-operations.md を参照してください
• 並列実行、マップオペレーション、バッチ処理、または 同時実行 -> concurrent-operations.md を参照してください
• エラー処理、再試行戦略、サーガパターン、または 補償トランザクション -> error-handling.md を参照してください
• 高度なエラー処理、タイムアウト処理、サーキットブレーカー、または 条件付き再試行 -> advanced-error-handling.md を参照してください
• テスト、ローカルテスト、クラウドテスト、テストランナー、または 不安定なテスト -> testing-patterns.md を参照してください
• デプロイ、CloudFormation、CDK、SAM、ロググループ、デプロイ、または インフラストラクチャ -> deployment-iac.md を参照してください
• 高度なパターン、GenAI エージェント、完了ポリシー、ステップのセマンティクス、または カスタムシリアライズ -> advanced-patterns.md を参照してください
• トラブルシューティング、実行の停止、実行の失敗、実行 ID のデバッグ、実行履歴、実行エラー、実行が失敗した理由、実行のタイムアウト、コールバックが届かない、実行の診断、または 実行の根本原因 -> troubleshooting-executions.md を参照してください

クイックリファレンス

基本的なハンドラーパターン

TypeScript:

import { withDurableExecution, DurableContext } from '@aws/durable-execution-sdk-js';

export const handler = withDurableExecution(async (event, context: DurableContext) => {
  const result = await context.step('process', async () => processData(event));
  return result;
});

Python:

from aws_durable_execution_sdk_python import durable_execution, DurableContext

@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
    result = context.step(lambda _: process_data(event), name='process')
    return result

Python API の違い

Python SDK は、いくつかの重要な点で TypeScript と異なります。

• ステップ：@durable_step デコレーターと context.step(my_step(args)) を使うか、context.step(lambda _: ..., name='...') のようにインラインで記述します。ステップ名を自動的に付けるには、デコレーターを使うことをおすすめします。
• 待機：context.wait(duration=Duration.from_seconds(n), name='...')
• 例外：ExecutionError（永続的）、InvocationError（一時的）、CallbackError（コールバックの失敗）
• テスト：DurableFunctionTestRunner クラスを直接使います。ハンドラーを指定してインスタンス化し、コンテキストマネージャーを使って、run(input=...) を呼び出します。

呼び出し要件

永続関数には、バージョン、エイリアス、または $LATEST を含む修飾 ARN が必要です。

# Valid
aws lambda invoke --function-name my-function:1 output.json
aws lambda invoke --function-name my-function:live output.json

# Invalid - will fail
aws lambda invoke --function-name my-function output.json

IAM 権限

Lambda 実行ロールには、管理ポリシー AWSLambdaBasicDurableExecutionRolePolicy を必ずアタッチしてください。このポリシーには、以下が含まれます。

• lambda:CheckpointDurableExecution - 実行状態を永続化します
• lambda:GetDurableExecutionState - 実行状態を取得します
• CloudWatch Logs の権限

追加で必要な権限：

• 永続的な呼び出し：対象関数の ARN に対する lambda:InvokeFunction
• 外部コールバック：システムに lambda:SendDurableExecutionCallbackSuccess と lambda:SendDurableExecutionCallbackFailure が必要です

検証ガイドライン

永続関数のコードを作成またはレビューする際は、以下のリプレイモデル違反がないか必ず確認してください。

1. ステップ外にある非決定的なコード：Date.now()、Math.random()、UUID の生成、API 呼び出し、データベースクエリはすべてステップ内に記述する必要があります
2. ステップ関数内のネストされた永続操作：ステップ関数内では context.step()、context.wait()、context.invoke() を呼び出せません。代わりに context.runInChildContext() を使ってください
3. 永続化されないクロージャの変更：ステップ内で変更された変数はリプレイ時に保持されません。代わりに、ステップから値を返してください
4. リプレイ時に繰り返されるステップ外の副作用：ログ記録には context.logger を使ってください（リプレイに対応しており、自動的に重複を排除します）

永続関数のテストを実装または変更する際は、以下を必ず確認してください。

1. すべての操作に説明的な名前が付いている
2. テストではインデックスではなく、名前を使って操作を取得している
3. 複数回の呼び出しでリプレイ動作をテストしている
4. ローカルテストには LocalDurableTestRunner を使っている

セキュリティに関する考慮事項

• チェックポイントデータの暗号化：実行状態は自動的に永続化されます。保存データを保護するには、関連付けられた CloudWatch Log Groups で KMS 暗号化を有効にしてください。
• ステップ結果に含まれる機密データ：ステップの戻り値はチェックポイントとして保存され、永続化されます。ステップから秘密情報、認証情報の生データ、または個人識別情報を返さないでください。機密データは Secrets Manager または SSM Parameter Store に保存し、代わりに参照情報を返してください。
• 入力検証：データをステップに渡す前に、ハンドラーの入口でイベントペイロードを検証し、サニタイズしてください。
• 認証情報の管理：ステップ内で AWS Secrets Manager または SSM Parameter Store から秘密情報を取得してください。
• コールバックペイロードの検証：waitForCallback 経由で受信するデータは外部システムに由来するため、処理前に検証し、サニタイズしてください。
• ログ記録：ステップの結果や実行状態が漏えいする可能性があるため、開発環境以外では DEBUG ログレベルを避けてください。KMS による CloudWatch Logs の暗号化を有効にしてください。

リソース

• AWS Lambda 永続関数のドキュメント
• JavaScript SDK リポジトリ
• Python SDK リポジトリ
• IAM ポリシーのリファレンス