Amazon API Gateway API リクエストおよびレスポンスデータマッピングリファレンス - Amazon API Gateway
メソッドリクエストデータを統合リクエストパラメータにマッピングする統合レスポンスデータをメソッドレスポンスヘッダーにマッピングするメソッドと統合との間でリクエストとレスポンスのペイロードをマッピングする

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

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

トピック

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

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

次の表で、PARAM_NAME は、特定のパラメータ型のメソッドリクエストパラメータの名前です。正規表現パターン '^[a-zA-Z0-9._$-]+$]' に一致する必要があります。これは参照される前に定義済みである必要があります。JSONPath_EXPRESSION は、リクエストまたはレスポンスの本文の JSON フィールドの JSONPath 式です。

注記

"$" プレフィックスは、この構文では省略されます。

マッピングされたデータソース

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

次の例は、以下のマッピングを行う OpenAPI スニペットです。

  • methodRequestHeaderParam という名前のメソッドリクエストのヘッダーから、integrationPathParam という名前の統合リクエストパスパラメータへのマッピング

  • methodRequestQueryParam という名前の複数値のメソッドリクエストから、integrationQueryParam という名前の統合リクエストのクエリ文字列へのマッピング


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

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

例 OpenAPI におけるメソッドリクエストボディからのマッピング

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


...
"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.multivalueheader.PARAM_NAME
統合レスポンスの本文 integration.response.body
統合レスポンスの本文 (JsonPath) integration.response.body.JSONPath_EXPRESSION
ステージ変数 stageVariables.VARIABLE_NAME
コンテキスト変数 サポートされるコンテキスト変数の 1 つである必要がある context.VARIABLE_NAME。
静的な値 'STATIC_VALUE'。STATIC_VALUE はリテラル文字列で、単一引用符のペアで囲まれている必要があります。
例 OpenAPI における統合レスポンスからのデータマッピング

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


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

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

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 キーが選択されます。