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

カスタムランタイムに 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 ドキュメントです。レスポンスヘッダーには、呼び出しに関する追加データが含まれます。

レスポンスヘッダー
  • Lambda-Runtime-Aws-Request-Id - リクエスト ID。関数の呼び出しをトリガーしたリクエストを識別します。

    例えば、8476a536-e9f4-11e8-9739-2dfe598c3fcd と指定します。

  • Lambda-Runtime-Deadline-Ms - 関数がタイムアウトした日付 (Unix 時間のミリ秒)。

    例えば、1542409706888 と指定します。

  • Lambda-Runtime-Invoked-Function-Arn - 呼び出しで指定されている Lambda 関数、バージョン、またはエイリアスの ARN。

    例えば、arn:aws:lambda:us-east-2:123456789012:function:custom-runtime と指定します。

  • Lambda-Runtime-Trace-Id - AWS X-Ray トレースヘッダー

    例えば、Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1 と指定します。

  • Lambda-Runtime-Client-Context - AWS Mobile SDK の呼び出しにおいて、クライアントアプリケーションおよびデバイスに関するデータ。

  • Lambda-Runtime-Cognito-Identity - AWS Mobile SDK からの呼び出しの場合は、Amazon Cognito ID プロバイダーに関するデータ。

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

リクエスト ID は、Lambda 内の呼び出しを追跡します。レスポンス送信時に呼び出しを指定する場合に使用します。

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

呼び出しレスポンス

パス/runtime/invocation/AwsRequestId/response

メソッド - POST

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

例 成功リクエスト
REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9 curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response" -d "SUCCESS"

初期化エラー

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

パス/runtime/init/error

メソッド - POST

ヘッダー

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

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

  • Runtime.NoSuchHandler

  • Runtime.APIKeyNotFound

  • Runtime.ConfigInvalid

  • Runtime.UnknownReason

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": [ ] }
レスポンス本文のパラメータ
  • StatusResponse – 文字列。202 応答コードとともに送信されるステータス情報。

  • ErrorResponse - エラー応答コードとともに送信される追加のエラー情報。ErrorResponse には、エラータイプとエラーメッセージが含まれています。

レスポンスコード
  • 202 - Accepted

  • 403 – Forbidden

  • 500 – Container error 回復不能な状態。ランタイムはすぐに終了することが望ましいです。

例 初期化エラーリクエスト
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> にすることが推奨されます。以下に例を示します。

  • Runtime.NoSuchHandler

  • Runtime.APIKeyNotFound

  • Runtime.ConfigInvalid

  • Runtime.UnknownReason

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": [ ] }
レスポンス本文のパラメータ
  • StatusResponse – 文字列。202 応答コードとともに送信されるステータス情報。

  • ErrorResponse - エラー応答コードとともに送信される追加のエラー情報。ErrorResponse には、エラータイプとエラーメッセージが含まれています。

レスポンスコード
  • 202 - Accepted

  • 400 – Bad Request

  • 403 – Forbidden

  • 500 – Container error 回復不能な状態。ランタイムはすぐに終了することが望ましいです。

例 エラーリクエスト
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"