メニュー
Amazon API Gateway
開発者ガイド

API Gateway で Lambda エラーを処理する

Lambda カスタム統合の場合、統合レスポンスで Lambda によって返されたエラーを、クライアントの標準 HTTP エラーレスポンスにマップする必要があります。そうしないと、Lambda のエラーはデフォルトで 200 OK レスポンスとして返されるため、API ユーザーは直感的に理解できません。

Lambda から返されるエラーには、標準エラーとカスタムエラーの 2 種類があります。API では、これらを異なる方法で処理する必要があります。

Lambda プロキシ統合では、Lambda は次の形式で出力を返す必要があります。

Copy
{ "isBase64Encoded" : "boolean", "statusCode": "number", "headers": { ... }, "body": "JSON string" }

この出力で、通常、statusCode4XX はクライアントエラー、5XX はサーバーエラーです。API Gateway では、これらのエラーを処理する方法として、指定された statusCode に従って Lambda エラーを HTTP エラーレスポンスにマッピングします。API Gateway がクライアントへのレスポンスの一部としてエラータイプ (InvalidParameterException など) を渡すには、Lambda 関数がヘッダー ("X-Amzn-ErrorType":"InvalidParameterException" など) を headers プロパティに含める必要があります。

API Gateway で Lambda の標準エラーを処理する

AWS Lambda の標準エラーは次の形式になります。

Copy
{ "errorMessage": "<replaceable>string</replaceable>", "errorType": "<replaceable>string</replaceable>", "stackTrace": [ "<replaceable>string</replaceable>", ... ] }

ここで、errorMessage はエラーの文字列式です。errorType は、言語に依存するエラーまたは例外タイプです。stackTrace は、エラーの発生につながったスタックトレースを示す文字列式のリストです。

たとえば、次の JavaScript Lambda 関数 (Node.js 4.3 以降) について考えてみます。

