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

API Gateway API リクエストとレスポンスペイロードのマッピングテンプレートのリファレンス

Amazon API Gateway は、モデルとマッピングテンプレートを操作するための変数のセットを定義します。このドキュメントでは、これらの関数を説明し、入力ペイロードの使用例を示します。

$context 変数へのアクセス

$context 変数は、API 呼び出しのすべてのコンテキスト情報を保持します。

$context 変数リファレンス

パラメータ 説明
$context.apiId

API Gateway が API に割り当てる識別子です。

$context.authorizer.claims.property

メソッドの呼び出し側が認証に成功した後に Amazon Cognito ユーザープールから返されるクレームのプロパティ。

注記

$context.authorizer.claims
$context.authorizer.principalId

クライアントにより送信され、API Gateway カスタムオーソライザー Lambda 関数から返されたトークンと関連付けられたプリンシパルユーザー ID。

$context.authorizer.property

API Gateway カスタムオーソライザー Lambda 関数から返された context マップの指定されたキー/値ペアの値。たとえば、オーソライザーが次の context マップを返すとします。

Copy
"context" : { "key": "value", "numKey": 1, "boolKey": true }

この場合、$context.authorizer.key を呼び出すと value が返され、$context.authorizer.numKey を呼び出すと 1 が返され、$context.authorizer.boolKey を呼び出すと true が返されます。

$context.httpMethod

使用される HTTP メソッドです。有効な値には、DELETEGETHEADOPTIONSPATCHPOST および PUT があります。

$context.identity.accountId

リクエストに関連付けられた AWS アカウント ID です。

$context.identity.apiKey

API に関連付けられた API 所有者キーです。

$context.identity.caller

リクエストを実行している発信者のプリンシパル ID です。

$context.identity.cognitoAuthenticationProvider

リクエストを実行している発信者が使用する Amazon Cognito 認証プロバイダーです。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。

この変数や他の Amazon Cognito $context 変数の関連情報については、「Amazon Cognito アイデンティティ」を参照してください。

$context.identity.cognitoAuthenticationType

リクエストを実行している発信者の Amazon Cognito 認証タイプです。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。

$context.identity.cognitoIdentityId

リクエストを実行している発信者の Amazon Cognito アイデンティティ ID です。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。

$context.identity.cognitoIdentityPoolId

リクエストを実行している発信者の Amazon Cognito アイデンティティ プール ID です。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。

$context.identity.sourceIp

API Gateway へのリクエストを実行する TCP 接続のソース IP アドレス。

$context.identity.user

リクエストを実行しているユーザーのプリンシパル ID です。

$context.identity.userAgent

API 発信者のユーザーエージェントです。

$context.identity.userArn

認証後に識別された有効ユーザーの Amazon リソースネーム (ARN) です。

$context.requestId

API 呼び出し用に自動生成された ID です。

$context.resourceId

API Gatewayがリソースに割り当てる ID です。

$context.resourcePath

リソースへのパスです。詳細については、「HTTP エンドポイントを公開するための API Gateway API を作成する」を参照してください。

$context.stage

API コールの開発ステージです (Beta、Prod など) 。

API メソッドが呼び出すターゲットバックエンドとして AWS Lambda を使用している場合、$context 変数を使用することが必要な場合があります。たとえば、ステージが Beta か Prod かに応じて 2 つの異なるアクションを実行することが必要な場合があります。

コンテキスト変数テンプレートの例

以下に、コンテキスト変数を取得する方法の例を示します。

Copy
{ "stage" : "$context.stage", "request_id" : "$context.requestId", "api_id" : "$context.apiId", "resource_path" : "$context.resourcePath", "resource_id" : "$context.resourceId", "http_method" : "$context.httpMethod", "source_ip" : "$context.identity.sourceIp", "user-agent" : "$context.identity.userAgent", "account_id" : "$context.identity.accountId", "api_key" : "$context.identity.apiKey", "caller" : "$context.identity.caller", "user" : "$context.identity.user", "user_arn" : "$context.identity.userArn" }

