Amazon API Gateway
開発者ガイド

API Gateway マッピングテンプレートとアクセスのログ記録の変数リファレンス

このセクションでは、Amazon API Gateway がデータモデル、オーソライザー、マッピングテンプレート、および CloudWatch アクセスログ記録での使用に定義している変数と関数についてのリファレンス情報を提供します。これらの変数と関数の使用方法の詳細については、「リクエストおよびレスポンスマッピングのモデルおよびマッピングテンプレートを作成する」を参照してください。

注記

$method$integration の変数については、「Amazon API Gateway API リクエストおよびレスポンスデータマッピングリファレンス」を参照してください。

データモデル、オーソライザー、マッピングテンプレート用の $context 変数、CloudWatch アクセスログ記録

以下の $context 変数は、データモデル、オーソライザー、マッピングテンプレート、そして CloudWatch アクセスログ記録に使用することができます。

CloudWatch アクセスログ記録にのみ使用できる $context 変数については、「CloudWatch アクセスログ記録専用の $context 変数」を参照してください。

パラメータ 説明
$context.apiId

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

$context.authorizer.claims.property

メソッドの呼び出し側が認証に成功した後に Amazon Cognito ユーザープールから返されるクレームのプロパティ。詳細については、「Amazon Cognito ユーザープール をオーソライザーとして使用して REST API へのアクセスを制御する」を参照してください。

注記

$context.authorizer.claims を呼び出すと NULL が返されます。

$context.authorizer.principalId

クライアントにより送信され、API Gateway Lambda オーソライザー (以前のカスタムオーソライザー) から返されたトークンと関連付けられたプリンシパルユーザー ID。詳細については、「API Gateway Lambda オーソライザーの使用」を参照してください。

$context.authorizer.property

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

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

$context.authorizer.key の呼び出しでは "value" 文字列が返され、$context.authorizer.numKey の呼び出しでは "1" 文字列が返され、$context.authorizer.boolKey の呼び出しでは "true" 文字列が返されます。

詳細については、「API Gateway Lambda オーソライザーの使用」を参照してください。

$context.awsEndpointRequestId

AWS エンドポイントのリクエスト ID (存在する場合)。

$context.domainName

API の呼び出しに使用された完全ドメイン名。これは、受信 Host ヘッダーと同じである必要があります。

$context.domainPrefix

$context.domainName の 1 つ目のラベル。多くの場合、これは発信者/顧客識別子として使用されます。

$context.error.message

API Gateway エラーメッセージを含む文字列。この変数は、Velocity Template Language エンジン、およびアクセスログ記録では処理されない、GatewayResponse 本文マッピングテンプレートの単純な変数の置換でのみ使用できます。詳細については、「CloudWatch を使用した WebSocket API 実行のモニタリング」および「エラーレスポンスをカスタマイズするゲートウェイレスポンスをセットアップする」を参照してください。

$context.error.messageString $context.error.message を引用符で囲んだ値、つまり "$context.error.message"
$context.error.responseType

GatewayResponsetype。この変数は、Velocity Template Language エンジン、およびアクセスログ記録では処理されない、GatewayResponse 本文マッピングテンプレートの単純な変数の置換でのみ使用できます。詳細については、「CloudWatch を使用した WebSocket API 実行のモニタリング」および「エラーレスポンスをカスタマイズするゲートウェイレスポンスをセットアップする」を参照してください。

$context.error.validationErrorString

詳細な検証エラーメッセージを含む文字列。

$context.extendedRequestId API Gateway が API リクエストに割り当てる拡張 ID。デバッグ/トラブルシューティングに役立つ情報が含まれています。
$context.httpMethod

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

$context.identity.accountId

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

$context.identity.apiKey

API キーを必要とする API メソッドの場合、この変数はメソッドリクエストに関連付けられている API キーです。API キーを必要としないメソッドの場合、この変数は null になります。詳細については、「API キーを使用する使用量プランの作成と使用」を参照してください。

$context.identity.apiKeyId API キーを必要とする API リクエストに関連付けられた API キー ID。
$context.identity.caller

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

$context.identity.cognitoAuthenticationProvider

リクエストを実行している発信者が使用する Amazon Cognito 認証プロバイダーです。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。詳しくは、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 です。Lambda オーソライザーで使用されます。詳細については、「Amazon API Gateway Lambda オーソライザーからの出力」を参照してください。

$context.identity.userAgent

API 発信者の User-Agent ヘッダー。

$context.identity.userArn

認証後に識別された有効ユーザーの Amazon リソースネーム (ARN) です。詳細については、「https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html」を参照してください。

$context.path リクエストパス。たとえば、https://{rest-api-id.execute-api.{region}.amazonaws.com/{stage}/root/child の非プロキシリクエスト URL の場合、$context.path 値は /{stage}/root/child
$context.protocol HTTP/1.1 などのリクエストプロトコル。
$context.requestId

API Gateway が API リクエストに割り当てる ID。

$context.requestOverride.header.header_name

リクエストヘッダーオーバーライド。このパラメータが定義されている場合、[Integration Request (統合リクエスト)] ペインで定義されている [HTTP Headers (HTTP ヘッダー)] の代わりに使用されるヘッダーが含まれます。詳細については、「マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする」を参照してください。

$context.requestOverride.path.path_name

