API Gateway での REST API のゲートウェイレスポンス
ゲートウェイレスポンスは、API Gateway によって定義されたレスポンスタイプで識別されます。レスポンスは、HTTP ステータスコード、パラメータマッピングで指定される追加のヘッダーのセット、および VTL 以外のマッピングテンプレートで生成されるペイロードで構成されます。
API Gateway REST API では、ゲートウェイレスポンスは GatewayResponse によって表されます。OpenAPI では、GatewayResponse インスタンスは x-amazon-apigateway-gateway-responses.gatewayResponse 拡張子で記述されます。
ゲートウェイレスポンスを有効にするには、API レベルでサポートされているレスポンスタイプのゲートウェイレスポンスを設定します。API Gateway からこのタイプのレスポンスが返されるたびに、ゲートウェイレスポンスに定義されているヘッダーマッピングとペイロードマッピングテンプレートに適用されてマッピングされた結果が API 発信者に返されます。
次のセクションでは、API Gateway コンソールと API Gateway REST API を使用してゲートウェイレスポンスを設定する方法を示します。
エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ
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 変数の詳細については、「データモデル、オーソライザー、マッピングテンプレート、および CloudWatch アクセスログ記録用の $context 変数」を参照してください。の詳細については、「$stageVariables」を参照してください。$stageVariables。メソッドリクエストパラメータの詳細については、「$input 変数」を参照してください。
トピック
