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

Amazon API Gateway API リクエストおよびレスポンスデータのマッピング

このセクションでは、API のメソッドリクエストデータ (contextstage、または util 変数に保存された他のデータも含む) から対応する統合リクエストパラメータへのデータマッピングと、統合レスポンスデータ (他のデータも含む) からメソッドレスポンスパラメータへのデータマッピングを設定する方法について説明します。メソッドリクエストデータには、リクエストパラメーター (パス、クエリ文字列、ヘッダー) と本文が含まれます。統合レスポンスデータには、レスポンスパラメーター (ヘッダー) と本文が含まれます。ステージ変数の使用の詳細については、「Amazon API Gateway ステージ変数のリファレンス」を参照してください。

メソッドリクエストデータを統合リクエストパラメータにマッピングする

パス変数、クエリ文字列、またはヘッダーの形式の統合リクエストパラメーターは、定義されたどのメソッドリクエストパラメーターとペイロードからもマッピングできます。

統合リクエストデータのマッピング式

マッピングされたデータソース マッピング式
メソッドリクエストのパス method.request.path.PARAM_NAME
メソッドリクエストのクエリ文字列 method.request.querystring.PARAM_NAME
メソッドリクエストのヘッダー method.request.header.PARAM_NAME
メソッドリクエスト本文 method.request.body
メソッドリクエスト本文 (JsonPath) method.request.body.JSONPath_EXPRESSION
ステージ変数 stageVariables.VARIABLE_NAME
コンテキスト変数 サポートされるコンテキスト変数の 1 つである必要がある context.VARIABLE_NAME
静的な値 'STATIC_VALUE'STATIC_VALUE はリテラル文字列で、単一引用符のペアで囲まれている必要があります。

ここで、PARAM_NAME は、特定のパラメーター型のメソッドリクエストパラメーターの名前です。これは参照される前に定義済みである必要があります。JSONPath_EXPRESSION は、リクエストまたはレスポンスの本文の JSON フィールドの JSONPath 式です。ただし、「$.」というプレフィックスは、この構文では省略されます。

例 Swagger におけるメソッドリクエストパラメーターからのマッピング

次の例は、1) methodRequestHeadParam という名前のメソッドリクエストのヘッダーを integrationPathParam という名前の統合リクエストのパスパラメーターにマッピングし、2) methodRequestQueryParam という名前のメソッドリクエストのクエリ文字列を integrationQueryParam という名前の統合リクエストのクエリ文字列にマッピングする Swagger スニペットを示しています。

Copy
... "requestParameters" : { "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam", "integration.request.querystring.integrationQueryParam" : "method.request.querystring.methodRequestQueryParam" } ...

統合リクエストのパラメーターは、JSONPath 式 を使用して JSON リクエスト本文のフィールドからマッピングすることもできます。次の表は、メソッドリクエストの本文および JSON フィールドのマッピング式を示しています。

例 Swagger におけるメソッドリクエスト本文からのマッピング

次の例は、1) メソッドリクエスト本文を body-header という名前の統合リクエストのヘッダーにマッピングし、2) 本文の JSON フィールドを JSON 式 (petstore.pets[0].name$. プレフィックスなし) で示されるようにマッピングする Swagger スニペットを示しています。

Copy
... "requestParameters" : { "integration.request.header.body-header" : "method.request.body", "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name", } ...

統合レスポンスデータをメソッドレスポンスヘッダーにマッピングする

メソッドレスポンスヘッダーのパラメータは、任意の統合レスポンスヘッダー/統合レスポンス本文、$context 変数、または静的な値からマッピングできます。

メソッドレスポンスヘッダーのマッピング式

マッピングされたデータソース マッピング式
統合レスポンスのヘッダー integration.response.header.PARAM_NAME
統合レスポンスの本文 integration.response.body
統合レスポンスの本文 (JsonPath) integration.response.body.JSONPath_EXPRESSION
ステージ変数 stageVariables.VARIABLE_NAME
コンテキスト変数 サポートされるコンテキスト変数の 1 つである必要がある context.VARIABLE_NAME
静的な値 'STATIC_VALUE'STATIC_VALUE はリテラル文字列で、単一引用符のペアで囲まれている必要があります。