Copy
exports.handler = function(event, context, callback) { callback(new Error("Malformed input ..."); };

この関数は、Malformed input ... をエラーメッセージとする、次の Lambda 標準エラーを返します。

Copy
{ "errorMessage": "Malformed input ...", "errorType": "Error", "stackTrace": [ "exports.handler (/var/task/index.js:3:14)" ] }

同様に、次の例は同じ Malformed input ... をエラーメッセージとし、Exception をスローする Python Lambda 関数です。

Copy
def lambda_handler(event, context): raise Exception('Malformed input ...')

この関数は、次の Lambda 標準エラーを返します。

Copy
{ "stackTrace": [ [ "/var/task/lambda_function.py", 3, "lambda_handler", "raise Exception('Malformed input ...')" ] ], "errorType": "Exception", "errorMessage": "Malformed input ..." }

errorType プロパティと stackTrace プロパティの値は、言語に依存します。この標準エラーは、Error オブジェクトの拡張または Exception クラスのサブクラスである各エラーオブジェクトにも適用されます。

Lambda の標準エラーをメソッドレスポンスにマッピングするには、まず該当する Lambda エラーの HTTP スタータスコードを確認する必要があります。次に、その HTTP ステータスコードに関連付けられた IntegrationResponseselectionPattern プロパティで正規表現パターンを設定します。API Gateway コンソールでは、この selectionPattern が [Integration Response] 設定エディタの [Lambda Error Regex] として示されます。

たとえば、新しい selectionPattern 式を設定するには、AWS CLI を使用して、次の put-integration-response コマンドを呼び出します。

Copy
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Invalid*" --region us-west-2

メソッドリクエストで対応するエラーコード (400) も必ず設定します。そうしないと、ランタイムに API Gateway から無効な設定エラーレスポンスがスローされます。

ランタイムに、API Gateway はエラーメッセージを selectionPattern プロパティの正規表現のパターンと照合します。一致すると、API Gateway は Lambda エラーを、対応する HTTP ステータスコードの HTTP レスポンスとして返します。一致しない場合、API Gateway はエラーをデフォルトレスポンスとして返すか、デフォルトレスポンスが設定されていなければ、無効な設定例外をスローします。

注記

特定のレスポンスで selectionPattern の値を .* に設定すると、このレスポンスはデフォルトのレスポンスとしてリセットされます。このような選択パターンは null (任意の未指定のエラーメッセージ) を含むすべてのエラーメッセージに一致するためです。その結果のマッピングにより、デフォルトのマッピングが上書きされます。

API Gateway REST API を使用して既存の selectionPattern 値を更新するには、integrationresponse:update オペレーションを呼び出し、/selectionPattern のパス値を Malformed* パターンの指定された正規表現式に置き換えます。

Copy
PATCH /restapis/z0vprf0mdh/resources/x3o5ih/methods/GET/integration/responses/400 HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170513T044831Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170513/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=4b4e4881a727bc999799be5110facfcf7ec81d025afc1a4386cf440b4efc80de Cache-Control: no-cache Postman-Token: 04794263-29f2-f336-fa16-5653a7f3281d { "patchOperations" : [ { "op" : "replace", "path" : "/selectionPattern", "value" : "Malformed*" } ] }

API Gateway コンソールを使用して selectionPattern 式を設定するには、指定された HTTP ステータスコードの統合レスポンスを設定または更新するときに、[Lambda Error Regex] テキストボックスに式を入力します。

API Gateway で Lambda のカスタムエラーを処理する

AWS Lambda では、前のセクションで説明した標準エラーの代わりにカスタムエラーオブジェクトを JSON 文字列として返すことができます。エラーは、任意の有効な JSON オブジェクトです。たとえば、次の JavaScript Lambda 関数 (Node.js 4.3 以降) はカスタムエラーを返します。

Copy
exports.handler = (event, context, callback) => { ... // Error caught here: var myErrorObj = { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } callback(JSON.stringify(myErrorObj)); };

callback を呼び出して関数を終了する前に、myErrorObj オブジェクトを JSON 文字列に変換する必要があります。そうしないと、myErrorObj"[object Object]" の文字列として返されます。API のメソッドを前の Lambda 関数と統合すると、API Gateway は以下の内容をペイロードとする統合レスポンスを受け取ります。

Copy
{ "errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}" }

通常の統合レスポンスと同様に、このエラーレスポンスはそのままメソッドレスポンスに渡すことができます。または、本文マッピングテンプレートを使用してペイロードを別の形式に変換することもできます。次の例は、ステータスコードが 500 のメソッドレスポンスの本文マッピングテンプレートです。

Copy
{ errorMessage: $input.path('$.errorMessage'); }

このテンプレートは、カスタムエラーの JSON 文字列が含まれている統合レスポンス本文を、次のメソッドレスポンス本文に変換します。このメソッドレスポンス本文には、カスタムエラーの JSON オブジェクトが含まれています。

Copy
{ "errorMessage" : { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } };

API の要件によっては、カスタムエラープロパティの一部または全部をメソッドレスポンスのヘッダーパラメータとして渡す必要があります。そのためには、統合レスポンス本文からメソッドレスポンスヘッダーにカスタムエラーマッピングを適用します。

たとえば、次の Swagger 拡張は、errorMessage.errorTypeerrorMessage.httpStatuserrorMessage.trace.function、および errorMessage.trace プロパティから、それぞれ error_typeerror_statuserror_trace_function、および error_trace ヘッダーへのマッピングを定義します。

Copy
"x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function", "method.response.header.error_status": "integration.response.body.errorMessage.httpStatus", "method.response.header.error_type": "integration.response.body.errorMessage.errorType", "method.response.header.error_trace": "integration.response.body.errorMessage.trace" }, ... } } }

ランタイムに、API Gateway は integration.response.body パラメータを逆シリアル化してヘッダーマッピングを行います。ただし、この逆シリアル化は、Lambda のカスタムエラーレスポンスの本文からヘッダーへのマッピングにのみ適用され、$input.body を使用した本文から本文へのマッピングには適用されません。これらのカスタムエラーの本文からヘッダーへのマッピングでは、クライアントはメソッドレスポンスの一部として以下のヘッダーを受け取ります (error_statuserror_traceerror_trace_function、および error_type をメソッドリクエストで宣言している場合)。

Copy
"error_status":"500", "error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}", "error_trace_function":"abc()", "error_type":"InternalServerError"

統合レスポンス本文の errorMessage.trace プロパティは複合プロパティです。これは JSON 文字列として error_trace ヘッダーにマッピングされます。