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

Amazon API Gateway API リクエストとレスポンスパラメーターのマッピングのリファレンス

このセクションでは、contextstage、または util 変数に保存された他のデータを含めて、API のメソッドリクエストデータからデータマッピングを対応する統合リクエストパラメーターに対して設定する方法、および他のデータを含めて、統合レスポンスデータからメソッドレスポンスパラメーターに設定する方法について説明します。メソッドリクエストデータには、リクエストパラメーター (パス、クエリ文字列、ヘッダー) と本文が含まれます。統合レスポンスデータには、レスポンスパラメーター (ヘッダー) と本文が含まれます。ステージ変数の使用の詳細については、「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", } ...

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

メソッドレスポンスヘッダーのパラメーターは、任意の統合レスポンスヘッダー、または統合レスポンス本文からマッピングできます。

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

マッピングされたデータソース マッピング式
統合レスポンスのヘッダー 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", } ...

リクエスト本文とレスポンス本文を変換する

統合リクエストとメソッドレスポンスの本文は、「Velocity Template Language (VTL)」に記載されているマッピングテンプレートを使用して、それぞれメソッドリクエストおよび統合レスポンスの本文から変換することができます。 JSON データは、VTL ロジックおよび JSONPath 式を使用して操作できます。また、HTTP パラメーター、呼び出しコンテキスト、およびステージ変数からのデータを追加で含めることもできます。

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

メソッドリクエスト本文を統合リクエスト本文に変換するために使用するリクエストのマッピングテンプレートは、クライアントリクエストで送信された「Content-Type」ヘッダーの値によって選択されます。

統合レスポンス本文をメソッドリクエスト本文に変換するために使用するレスポンスのマッピングテンプレートは、クライアントリクエストで送信された「Accept」ヘッダーの値によって選択されます。

たとえば、クライアントから "Content-Type : application/xml" および "Accept : application/json" のヘッダーが送信された場合、application/xml キーを持つリクエストテンプレートは統合リクエストに使用され、application/json キーを持つレスポンステンプレートはメソッドレスポンスに使用されます。

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