例 Swagger における統合レスポンスからのデータマッピング

次の例は、1) 統合レスポンスの redirect.url JSONPath フィールドをリクエストレスポンスの location ヘッダーにマッピングし、2) 統合レスポンスの x-app-id ヘッダーをメソッドレスポンスの id ヘッダーにマッピングする Swagger スニペットを示しています。

Copy
... "responseParameters" : { "method.response.header.location" : "integration.response.body.redirect.url", "method.response.header.id" : "integration.response.header.x-app-id", } ...

メソッドおよび統合間でリクエストとレスポンスのペイロードをマッピングする

API Gateway では、Velocity Template Language (VTL) エンジンを使用して、統合リクエストと統合レスポンスの本文マッピングテンプレートを処理します。マッピングテンプレートは、メソッドリクエストのペイロードを対応する統合リクエストのペイロードに変換し、統合レスポンスの本文をメソッドレスポンスの本文に変換します。

VTL テンプレートは、JSONPath 式、呼び出しコンテキストやステージ変数などの他のパラメータ、およびユーティリティ関数を使用して JSON データを処理します。

ペイロードのデータ構造を記述するモデルが定義されている場合、API Gateway はそのモデルを使用して統合リクエストや統合レスポンスのスケルトンマッピングテンプレートを生成できます。スケルトンテンプレートを利用してマッピング VTL スクリプトをカスタマイズしたり拡張したりできます。ただし、ペイロードのデータ構造のモデルを定義せずに、マッピングテンプレートを最初から作成することもできます。

VTL マッピングテンプレートを選択する

API Gateway は、以下のロジックを使用して、Velocity Template Language (VTL) のマッピングテンプレートの選択、メソッドリクエストから対応する統合リクエストへのペイロードのマッピング、統合レスポンスから対応するメソッドレスポンスへのペイロードのマッピングを行います。

リクエストペイロードの場合、API Gateway はリクエストの Content-Type ヘッダー値をキーとして使用して、リクエストペイロードのマッピングテンプレートを選択します。レスポンスペイロードの場合、API Gateway は受信リクエストの Accept ヘッダー値をキーとして使用して、マッピングテンプレートを選択します。

Content-Type ヘッダーがリクエストにない場合、API Gateway はデフォルト値が application/json であると見なします。そのようなリクエストでは、API Gateway は application/json をデフォルトキーとして使用してマッピングテンプレートを選択します (定義されている場合)。このキーに一致するテンプレートがない場合、passthroughBehavior プロパティが WHEN_NO_MATCH または WHEN_NO_TEMPLATES に設定されていれば、API Gateway はペイロードをマッピングせずに渡します。

Accept ヘッダーがリクエストで指定されていない場合、API Gateway はそのデフォルト値が application/json であると見なします。この場合、API Gateway は application/json の既存のマッピングテンプレートを選択してレスポンスペイロードをマッピングします。application/json のテンプレートが定義されていない場合、API Gateway は最初の既存のテンプレートを選択してデフォルトとして使用し、レスポンスペイロードをマッピングします。同様に、指定された Accept ヘッダー値が既存のテンプレートキーに一致しない場合、API Gateway は最初の既存のテンプレートを使用します。テンプレートが定義されていない場合、API Gateway はレスポンスペイロードをマッピングしないまま渡します。

たとえば、API でリクエストペイロードの application/json テンプレートが定義されており、レスポンスペイロードの application/xml テンプレートが定義されているとします。クライアントが "Content-Type : application/json" と、 "Accept : application/xml" ヘッダーをリクエストに設定している場合、リクエストペイロードとレスポンスペイロードの両方が対応するマッピングテンプレートを使用して処理されます。Accept:application/xml ヘッダーがない場合、application/xml マッピングテンプレートを使用してレスポンスペイロードがマッピングされます。マッピングされていないレスポンスペイロードを代わりに返すには、application/json の空のテンプレートを設定する必要があります。

マッピングテンプレートを選択するとき、Accept ヘッダーおよび Content-Type ヘッダーから使用されるのは MIME タイプだけです。たとえば、"Content-Type: application/json; charset=UTF-8" のヘッダーの場合、リクエストテンプレートで application/json キーが選択されます。