$input 変数へのアクセス

$input 変数は、テンプレートによって処理される入力ペイロードとパラメータを示します。この変数は 4 つの関数を提供します。

関数リファレンス

変数と関数 説明
$input.body

文字列として raw ペイロードを返します。

$input.json(x)

この関数は、JSONPath の式を評価し、結果を JSON 文字列で返します。

たとえば $input.json('$.pets') は、ペットの構造を表す JSON 文字列を返します。

JSONPath の詳細については、JSONPath または JSONPath for Java を参照してください。

$input.params()

API 呼び出しのすべてのリクエストパラメータのマップを返します。

$input.params(x)

パラメータ名文字列 x が指定された場合に、パス、クエリ文字列、またはヘッダー値から (この順番で) メソッドリクエストパラメータの値を返します。

$input.path(x)

JSONPath 式文字列 (x) を受け取り、結果のオブジェクト表現を返します。これにより、Apache Velocity Template Language (VTL) でペイロード要素にネイティブにアクセスしてこれらの要素を操作できるようになります。

例: $input.path('$.pets').size()

JSONPath の詳細については、JSONPath または JSONPath for Java を参照してください。

クエリ文字列を取得する $input 変数やモデルを使用するまたは使用しないリクエスト本文を使用することが必要な場合があります。さらに、パラメータ、ペイロード、またはペイロードのサブセクションを AWS Lambda 関数に組み込むことが必要な場合があります。以下に、これを実行する方法の例を示します。

JSON マッピングテンプレートの例

次の例に、マッピングを使用してクエリ文字列の名前を読み取り、POST 本文全体を要素に含める方法を示します。

Copy
{ "name" : "$input.params('name')", "body" : $input.json('$') }

JSON の入力に JavaScript で解析できない文字がエスケープされずに含まれている場合、400 レスポンスが返されることがあります。上記の $util.escapeJavaScript($input.json('$')) を適用すると、JSON の入力を正しく解析できるようになります。

入力マッピングテンプレートの例

次の例に、JSONPath 式を json() メソッドに渡す方法を示します。さらに、プロパティ名の前にピリオド (.) を使用して、リクエスト本文オブジェクトの特定のプロパティを読み取ることができます。

Copy
{ "name" : "$input.params('name')", "body" : $input.json('$.mykey') }

メソッドリクエストのペイロードに、JavaScript で解析できない文字がエスケープされずに含まれている場合、400 レスポンスが返されることができます。この場合、次に示すように、マッピングテンプレートで $util.escapeJavaScript() 関数を呼び出す必要があります。

Copy
{ "name" : "$input.params('name')", "body" : $util.escapeJavaScript($input.json('$.mykey')) }

パラメーターマッピングテンプレートの例

以下のパラメーターマッピングの例では、パス、クエリ文字列、およびヘッダーを含むすべてのパラメーターが、JSON ペイロードを介して統合エンドポイントに渡されます。

Copy
#set($allParams = $input.params()) { "params" : { #foreach($type in $allParams.keySet()) #set($params = $allParams.get($type)) "$type" : { #foreach($paramName in $params.keySet()) "$paramName" : "$util.escapeJavaScript($params.get($paramName))" #if($foreach.hasNext),#end #end } #if($foreach.hasNext),#end #end } }

事実上、このマッピングテンプレートは、すべてのリクエストパラメーターを次に示すようにペイロードに出力します。

