マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする
標準 API Gateway パラメータとレスポンスコードのマッピングテンプレートを使用して、パラメータの 1 対 1 のマッピング、および統合レスポンスステータスコードの一群 (正規表現と一致する) を単一のレスポンスステータスコードにマッピングすることができます。マッピングテンプレートオーバーライドにより多対 1 のマッピングを実行する柔軟性が提供されます。標準 API Gateway マッピング後のパラメータのオーバーライドが適用されます。条件付きでマップパラメータは本文の内容または他のパラメータ値に基づきます。プログラムによってオンザフライで新しいパラメータを作成し、統合エンドポイントによりオーバーライドステータスコードが返されます。あらゆるタイプのリクエストパラメータ、レスポンスヘッダー、またはレスポンスステータスコードはオーバーライドされます。
マッピングテンプレートオーバーライドの使用例を以下に示します。
-
2 つのパラメータを連結した新しいヘッダーを作成する (または既存のヘッダーをオーバライドする) には
-
本文の内容に基づく成功または失敗コードにレスポンスコードをオーバーライドするには
-
パラメータまたはその他のパラメータの内容に基づいて、条件付きでパラメータを再マッピングするには
-
JSON 本文の内容を反復処理し、ヘッダーやクエリ文字列にキーと値のペアを再マッピングするには
マッピングテンプレートオーバーライドを作成するには、マッピングテンプレートで以下のいずれかの $context 変数を使用します。
| リクエストボディのマッピングテンプレート | レスポンスボディのマッピングテンプレート |
|---|---|
$context.requestOverride.header. |
$context.responseOverride.header. |
$context.requestOverride.path. |
$context.responseOverride.status |
$context.requestOverride.querystring. |
注記
マッピングテンプレートオーバーライドは、データマッピングが不足しているため、プロキシ統合エンドポイントで使用することはできません。統合の詳細については、API Gateway API 統合タイプの選択 を参照してください。
重要
オーバーライドが終了します。オーバーライドは各パラメータに一度だけ適用されます。同じパラメータを複数回オーバーライドしようとすると、Amazon API Gateway から 5XX レスポンスが発生します。テンプレート全体で同じパラメータを複数回オーバーライドする必要がある場合は、変数を作成してテンプレートの終了時にオーバーライドを適用することをお勧めします。テンプレートはテンプレート全体が解析された後にのみ適用されることに注意してください。「チュートリアル: API Gateway コンソールを使用して API のリクエストパラメータとヘッダーをオーバーライドする」を参照してください。
以下のチュートリアルでは、API Gateway コンソールでマッピングテンプレートオーバーライドを作成およびテストする方法を示します。これらのチュートリアルでは、開始点として PetStore サンプル API を使用します。両方のチュートリアルは、PetStore サンプル API がすでに作成されていることを前提としています。
トピック
チュートリアル: API Gateway コンソールを使用して、API の応答ステータスコードをオーバーライドする
PetStore サンプル API を使用してペットを取得するには、GET /pets/{petId} の API メソッドリクエストを使用します。{petId} は、実行時に数字をとることができるパスパラメータです。
このチュートリアルでは、エラー状態が検出された場合、GET を $context.responseOverride.status にマッピングするマッピングテンプレートを作成することで、この 400 メソッドのレスポンスコードをオーバーライドします。
https://console.aws.amazon.com/apigateway
で API Gateway コンソールにサインインします。 -
[API] で PetStore API を選択し、[リソース] を選択します。
-
[リソース] ツリーで、
/{petId}の下のGETメソッドを選択します。 [テスト] タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
-
[petId] に「
-1」と入力し、[テスト] を選択します。結果として、2 つのことが分かります。
まず、[レスポンス本文] は範囲外エラーを示します。
{ "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }次に、[ログ] ボックスの最後の行は
Method completed with status: 200で終わります。 -
[統合レスポンス] タブの [デフォルト - レスポンス] で、[編集] を選択します。
-
[マッピングテンプレート] を選択します。
-
[マッピングテンプレートの追加] を選択します。
-
[コンテンツタイプ] に、「
application/json」と入力します。 -
[テンプレート本文] で次のように入力します。
#set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end -
[Save] を選択します。
-
[テスト] タブを選択します。
-
[petId] に「
-1」と入力します。 -
結果として、[Response Body (レスポンス本文)] は範囲外エラーを示します。
{ "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }ただし、[Logs (ログ)] ボックスの最後の行は、
Method completed with status: 400で終わるようになりました。
チュートリアル: API Gateway コンソールを使用して API のリクエストパラメータとヘッダーをオーバーライドする
このチュートリアルでは、GET を他の 2 つのヘッダーを組み合わせる新しいヘッダーにマッピングするマッピングテンプレートを作成することで、$context.requestOverride.header. メソッドのリクエストヘッダーコードをオーバーライドします。header_name
https://console.aws.amazon.com/apigateway
で API Gateway コンソールにサインインします。 -
[API] で、PetStore API を選択します。
-
[リソース] ツリーで、
/petの下のGETメソッドを選択します。 -
[メソッドリクエスト] タブの [メソッドリクエストの設定] で、[編集] を選択します。
-
[HTTP リクエストヘッダー] を選択した後、[ヘッダーの追加] を選択します。
[名前] に
header1と入力します。-
[ヘッダーを追加] を選択し、
header2という名前の 2 つ目のヘッダーを作成します。 -
[Save] を選択します。
-
[統合リクエスト] タブの [統合リクエストの設定] で、[編集] を選択します。
[リクエスト本文のパススルー] で、[テンプレートが定義されていない場合 (推奨)] を選択します。
-
[マッピングテンプレート] を選択し、次の操作を行います。
[マッピングテンプレートの追加] を選択します。
[コンテンツタイプ] に、「
application/json」と入力します。[テンプレート本文] で次のように入力します。
#set($header1Override = "foo") #set($header3Value = "$input.params('header1')$input.params('header2')") $input.json("$") #set($context.requestOverride.header.header3 = $header3Value) #set($context.requestOverride.header.header1 = $header1Override) #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
-
[Save] を選択します。
-
[テスト] タブを選択します。
-
[Headers (ヘッダー)] で、[{pets}] に、次のコードをコピーします。
header1:header1Val header2:header2Val -
[Test (テスト)] を選択します。
[ログ] に、このテキストを含むエントリが表示されます。
Endpoint request headers: {header3=header1Valheader2Val, header2=header2Val, header1=foo, x-amzn-apigateway-api-id=<api-id>, Accept=application/json, multivalueheader=foo,header1Valheader2Val}
例: API Gateway CLI を使用して API のリクエストパラメータとヘッダーをオーバーライドする
次の CLI の例では、put-integration コマンドを使用してレスポンスコードをオーバーライドする方法を示しています。
aws apigateway put-integration --rest-api-id<API_ID>--resource-id<PATH_TO_RESOURCE_ID>--http-method<METHOD>--type<INTEGRATION_TYPE>--request-templates<REQUEST_TEMPLATE_MAP>
ここで、<REQUEST_TEMPLATE_MAP> は、コンテンツタイプから適用されるテンプレートの文字列へのマッピングです。マッピングは以下のような構造になっています。
Content_type1=template_string,Content_type2=template_string
または、JSON 構文です。
{"content_type1": "template_string" ...}
次の例では、put-integration-response コマンドを使用して API レスポンスコードをオーバーライドする方法を示しています。
aws apigateway put-integration-response --rest-api-id<API_ID>--resource-id<PATH_TO_RESOURCE_ID>--http-method<METHOD>--status-code<STATUS_CODE>--response-templates<RESPONSE_TEMPLATE_MAP>
<RESPONSE_TEMPLATE_MAP> は先ほどの <REQUEST_TEMPLATE_MAP> と同じ形式です。
例: SDK for JavaScript を使用して API のリクエストパラメータとヘッダーをオーバーライドする
次の例では、put-integration コマンドを使用してレスポンスコードをオーバーライドする方法を示しています。
リクエスト：
var params = { httpMethod: 'STRING_VALUE', /* required */ resourceId: 'STRING_VALUE', /* required */ restApiId: 'STRING_VALUE', /* required */ type: HTTP | AWS | MOCK | HTTP_PROXY | AWS_PROXY, /* required */ requestTemplates: { '<Content_type>': 'TEMPLATE_STRING', /* '<String>': ... */ }, }; apigateway.putIntegration(params, function(err, data) { if (err) console.log(err, err.stack); // an error occurred else console.log(data); // successful response });
レスポンス：
var params = { httpMethod: 'STRING_VALUE', /* required */ resourceId: 'STRING_VALUE', /* required */ restApiId: 'STRING_VALUE', /* required */ statusCode: 'STRING_VALUE', /* required */ responseTemplates: { '<Content_type>': 'TEMPLATE_STRING', /* '<String>': ... */ }, }; apigateway.putIntegrationResponse(params, function(err, data) { if (err) console.log(err, err.stack); // an error occurred else console.log(data); // successful response });