リクエストパスオーバーライド。このパラメータが定義されている場合、[Integration Request (統合リクエスト)] ペインで定義されている [URL Path Parameters (URL パスパラメータ)] の代わりに使用されるリクエストパスが含まれます。詳細については、「マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする」を参照してください。

$context.requestOverride.querystring.querystring_name

リクエストクエリ文字列オーバーライド。このパラメータが定義されている場合、[Integration Request (統合リクエスト)] ペインで定義されている [URL Query String Parameters (URL クエリ文字列パラメータ)] の代わりに使用されるリクエストクエリ文字列が含まれます。詳細については、「マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする」を参照してください。

$context.responseOverride.header.header_name レスポンスヘッダーオーバーライド。このパラメータが定義されている場合、[Integration Response (統合レスポンス)] ペインの [Default mapping (デフォルトのマッピング)] として定義されている [Response header (レスポンスヘッダー)] の代わりに返されるヘッダーが含まれます。詳細については、「マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする」を参照してください。
$context.responseOverride.status レスポンスステータスコードオーバーライド。このパラメータが定義されている場合、[Integration Response (統合レスポンス)] ペインの [Default mapping (デフォルトのマッピング)] として定義されている [Method response status (メソッドレスポンスのステータス)] の代わりに返されるステータスコードが含まれます。詳細については、「マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする」を参照してください。
$context.requestTime CLF 形式の要求時間 (dd/MMM/yyyy:HH:mm:ss +-hhmm)。
$context.requestTimeEpoch エポック形式のリクエスト時間。
$context.resourceId

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

$context.resourcePath

リソースへのパスです。たとえば、https://{rest-api-id.execute-api.{region}.amazonaws.com/{stage}/root/child の非プロキシリクエスト URI の場合、$context.resourcePath 値は /root/child。詳細については、「チュートリアル: HTTP 非プロキシ統合で API をビルドする」を参照してください。

$context.stage

API リクエストのデプロイステージ (BetaProd など)。

$context.wafResponseCode

AWS WAF から受け取ったレスポンス: WAF_ALLOW または WAF_BLOCK。ステージがウェブ ACL に関連付けられていない場合は、設定されません。詳細については、「AWS WAF を使用して一般的なウェブの脆弱性から Amazon API Gateway API を保護する」を参照してください。

$context.webaclArn

リクエストを許可するかブロックするかを決定するために使用されるウェブ ACL の完全な ARN。ステージがウェブ ACL に関連付けられていない場合は、設定されません。詳細については、「AWS WAF を使用して一般的なウェブの脆弱性から Amazon API Gateway API を保護する」を参照してください。

$context.xrayTraceId

X-Ray トレース用のトレース ID。詳細については、「API Gateway での AWS X-Ray のセットアップ」を参照してください。

$context 変数テンプレートの例

API メソッドが、構造化データを特定のフォーマットにする必要があるバックエンドにデータを渡す場合、マッピングテンプレートで $context 変数を使用することをお勧めします。

次の例は、統合リクエストペイロード内で、受信 $context 変数をわずかに異なる名前のバックエンド変数にマッピングするマッピングテンプレートを示しています。

注記

変数の 1 つは API キーであることに注意してください。この例では、メソッドで「API キーを要求する」が有効になっていることを前提としています。

{ "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" }

CloudWatch アクセスログ記録専用の $context 変数

以下の $context 変数は、CloudWatch アクセスログ記録でのみ使用できます。詳細については、「API Gateway CloudWatch の API ログ作成をセットアップする」を参照してください。(WebSocket API については、「CloudWatch を使用した WebSocket API 実行のモニタリング」を参照してください。)

パラメータ 説明
$context.integrationLatency 統合レイテンシー (ミリ秒)。
$context.integrationStatus 統合レスポンスのステータス。
$context.responseLatency レスポンスレイテンシー (ミリ秒)。
$context.responseLength レスポンスペイロードの長さ。
$context.status メソッドレスポンスのステータス。

$input 変数

$input 変数は、マッピングテンプレートによって処理されるメソッドリクエストペイロードとパラメータを示します。この変数は 4 つの関数を提供します。

変数と関数 説明
$input.body

文字列として raw リクエストペイロードを返します。

$input.json(x)

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

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

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

$input.params()

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

$input.params(x)

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

$input.path(x)

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

たとえば、式 $input.path('$.pets') が次のようにオブジェクトを返すとします。

[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]

$input.path('$.pets').count()"3" を返します。

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

$input 変数テンプレートの例

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

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

#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 } }

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

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

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

$input を使用した JSON マッピングテンプレートの例

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

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

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

$input を使用したマッピングテンプレートの例

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

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

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

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

$input を使用したリクエストとレスポンスの例

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

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

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" : {} } }

レスポンス:

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

マッピングのその他の例については、リクエストおよびレスポンスマッピングのモデルおよびマッピングテンプレートを作成する を参照してください。

$stageVariables

ステージ変数は、パラメータマッピングおよびマッピングテンプレートで使用できます。また、メソッド統合で使用される ARN および URL のプレースホルダーとして使用できます。詳細については、「REST API デプロイのステージ変数を設定する」を参照してください。

構文 説明
$stageVariables.<variable_name>

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

$stageVariables['<variable_name>']

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

${stageVariables['<variable_name>']}

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

$util 変数

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

注記

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

関数 説明
$util.escapeJavaScript()

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

注記

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

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

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

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

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

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

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

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

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

$util.urlDecode()

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

$util.base64Encode()

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

$util.base64Decode()

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