AWS EmulatorでLambda関数を作って呼び出す方法

​​AWS Emulator​AWS CLI,AWS Lambda,Python,テスト

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 以外のランタイム、コンテナイメージの関数、非同期の呼び出し、バージョンとエイリアス、ほかのサービスからのトリガーは試していません。

1. コードを zip にまとめる、2. create-function で関数を作る(State は Pending)、3. wait function-active-v2 で Active になるまで待つ、4. invoke で呼び出す。成功なら StatusCode 200 で戻り値は response.json へ、関数のエラーでも 200 のまま FunctionError が付く
この記事で試す、関数を作って呼び出すまでの流れ

エミュレーターを起動して、AWS CLI を向ける

AWS Emulator は、公式ガイドにある Linux での入れ方のとおりに Debian パッケージで入れました。

1つ目の端末で起動します。-t off は、使用状況のデータ(テレメトリー)を送らない指定です。

bash
aws-emulator -t off

2つ目の端末で、SDK の接続先をエミュレーターに向ける手順にある環境変数を設定します。最後の AWS_PAGER は、AWS CLI の出力をページャーで開かずにそのまま表示するために足しました。

bash
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つもありません。

text
$ aws lambda list-functions
{
    "Functions": []
}

実行ロールと zip を用意する

CreateFunction の API リファレンスによると、関数を作るにはコードの入ったパッケージ(zip かコンテナイメージ)と、実行ロールが要ります。まず、Lambda が引き受けられるロールを IAM で作ります。信頼ポリシーを trust.json に書きました。

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "lambda.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}
text
$ 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 はログに出ます。

python
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 にまとめます。

text
$ 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を取って組み立てました。

text
$ 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 で待ってから呼ぶ形にしておきます。

text
$ 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 を指定し、最後の引数に戻り値を書き出すファイル名を指定します。

text
$ 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 として扱うので、付け忘れると次のエラーになりました。

text
$ 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 の間に出ていました。

text
$ 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 で終わるのを待ってから呼びます。

text
$ 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 と同じです。

python
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 には例外の種類とメッセージ、スタックトレースが入っていました。

text
$ 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 でした。

text
$ 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 でした。

text
$ 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 を作りました。

python
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 で失敗しました。

text
$ 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 を表示しました。

text
$ 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 で止まりました。

​Posted by 86