カスタムランタイムに Lambda ランタイム API を使用する

AWS Lambda では、カスタムランタイムの HTTP API を使用して Lambda の呼び出しイベントを受け取り、レスポンスデータを Lambda の実行環境に送り返します。このセクションでは、Lambda ランタイム API の API リファレンスについて説明します。

ランタイム API バージョン 2018-06-01 の OpenAPI 仕様は、runtime-api.zip から入手できます。

API リクエスト URL を作成するには、ランタイムは AWS_LAMBDA_RUNTIME_API 環境変数から API エンドポイントを取得し、API バージョンを追加し、目的のリソースパスを追加します。

curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

次の呼び出し

パス – /runtime/invocation/next

メソッド - GET

ランタイムは、このメッセージを Lambda に送信して、呼び出しイベントをリクエストします。レスポンス本文には、呼び出しのペイロードが含まれます。これは、関数トリガーのイベントデータを含む JSON ドキュメントです。レスポンスヘッダーには、呼び出しに関する追加データが含まれます。

応答が遅れる可能性があるため、GET リクエストにタイムアウトを設定しないでください。Lambda がランタイムをブートストラップするときと、返すイベントがランタイムにあるときとの間に、ランタイムプロセスが数秒間停止する可能性があります。

リクエスト ID (Lambda-Runtime-Aws-Request-Id) は一意のイベントを特定します。リクエスト ID はイベントソースから提供されるか Lambda が取り込み時に自動生成します。レスポンスまたはエラーを送信するときはこれを URL パスで使用します。

呼び出し ID (Lambda-Runtime-Invocation-Id) は、1 回のイベントの呼び出し試行を表します。1 つのリクエスト ID で呼び出しが複数行われることがあり、それぞれ固有の呼び出し ID が付きます。Lambda は各呼び出し ID を 1 回のみ使用し、再利用はしません。この値を /response および /error 呼び出し時にエコーバックします。ヘッダーは既存のランタイムとの下位互換性を保つためのオプションです。このヘッダーを省略しても拒否がトリガーされることはありません。Lambda は、ヘッダーはあるがその値がアクティブな呼び出しと一致しない場合にのみ、400 InvalidInvocationId を使って拒否します。

トレースヘッダーには、トレース ID、親 ID、サンプリングデシジョンが含まれます。リクエストがサンプリングされている場合、リクエストが Lambda、またはアップストリームサービスによってサンプリングされた場合。ランタイムは、_X_AMZN_TRACE_ID をヘッダーの値に設定します。X-Ray SDK はこの値を読み込んで ID を取得し、リクエストを追跡するかどうかを判断します。

呼び出しレスポンス

パス – /runtime/invocation/AwsRequestId/response

メソッド - POST

関数が実行されて完了すると、ランタイムは呼び出し応答を Lambda に送信します。同期呼び出しの場合、Lambda はそのレスポンスをクライアントに送ります。

リクエストヘッダー

Lambda-Runtime-Invocation-Id – /next から届いた値をエコーバックします。Lambda は、値がアクティブな呼び出しと一致しない場合に 400 InvalidInvocationId を使ってリクエストを拒否します。

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
INVOCATION_ID=<value from Lambda-Runtime-Invocation-Id response header>
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS" --header "Lambda-Runtime-Invocation-Id: $INVOCATION_ID"

初期化エラー

関数がエラーを返すか、初期化中にランタイムでエラーが発生した場合、ランタイムはこのメソッドを使用してエラーを Lambda に報告します。

パス – /runtime/init/error

メソッド - POST

ヘッダー

Lambda-Runtime-Function-Error-Type – ランタイムで発生したエラータイプ。このヘッダーはオプションです。Lambda は任意の文字列値を受け入れていますが、<Category.Reason> の形式 (Category が Runtime または Function、Reason が大文字で始まる) を使用することが推奨されます。例えば、次のようになります。

このパターンに一致しない値は Runtime.Unknown または Function.Unknown に正規化されます。

Body パラメータ

ErrorRequest - エラーに関する情報。必須: いいえ。

このフィールドは、次の構造を持つ JSON オブジェクトです。

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Lambda は、errorType として任意の値を受け入れることに注意してください。

次の例は、呼び出しで指定されたイベントデータを関数で解析できなかった Lambda 関数のエラーメッセージを示しています。

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" : \"InvalidFunctionException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

呼び出しエラー

関数がエラーを返すか、ランタイムでエラーが発生した場合、ランタイムはこのメソッドを使用してエラーを Lambda に報告します。

パス – /runtime/invocation/AwsRequestId/error

メソッド - POST

ヘッダー

Lambda-Runtime-Function-Error-Type – ランタイムで発生したエラータイプ。必須: いいえ。

このヘッダーは、文字列値で構成されています。Lambda はどのような文字列でも受け入れますが、形式は <category.reason> にすることが推奨されます。以下に例を示します。

Lambda-Runtime-Invocation-Id – /next から届いた値をエコーバックします。Lambda は、値がアクティブな呼び出しと一致しない場合に 400 InvalidInvocationId を使ってリクエストを拒否します。

Body パラメータ

ErrorRequest - エラーに関する情報。必須: いいえ。

このフィールドは、次の構造を持つ JSON オブジェクトです。

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Lambda は、errorType として任意の値を受け入れることに注意してください。

次の例は、呼び出しで指定されたイベントデータを関数で解析できなかった Lambda 関数のエラーメッセージを示しています。

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" : \"InvalidEventDataException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

復元後 (SnapStart にのみ適用)

パス – /runtime/restore/next

メソッド - GET

スナップショット前のフックが完了すると、ランタイムが GET /runtime/restore/next を呼び出します。これは、/runtime/invocation/next と同様に、ランタイムで実行環境のスナップショットを作成する準備が整ったことを Lambda に知らせるイテレーター形式のブロッキング呼び出しです。リクエストは、Lambda がスナップショットから実行環境を復元するまでブロックされ、その後、HTTP 200 レスポンスを本文が空の状態で返します。

ヘッダー。

必要なヘッダーはありません。

リクエストの構文

GET /2018-06-01/runtime/restore/next HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}

レスポンスの構文

HTTP/1.1 200 OK
Content-Length: 0

復元後 (SnapStart にのみ該当)

復元後フックが失敗するか、復元中にランタイムでエラーが発生した場合、ランタイムはこのメソッドを使用してエラーを Lambda に報告します。Lambda は処理中の呼び出しに失敗し、実行環境を破棄します。

パス – /runtime/restore/error

メソッド - POST

ヘッダー

Lambda-Runtime-Function-Error-Type – ランタイムで発生したエラータイプ。このヘッダーはオプションです。Lambda は任意の文字列値を受け入れていますが、<Category.Reason> の形式 (Category が Runtime または Function、Reason が大文字で始まる) を使用することが推奨されます (例 Runtime.AfterRestoreError)。このパターンに一致しない値は Runtime.Unknown または Function.Unknown に正規化されます。

POST /2018-06-01/runtime/restore/error HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}
Lambda-Runtime-Function-Error-Type: Runtime.AfterRestoreError

HTTP/1.1 202 Accepted
Content-Type: application/json

{"status":"OK"}