マッピングテンプレートを使用して、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 メソッドのレスポンスコードをオーバーライドします。
API Gateway コンソール (https://console.aws.amazon.com/apigateway
) にサインインします。 -
[API] で、PetStore API を選択します。
-
[リソース] 列で、
GETの下の/{petId}メソッドを選択します。 -
[クライアント] ボックスで、[テスト] を選択します。
-
[{petId}] に
-1を入力して、[Test (テスト)] を選択します。結果として、2 つのことが分かります。
まず、[Response Body (レスポンス本文)] は範囲外エラーを示します。
{ "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }次に、[Logs (ログ)] ボックスの最後の行は、
Method completed with status: 200で終わります。 -
[メソッドの実行] に戻ります。[統合レスポンス] を選択し、[200] の横にある矢印を選択します。
-
[マッピングテンプレート] セクションで、[マッピングテンプレートの追加] を選択します。
-
[コンテンツタイプ] に
application/jsonと入力し、チェックマークアイコンを選択して選択項目を保存します。 -
テンプレートエリアに次のコードをコピーします。
#set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end -
[保存] を選択します。
-
[Method Execution (メソッドの実行)] に戻ります。
-
[クライアント] ボックスで、[テスト] を選択します。
-
[{petId}] に
-1を入力して、[Test (テスト)] を選択します。結果として、[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 を選択します。
-
[リソース] 列で、
GETの下の/petsメソッドを選択します。 -
[メソッドリクエスト] を選択します。
-
次のようにパラメータを作成します。
-
[HTTP リクエストヘッダー] を展開します。
-
[ヘッダーの追加] を選択します。
-
[名前] で、「
header1」と入力します。 -
チェックマークアイコンを選択して、選択を保存します。
この手順を繰り返して、
header2という 2 番目のヘッダーを作成します。 -
-
[Method Execution (メソッドの実行)] に戻ります。
-
[Integration Request (統合リクエスト)] を選択します。
-
[HTTP Headers (HTTP ヘッダー)] を展開します。作成した 2 つのヘッダー、
header1とheader2が、デフォルトのマッピング ([Mapped from (マッピング元)] の下) と共に表示されます。 -
[マッピングテンプレート] を展開します。
-
[マッピングテンプレートの追加] を選択します。
-
[コンテンツタイプ] に
application/jsonと入力し、チェックマークアイコンを選択して選択項目を保存します。 -
[Note: This template can map headers and body. (注意: このテンプレートはヘッダーと本文をマッピングできます。)] というポップアップが表示されます。
[Yes, secure this integration (はい、この統合を保護します)] を選択します。
-
テンプレートエリアに次のコードをコピーします。
#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]) -
[保存] を選択します。
-
[Method Execution (メソッドの実行)] に戻ります。
-
[クライアント] ボックスで、[テスト] を選択します。
-
[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 });
