API Gatewayのマッピングテンプレートの設定例

🔶概要

API Gatewayの統合レスポンスで設定する、マッピングテンプレートを使えば、バックエンドから受け取ったレスポンスを、ある程度加工する事ができます。

以下は、VTLで記述する、テンプレートの設定例です。

🔶設定例

🔷プロパティ名の置き換え

以下の「name」と「data」のプロパティ名を、「NAMAE」、「DEETA」に置き換える例。

変換前レスポンス

{
  "name": "hoge",
  "data": {
    "param1": 10,
    "param2": 20
  }
}

テンプレート例
$input.json('$')で、バックエンドからのレスポンスのJSONデータを呼び出せます。
'$'はJSONデータ全体を指し、$input.json('$.data.param1')のようにプロパティ名を指定します。

## プロパティ名の置き換え
{
  "NAMAE": $input.json('$.name'),
  "DEETA": $input.json('$.data')
}

変換後レスポンス

{
  "NAMAE": "hoge",
  "DEETA": {
    "param1": 10,
    "param2": 20
  }
}

🔷if文による分岐

変換前レスポンス

{
  "name": "hoge",
  "data": {
    "param1": 10,
    "param2": 20
  }
}

テンプレート例
#if(評価式) #else #endの基本形で、if文が使えます。
また、以下の例のように#elseifも使えます。
以下では#{elseif}と書いていますが、{}は#elseifが文の前後の文字列によって読めなくなるのを防ぐための括り文字です。

1つ注意するのが、値を評価する際に、レスポンスをデータのオブジェクトとして呼び出す、$input.path('$')を使う点です。
$input.json('$')はJSONデータを呼び出す書き方で、JSONデータではif文で評価できません。

## if文分岐
{
  "result": #if($input.path('$.name') == "hoge")
              "ほげでした"
            #{elseif}($input.path('$.name') == "fuga")
              "ふがでした"
            #else
              "ぴよかも"
            #end,
  "data": $input.json('$.data')
}

変換後レスポンス

{
  "result": "ほげでした",
  "data": {
    "param1": 10,
    "param2": 20
  }
}

🔷レスポンスのHTTPステータスの上書き

テンプレートに#set($context.responseOverride.status = (ステータスコード))を記述する事で、リクエスト元へのレスポンスの、HTTPステータスの値を任意の値に上書きできます。

テンプレート例

#set($context.responseOverride.status = 200)
{
  "result": "error",
  "message": "エラーだけど、ステータス200で返します"
}

🔷ステージ変数の利用

テンプレートに${stageVariables.（設定したステージ変数名）}を記述する事で、ステージ変数で設定した値をセットする事ができます。

テンプレート例

## ステージ変数に「hensu=ｈｏｇｅ」を設定している場合
{
  "result": "ステージ変数も呼べます",
  "value": "値は${stageVariables.hensu}"
}

変換後レスポンス

{
  "result": "ステージ変数も呼べます",
  "value": "値はhoge"
}

🔶制限

🔷テンプレート内で、HTTPステータスを呼び出せない

テンプレート内の記述だけで、「バックエンドからのレスポンスのステータスが200だったら、○○と返す」という処理はできません。
統合レスポンスの、HTTPステータスの正規表現で、「バックエンドからのレスポンスのステータスが200の時のレスポンスは〜」のように設定する必要があります。

2019/03/05時点で、HTTPステータスを呼び出す方法がありません。

🔶参考

マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/apigateway-override-request-response-parameters.html