メニュー
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 変数へのアクセス」を参照してください。メソッドリクエストのパラメータの詳細については、「マッピングテンプレートからアクセス可能なリクエストパラメータ」を参照してください。

API Gateway のレスポンス

API Gateway のレスポンスは、API Gateway によって定義されたレスポンスタイプで識別されます。レスポンスは、HTTP ステータスコード、パラメータマッピングで指定される追加のヘッダーのセット、および VTL 以外のマッピングテンプレートで生成されるペイロードで構成されます。

API Gateway REST API では、ゲートウェイレスポンスは GatewayResponse によって表されます。Swagger では、GatewayResponse インスタンスは x-amazon-apigateway-gateway-responses.gatewayResponse 拡張子で記述されます。

ゲートウェイレスポンスを有効にするには、API レベルでサポートされているレスポンスタイプのゲートウェイレスポンスを設定します。API Gateway から該当タイプのレスポンスが返されるたびに、ゲートウェイレスポンスに定義されているヘッダーマッピングとペイロードマッピングテンプレートに適用されてマッピングされた結果が API 発信者に返されます。

次のセクションでは、API Gateway コンソールと API Gateway REST API を使用してゲートウェイレスポンスを設定する方法を示します。

API Gateway でサポートされているゲートウェイレスポンスのタイプ

API Gateway では、API 開発者がカスタマイズできる以下のゲートウェイレスポンスを公開しています。

ゲートウェイレスポンスのタイプ デフォルトのステータスコード 説明
DEFAULT_4XX Null

レスポンスタイプが未指定で、ステータスコードが 4XX のデフォルトのゲートウェイレスポンス。このフォールバックゲートウェイレスポンスのステータスコードを変更すると、他のすべての 4XX レスポンスのステータスコードが新しい値に変更されます。このステータスコードを null にリセットすると、他のすべての 4XX レスポンスのステータスコードが元の値に戻ります。

DEFAULT_5XX Null

レスポンスタイプが未指定で、ステータスコードが 5XX のデフォルトのゲートウェイレスポンス。このフォールバックゲートウェイレスポンスのステータスコードを変更すると、他のすべての 5XX レスポンスのステータスコードが新しい値に変更されます。このステータスコードを null にリセットすると、他のすべての 5XX レスポンスのステータスコードが元の値に戻ります。

ACCESS_DENIED 403

認証が失敗した場合のゲートウェイレスポンス。たとえば、カスタムまたは Amazon Cognito オーソライザーによってアクセスが拒否された場合などが該当します。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

API_CONFIGURATION_ERROR 500

API 設定が無効な場合のゲートウェイレスポンス。たとえば、無効なエンドポイントアドレスが送信された場合、バイナリサポートが有効になっているときにバイナリデータに対する Base64 デコーディングが失敗した場合、統合レスポンスマッピングがいずれのテンプレートとも一致せず、デフォルトテンプレートも設定されていない場合などが該当します。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_5XX タイプになります。

AUTHORIZER_CONFIGURATION_ERROR 500

カスタムまたは Amazon Cognito オーソライザーへの接続が失敗した場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_5XX タイプになります。

AUTHORIZER_FAILURE 500

カスタムまたは Amazon Cognito オーソライザーが発信者の認証に失敗した場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_5XX タイプになります。

BAD_REQUEST_PARAMETERS 400

有効になっているリクエストの検証に基づいてリクエストパラメータを検証できない場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

BAD_REQUEST_BODY 400

有効になっているリクエストの検証に基づいてリクエスト本文を検証できない場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

EXPIRED_TOKEN 403

AWS 認証トークンの有効期限が切れた場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

INTEGRATION_FAILURE 504

統合が失敗した場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_5XX タイプになります。

INTEGRATION_TIMEOUT 504

統合がタイムアウトした場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_5XX タイプになります。

INVALID_API_KEY 403

API キーを必要としているメソッドに対して無効な API キーが送信された場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

INVALID_SIGNATURE 403

AWS 署名が無効な場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

MISSING_AUTHENTICATION_TOKEN 403

認証トークンが見つからない場合のゲートウェイレスポンス。サポートされていない API メソッドやリソースをクライアントが呼び出そうとした場合などが該当します。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

QUOTA_EXCEEDED 429

使用量プランのクォータが超過した場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

REQUEST_TOO_LARGE 413

リクエストが大きすぎる場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

RESOURCE_NOT_FOUND 404

API リクエストが認証および認可 (API キー認証および認可を除く) に合格した後で、指定されたリソースを API Gateway で見つけることができない場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

THROTTLED 429

使用量プランレベル、メソッドレベル、ステージレベル、またはアカウントレベルのスロットリング制限を超えた場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

UNAUTHORIZED 401

カスタムまたは Amazon Cognito オーソライザーが発信者の認証に失敗した場合のゲートウェイレスポンス。

UNSUPPORTED_MEDIA_TYPE 415

厳格なパススルー動作が有効になっているときに、ペイロードがサポートされていないメディアタイプである場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで DEFAULT_4XX タイプになります。

API Gateway コンソールを使用してゲートウェイレスポンスをカスタマイズする

