AWS EmulatorでLambda関数を作って呼び出す方法
AWS Emulator に Python の Lambda 関数を zip で登録すると、aws lambda invoke で呼び出して戻り値を受け取れます。AWS のアカウントは要りません。ローカル環境や CI で、デプロイする前に Lambda 関数を作って呼び出す流れを試したいときの手順です。関数の作成、呼び出し、コードの差し替え、エラーと時間切れのときの応答、削除までを、検証環境で実行したコマンドと出力のまま載せます。
検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.385(2026年11月14日リリース、Debian パッケージ)、AWS CLI 2.40.3 です。AWS のアカウントと認証情報は使っていません。本物の AWS Lambda での動きと料金は確かめておらず、記事で触れるところは公式ドキュメントを出どころにしています。Python 以外のランタイム、コンテナイメージの関数、非同期の呼び出し、バージョンとエイリアス、ほかのサービスからのトリガーは試していません。

エミュレーターを起動して、AWS CLI を向ける
AWS Emulator は、公式ガイドにある Linux での入れ方のとおりに Debian パッケージで入れました。
1つ目の端末で起動します。-t off は、使用状況のデータ(テレメトリー)を送らない指定です。
aws-emulator -t off
2つ目の端末で、SDK の接続先をエミュレーターに向ける手順にある環境変数を設定します。最後の AWS_PAGER は、AWS CLI の出力をページャーで開かずにそのまま表示するために足しました。
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
export AWS_PAGER=""
起動した直後は、関数は1つもありません。
$ aws lambda list-functions
{
"Functions": []
}
実行ロールと zip を用意する
CreateFunction の API リファレンスによると、関数を作るにはコードの入ったパッケージ(zip かコンテナイメージ)と、実行ロールが要ります。まず、Lambda が引き受けられるロールを IAM で作ります。信頼ポリシーを trust.json に書きました。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "Service": "lambda.amazonaws.com" },
"Action": "sts:AssumeRole"
}
]
}
$ aws iam create-role --role-name example-lambda-role --assume-role-policy-document file://trust.json --query Role.Arn --output text
arn:aws:iam::<12桁のアカウントID>:role/example-lambda-role
出力の中のアカウントIDは、<12桁のアカウントID> に置き換えています。
関数のコードは fn/lambda_function.py に書きました。受け取った name と、環境変数 GREETING、context オブジェクトの関数名とリクエスト ID を返します。print はログに出ます。
import os
def lambda_handler(event, context):
name = event.get("name", "world")
print(f"name={name}")
return {
"message": f"hello, {name}",
"greeting": os.environ.get("GREETING"),
"function_name": context.function_name,
"request_id": context.aws_request_id,
}
これを zip にまとめます。
$ cd fn && zip ../function.zip lambda_function.py
adding: lambda_function.py (deflated 40%)
関数を作り、Active になるまで待つ
create-function で関数を作ります。ハンドラーの lambda_function.lambda_handler は「ファイル名.関数名」の形で、Python のハンドラーの説明にある、コンソールで作ったときの既定の名前と同じです。ロールの ARN は、sts get-caller-identity でアカウントIDを取って組み立てました。
$ aws lambda create-function --function-name example-fn --runtime python3.12 --handler lambda_function.lambda_handler --role arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/example-lambda-role --zip-file fileb://function.zip --environment "Variables={GREETING=nyan}"
{
"FunctionName": "example-fn",
"FunctionArn": "arn:aws:lambda:us-east-1:<12桁のアカウントID>:function:example-fn",
"Runtime": "python3.12",
"Role": "arn:aws:iam::<12桁のアカウントID>:role/example-lambda-role",
"Handler": "lambda_function.lambda_handler",
"CodeSize": 373,
"Timeout": 3,
"MemorySize": 128,
(中略)
"State": "Pending",
"StateReason": "The function is being created.",
"StateReasonCode": "Creating",
(以下は省略)
}
返ってきた直後の State は Pending です。関数の状態の説明によると、本物の Lambda は Pending の間は関数を呼び出さず、Active になってから呼べるようになります。エミュレーターでも同じ順で状態を返したので、スクリプトでは wait function-active-v2 で待ってから呼ぶ形にしておきます。
$ aws lambda wait function-active-v2 --function-name example-fn
$ aws lambda get-function-configuration --function-name example-fn --query "{State:State,LastUpdateStatus:LastUpdateStatus,Runtime:Runtime,Handler:Handler}"
{
"State": "Active",
"LastUpdateStatus": "Successful",
"Runtime": "python3.12",
"Handler": "lambda_function.lambda_handler"
}
invoke で呼び出して、戻り値とログを見る
--payload で関数に渡す JSON を指定し、最後の引数に戻り値を書き出すファイル名を指定します。
$ aws lambda invoke --function-name example-fn --cli-binary-format raw-in-base64-out --payload '{"name":"neko"}' response.json
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
$ cat response.json; echo
{"message": "hello, neko", "greeting": "nyan", "function_name": "example-fn", "request_id": "5de97a6c-3bc2-4159-99ce-d2f24bf43484"}
渡した name、作るときに設定した環境変数、関数名が、関数の中から見えていました。
--cli-binary-format raw-in-base64-out は、--payload に JSON をそのまま書くための指定です。AWS CLI v2 はバイナリの引数を base64 として扱うので、付け忘れると次のエラーになりました。
$ aws lambda invoke --function-name example-fn --payload '{"name":"neko"}' response.json
aws: [ERROR]: An error occurred (InvalidRequestContentException) when calling the Invoke operation: Could not parse request body into json: Could not parse payload into json: Unexpected character ('�' (code 65533)): was expecting a valid value (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
(以下は省略)
--log-type Tail を付けると、実行ログが base64 で LogResult に入って返ります。Invoke の API リファレンスによると、入るのはログの最後の 4 KB です。デコードすると、print の行が START と END の間に出ていました。
$ aws lambda invoke --function-name example-fn --cli-binary-format raw-in-base64-out --payload '{"name":"neko"}' --log-type Tail response.json --query LogResult --output text | base64 -d
START RequestId: 34efc45d-3b22-44f9-8f5e-7bc1fff27aa6 Version: $LATEST
name=neko
END RequestId: 34efc45d-3b22-44f9-8f5e-7bc1fff27aa6
REPORT RequestId: 34efc45d-3b22-44f9-8f5e-7bc1fff27aa6 Duration: 8.86 ms Billed Duration: 9 ms Memory Size: 128 MB Max Memory Used: 1 MB
コードを差し替えて、もう一度呼ぶ
コードを直したら、zip を作り直して update-function-code で差し替えます。戻り値の hello を nyaa に変えました。返ってきた直後の LastUpdateStatus は InProgress だったので、wait function-updated-v2 で終わるのを待ってから呼びます。
$ aws lambda update-function-code --function-name example-fn --zip-file fileb://function.zip --query "{LastUpdateStatus:LastUpdateStatus,CodeSize:CodeSize}"
{
"LastUpdateStatus": "InProgress",
"CodeSize": 373
}
$ aws lambda wait function-updated-v2 --function-name example-fn
$ aws lambda invoke --function-name example-fn --cli-binary-format raw-in-base64-out --payload '{"name":"neko"}' response.json && cat response.json; echo
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
{"message": "nyaa, neko", "greeting": "nyan", "function_name": "example-fn", "request_id": "80c945aa-2f83-4ade-af59-7b9f0e19128c"}
関数のエラーと時間切れは StatusCode 200 で返る
関数の中で例外が起きたときの返り方を見るために、sleep がなければ ValueError を出し、あれば指定の秒数だけ待つ関数 example-err を作りました。作り方は example-fn と同じです。
import time
def lambda_handler(event, context):
if "sleep" in event:
time.sleep(event["sleep"])
return "woke up"
raise ValueError("name is required")
引数なしで呼んだ結果です。応答に FunctionError が付き、err.json には例外の種類とメッセージ、スタックトレースが入っていました。
$ aws lambda invoke --function-name example-err err.json
{
"StatusCode": 200,
"FunctionError": "Unhandled",
"ExecutedVersion": "$LATEST"
}
$ cat err.json; echo
{"errorMessage":"name is required","errorType":"ValueError","requestId":"1efbc2bc-f99e-4a99-8dc4-5fbbc688078a","stackTrace":[" File \"/var/task/lambda_function.py\", line 8, in lambda_handler\n raise ValueError(\"name is required\")\n"]}
Invoke の API リファレンスにも、API の応答のステータスコードは関数のエラーを表さず、FunctionError があれば関数の実行中にエラーが起きたことを示す、と書かれています。
関数が例外を出しても、aws lambda invoke の終了コードは 0 で、StatusCode は 200 のままです。失敗を見分けるには、応答に FunctionError があるかを確かめます。
時間切れも同じ形でした。タイムアウトは指定しなかったので、CreateFunction の既定値の 3 秒になっています。関数の中で 5 秒待たせると、3.7 秒ほどで戻り、errorType が Sandbox.Timedout でした。
$ time aws lambda invoke --function-name example-err --cli-binary-format raw-in-base64-out --payload '{"sleep":5}' err.json
{
"StatusCode": 200,
"FunctionError": "Unhandled",
"ExecutedVersion": "$LATEST"
}
real 0m3.674s
user 0m0.567s
sys 0m0.065s
$ cat err.json; echo
{"errorMessage":"01eb6253-942b-474e-b04f-54b2c5770852 Task timed out after 3.00 seconds","errorType":"Sandbox.Timedout","requestId":"01eb6253-942b-474e-b04f-54b2c5770852","stackTrace":[]}
update-function-configuration --timeout 10 で 10 秒に延ばし、wait function-updated-v2 で待ってから同じように呼ぶと、5.8 秒ほどで "woke up" が返りました。
一方、関数そのものがないときは、関数を実行する前に起きるエラーなので、返り方が違います。Invoke の API リファレンスでは、こうしたエラーのときだけ、HTTP のステータスがエラーを表すと説明されています。検証環境では ResourceNotFoundException になり、AWS CLI の終了コードは 254、HTTP のステータスは 404 でした。
$ aws lambda invoke --function-name no-such-fn err.json
aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the Invoke operation: Function not found: arn:aws:lambda:us-east-1:<12桁のアカウントID>:function:no-such-fn:$LATEST
(以下は省略)
$ aws lambda invoke --function-name no-such-fn err.json --debug 2>&1 | grep -E "HTTP/1.1\" [0-9]+"
2026-11-15 02:21:24,832 - MainThread - urllib3.connectionpool - DEBUG - https://127.0.0.1:9297 "POST /2015-03-31/functions/no-such-fn/invocations HTTP/1.1" 404 150
エミュレーターの中の Python の環境
関数のコードがどんな環境で動くかを見るために、Python のバージョンと、ルートディレクトリ(/)の中身の一覧を返す関数 example-probe を作りました。
import os
import platform
def lambda_handler(event, context):
result = {"python_version": platform.python_version()}
try:
result["pid"] = os.getpid()
except OSError as e:
result["pid_error"] = str(e)
try:
result["listdir"] = os.listdir("/")
except OSError as e:
result["listdir_error"] = str(e)
return result
公式のランタイムの一覧では python3.12 は Python 3.12 ですが、エミュレーターでは 3.14.0.alpha が返りました。プロセス ID は 1 で、os.listdir("/") は、ファイルシステムに届かないという OSError で失敗しました。
$ aws lambda invoke --function-name example-probe probe.json && cat probe.json; echo
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
{"python_version": "3.14.0.alpha", "pid": 1, "listdir_error": "a Lambda function in this emulator has no host filesystem or process to reach"}
Python のバージョンで変わる処理や、os.listdir("/") のようにファイルシステムを見る処理は、エミュレーターの結果をそのまま当てにできません。
存在しないロール no-such-role を指定した関数 example-norole も、エラーにならずに作られました。AWS Emulator の制限の説明のとおり、IAM のポリシーは AWS と同じようには判定されないので、権限の確認には使えません。
この記事で使った Lambda の操作で、未対応の操作に返る HTTP 501(NotImplemented)が返ったものはありませんでした。リリースのページで v1.0.385 に付いている fidelity のスコアのファイルでも、Lambda の API を含むテストに NotImplemented の記録はありませんでした。
関数を消して、エミュレーターを止める
作った4つの関数を delete-function で消します。AWS CLI は関数ごとに "StatusCode": 204 を表示しました。
$ for f in example-fn example-err example-probe example-norole; do aws lambda delete-function --function-name $f; done
{
"StatusCode": 204
}
(同じ表示があと3回続く)
$ aws lambda list-functions --query "Functions[].FunctionName"
[]
エミュレーターは作ったリソースをメモリーに置き、止めると消します。止めるときは、起動した端末で Ctrl+C を押すか、SIGTERM を送ります。検証環境では、SIGTERM を送ると、終了コード 0 で止まりました。




