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

エラーレスポンスをカスタマイズするゲートウェイレスポンスをセットアップする

API Gateway は、受信リクエストを処理できない場合、統合バックエンドにリクエストを転送せずにクライアントにエラーレスポンスを返します。デフォルトでは、エラーレスポンスにエラーを説明する短いメッセージが含まれます。たとえば、未定義の API リソースに対してオペレーションを呼び出そうとすると、{ "message": "Missing Authentication Token" } というメッセージが含まれたエラーレスポンスが返されます。API Gateway に慣れていないユーザーには、メッセージの意味がわかりにくい場合があります。

一部のエラーレスポンスについては、API 開発者がカスタマイズして異なる形式で返すことが API Gateway で許可されています。たとえば、Missing Authentication Token の場合は、次の例に示すように、元のレスポンスペイロードにヒントを追加し、考えられる原因を説明できます: {"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}

API が外部交換と AWS クラウドの間を仲介する場合は、統合リクエストまたは統合レスポンスの VTL マッピングテンプレートを使用してペイロードを 1 つの形式から別の形式にマッピングします。ただし、VTL マッピングテンプレートはレスポンスが正常に返される有効なリクエストに対してのみ使用できます。無効なリクエストに対しては、API Gateway は統合を完全にバイパスしてエラーレスポンスを返します。エラーレスポンスを交換に準拠した形式にするには、カスタマイズを使用する必要があります。カスタマイズで生成されるのは、単純な変数の置換のみをサポートする VTL 以外のマッピングテンプレートです。

API Gateway で生成されたエラーレスポンスを API Gateway で生成される任意のレスポンスに一般化したものは、ゲートウェイレスポンスと呼ばれます。これにより、API Gateway で生成されたレスポンスは統合レスポンスから区別されます。ゲートウェイレスポンスのマッピングテンプレートは、$context 変数の値と $stageVariables プロパティの値にアクセスできます。また、method.request.param-position.param-name 形式のメソッドリクエストのパラメータにもアクセスできます。$context 変数の詳細については、「$context 変数へのアクセス」を参照してください。$stageVariables の詳細については、「$stageVariables 変数へのアクセス」を参照してください。メソッドリクエストのパラメータの詳細については、「マッピングテンプレートからアクセス可能なリクエストパラメータ」を参照してください。