API Gateway コンソールを使用してゲートウェイレスポンスをカスタマイズするには

  1. API Gateway コンソールにサインインします。

  2. 既存の API を選択するか、新しい API を作成します。

  3. プライマリナビゲーションペインで API を展開し、API の下の [Gateway Responses] を選択します。

  4. [Gateway Responses] ペインで、レスポンスタイプを選択します。このチュートリアルでは、[Missing Authentication Token (403)] を例として使用します。

  5. API Gateway で生成された Status Code を変更し、API の要件を満たす別のステータスコードを返すことができます。この例では、カスタマイズにより、ステータスコードがデフォルト値 (403) から 404 に変更されます。これは、見つからないと見なすことができるサポートされていないリソースや無効なリソースをクライアントが呼び出したときに、このエラーメッセージが発生するためです。

  6. カスタムヘッダーを返すには、[Response Headers] の [Add Header] を選択します。例として、以下のカスタムヘッダーを追加します。

    Copy
    Access-Control-Allow-Origin:'a.b.c' x-request-id:method.request.header.x-amzn-RequestId x-request-path:method.request.path.petId x-request-query:method.request.querystring.q

    前述のヘッダーマッピングで、静的ドメイン名 ('a.b.c') は Allow-Control-Allow-Origin ヘッダーにマッピングされて、CORS から API へのアクセスが許可されます。x-amzn-RequestId パス変数はレスポンスの request-id にマッピングされます。受信リクエストの petId パス変数はレスポンスの request-path ヘッダーにマッピングされます。元のリクエストの q クエリパラメータはレスポンスの request-query ヘッダーにマッピングされます。

  7. [Body Mapping Templates] で、[Content Type] は application/json のままにして、[Body Mapping Template] エディタに次の本文マッピングテンプレートを入力します。

    Copy
    { "message":"$context.error.messageString", "type": "$context.error.responseType", "statusCode": "'404'", "stage": "$context.stage", "resourcePath": "$context.resourcePath", "stageVariables.a": "$stageVariables.a" }

    この例では、$context プロパティと $stageVariables プロパティを、ゲートウェイレスポンス本文のプロパティにマッピングする方法を示しています。

  8. [Save] を選択します。

  9. 新規または既存のステージに API をデプロイします。

  10. 該当する API メソッドの呼び出し URL は https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId} であると仮定して、次の CURL コマンドを呼び出してテストします。

    Copy
    curl -v -H 'x-amnz-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1

    追加のクエリ文字列パラメーター q=1 は API と互換性がないため、指定されたゲートウェイのレスポンスをトリガーするために、エラーが返されます。次のようなゲートウェイレスポンスが返されます。

    Copy
    > GET /custErr/pets/5?q=1 HTTP/1.1 Host: o81lxisefl.execute-api.us-east-1.amazonaws.com User-Agent: curl/7.51.0 Accept: */* HTTP/1.1 404 Not Found Content-Type: application/json Content-Length: 334 Connection: keep-alive Date: Tue, 02 May 2017 03:15:47 GMT x-amzn-RequestId: a2be05a4-2ee5-11e7-bbf2-df131ec50ae6 Access-Control-Allow-Origin: a.b.c x-amzn-ErrorType: MissingAuthenticationTokenException header-1: static x-request-query: 1 x-request-path: 5 X-Cache: Error from cloudfront Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront) X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA== { "message":"Missing Authentication Token", "type": MISSING_AUTHENTICATION_TOKEN, "statusCode": '404', "stage": custErr, "resourcePath": /pets/{petId}, "stageVariables.a": a }

    前述の例では、API バックエンドが Pet Store であること、さらに API にステージ変数 a が定義されていることを前提としています。

API Gateway REST API を使用してゲートウェイレスポンスをカスタマイズする

API Gateway REST API を使用してゲートウェイレスポンスをカスタマイズする前に、API が作成済みで、その識別子を取得済みであることが必要です。API 識別子を取得するには、restapi:gateway-responses リンクリレーションに従い、その結果を確認します。

API Gateway REST API を使用してゲートウェイレスポンスをカスタマイズするには

  1. GatewayResponse インスタンス全体を上書きする場合は、gatewayresponse:put アクションを呼び出して、必要な responseType を URL パスパラメータに指定し、リクエストペイロードで statusCoderesponseParameters、および responseTemplates の各マッピングを渡します。

  2. GatewayResponse インスタンスの一部を更新する場合は、gatewayresponse:update アクションを呼び出して、必要な responseType を URL パスパラメータに指定し、リクエストペイロードで必要な個別の GatewayResponse プロパティ (responseParameters マッピングや responseTemplates マッピングなど) を渡します。

Swagger でゲートウェイレスポンスのカスタマイズを設定する

API ルートレベルで x-amazon-apigateway-gateway-responses 拡張子を使用し、Swagger でゲートウェイレスポンスをカスタマイズできます。次の Swagger の定義は、MISSING_AUTHENTICATION_TOKEN タイプの GatewayResponse をカスタマイズする例を示しています。

Copy
"x-amazon-apigateway-gateway-responses": { "MISSING_AUTHENTICATION_TOKEN": { "statusCode": 404, "responseParameters": { "gatewayresponse.header.x-request-path": "method.input.params.petId", "gatewayresponse.header.x-request-query": "method.input.params.q", "gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'", "gatewayresponse.header.x-request-header": "method.input.params.Accept" }, "responseTemplates": { "application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}" } }

この例では、カスタマイズによってステータスコードをデフォルト (403) から 404 に変更します。また、ゲートウェイレスポンスに 4 つのヘッダーパラメータと、application/json メディアタイプの 1 つの本文マッピングテンプレートを追加します。