API Gatewayのマッピングテンプレートについて

technologies

ベンジャミンのクワバラです。

re:Invent2024のGamedayに参加したのですが、そのミッションの中で「既に存在するDynamoDBを検索するためのAPIを作成する」必要があり、その過程でAPI Gatewayのマッピングテンプレートについて知ったので備忘録として残します。あまりre:Inventとは関係ありませんが…

はじめに

API Gatewayのマッピングテンプレートは、リクエストやレスポンスのデータを変換する強力なツールです。今回は、マッピングテンプレートの基本と実践的な使用例を紹介します。

※このブログではマッピングテンプレートの書き方紹介に留めて、API Gatewayへの導入方法は割愛します。

マッピングテンプレートとは

マッピングテンプレートは、Velocity Template Language (VTL)で記述されたスクリプトで、JSONPathを使用してペイロードに適用されます。これにより、以下のような操作が可能になります

  • APIのリクエストおよびレスポンスの形式変換
  • パラメータやステータスコードの上書き
  • AWSサービスとの統合時のデータ選択

基本的な使用例

プロパティ名の変更
この例では、「name」と「data」のプロパティ名を「NAMAE」と「DEETA」に変更しています。

{
  "NAMAE": $input.json('$.name'),
  "DEETA": $input.json('$.data')
}

この例では、「name」と「data」のプロパティ名を「NAMAE」と「DEETA」に変更しています。

条件分岐の使用
"result": #if($input.path('$.name') == "hoge")
  "ほげ"
#{elseif}($input.path('$.name') == "fuga")
  "ふが"
#else
  "ぴよ"
#end

VTLを使用して、入力データに基づいて異なる結果を返すことができます。

高度な使用例

HTTPステータスの上書き

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

バックエンドのレスポンスに関わらず、特定のHTTPステータスを設定できます。

ステージ変数の利用

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

注意点

  • テンプレート内でHTTPステータスを直接参照することはできません。
  • 複雑なデータ変換には、十分なテストが必要です。

DynamoDBの全レコードを返すサンプル

DynamoDBの全レコードを取得するためには、scanオペレーションを使用します。以下に、API Gatewayのマッピングテンプレートでこれを実現する例を示します。

{
    "TableName": "YourTableName",
    "Limit": 1000
}

このマッピングテンプレートは、指定したテーブルから最大1000件のレコードを取得します。

注意点

  • Limitパラメータは、1回のスキャンで取得するアイテム数を制限します。大規模なテーブルの場合、全レコードを取得するには複数回のスキャンが必要になる可能性があります。
  • 大量のデータを返す場合、レスポンスのサイズに注意が必要です。API Gatewayには応答サイズの制限があります。

ページネーションの実装

大規模なテーブルの全レコードを取得する場合、ページネーションを実装することをお勧めします。以下のようにマッピングテンプレートを修正できます

{
    "TableName": "YourTableName",
    "Limit": 1000
    #if($input.params('LastEvaluatedKey'))
    ,"ExclusiveStartKey": $util.parseJson($input.params('LastEvaluatedKey'))
    #end
}

このテンプレートでは、クライアントからLastEvaluatedKeyパラメータが提供された場合、それを使用して次のページのスキャンを開始します。

まとめ

以上がAPI Gatewayマッピングテンプレートの紹介になります。マッピングテンプレートはLambdaを利用せずにAPI GatewayとDynamoDBだけで完結するため構築後の保守が楽になることが見込めますが、複雑な検索要件の場合はLambdaを利用する必要があるため、要件によって選択する必要があります。

Related posts