Copy
{ "parameters" : { "path" : { "path_name" : "path_value", ... } "header" : { "header_name" : "header_value", ... } 'querystring" : { "querystring_name" : "querystring_value", ... } } }

リクエストと応答の例

以下に、3 つすべての関数を使用する例を示します。

リクエストテンプレート:

Copy
Resource: /things/{id} With input template: { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : $util.escapeJavaScript($input.json('$.things')) } POST /things/abc { "things" : { "1" : {}, "2" : {}, "3" : {} } }

レスポンス:

Copy
{ "id": "abc", "count": "3", "things": { "1": {}, "2": {}, "3": {} } }

マッピングのその他の例については、「ペイロードマッピングを設定する」を参照してください。

$stageVariables 変数へのアクセス

ステージ変数を挿入するための構文は次のようになります: $stageVariables

$stageVariables のリファレンス

構文 説明
$stageVariables.<variable_name>

<variable_name> はステージ変数名を表します。

$stageVariables['<variable_name>']

<variable_name> はあらゆるステージ変数名を表します。

${stageVariables['<variable_name>']}

<variable_name> はあらゆるステージ変数名を表します。

$util 変数へのアクセス

$util 変数には、マッピングテンプレートで使用するための効用関数が含まれます。

注記

別に指定されていない限り、デフォルトの文字は UTF-8 に設定されます。

$util 変数リファレンス

機能 説明
$util.escapeJavaScript()

JavaScript 文字列ルールを使用して文字列内の文字をエスケープします。

注記

この関数は、通常の一重引用符 (') をエスケープした一重引用符 (\') に変換します。 ただし、エスケープした一重引用符は JSON で有効ではありません。 したがって、この関数からの出力を JSON のプロパティで使用する場合、エスケープした一重引用符 (\') を通常の一重引用符 (') に戻す必要があります。 これを次の例で示します:

Copy
$util.escapeJavaScript(data).replaceAll("\\'","'")
$util.parseJson()

"stringified" JSON を受け取り、結果のオブジェクト表現を返します。この関数の結果を使用して、Apache Velocity Template Language (VTL) でペイロード要素にネイティブにアクセスしてこれらの要素を操作できるようになります。たとえば、次のペイロードがあるとします。

Copy
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}

さらに、次のマッピングテンプレートを使用するとします。

Copy
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage'))) { "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0] }

この場合、次の出力が返されます。

Copy
{ "errorMessageObjKey2ArrVal" : 1 }
$util.urlEncode()

文字列を「application/x-www-form-urlencoded」形式に変換します。

$util.urlDecode()

「application/x-www-form-urlencoded」文字列をデコードします。

$util.base64Encode()

データを base64 エンコードされた文字列にエンコードします。

$util.base64Decode()

base64 エンコードされた文字列からデータをデコードします。

統合パススルーの動作

メソッドリクエストにペイロードが含まれ、Content-Type ヘッダーが、指定されたマッピングテンプレートに一致しないか、マッピングテンプレートが定義されていない場合は、クライアントで提供されたリクエストペイロードを、統合リクエストを通じて変換せずにバックエンドに渡す選択ができます。このプロセスは統合パススルーと呼ばれます。入力リクエストの実際のパススルー動作は、統合リクエストの設定中に、指定されたマッピングテンプレートに選択したオプションと、クライアントが受信リクエストで設定する Content Type ヘッダーによって決まります。次の例では、可能なパススルー動作について示します。

例 1: application/json コンテンツタイプで 1 つのマッピングテンプレートが統合リクエストで定義されている。

Content-Type ヘッダー\選択されたパススルーオプション WHEN_NO_MATCH WHEN_NO_TEMPLATE NEVER
なし (デフォルト: application/json リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。
application/json リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。
application/xml リクエストペイロードは変換されず、そのままバックエンドに送信されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。

例 2: application/xml コンテンツタイプで 1 つのマッピングテンプレートが統合リクエストで定義されている。

Content-Type ヘッダー\選択されたパススルーオプション WHEN_NO_MATCH WHEN_NO_TEMPLATE NEVER
なし (デフォルト: application/json リクエストペイロードは変換されず、そのままバックエンドに送信されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。
application/json リクエストペイロードは変換されず、そのままバックエンドに送信されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。
application/xml リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。