API Gateway マッピングテンプレートとアクセスのログ記録の変数リファレンス - Amazon API Gateway
データモデル、オーソライザー、マッピングテンプレート、および CloudWatch アクセスログ記録用の $context 変数$context 変数テンプレートの例アクセスログ記録専用の $context 変数$input 変数$input 変数テンプレートの例$stageVariables$util 変数

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

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

注記

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

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

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

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

パラメータ 説明
$context.accountId

API 所有者の AWS アカウント ID。
$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.deploymentId

API デプロイの 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

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

詳細な検証エラーメッセージを含む文字列。
$context.extendedRequestId API Gateway が生成して API リクエストに割り当てる拡張 ID。拡張リクエスト ID には、デバッグとトラブルシューティングに役立つ情報が含まれています。
$context.httpMethod

使用される HTTP メソッドです。有効な値には、DELETE、GET、HEAD、OPTIONS、PATCH、POST および PUT があります。
$context.identity.accountId

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

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

リクエストに署名した発信者のプリンシパル ID。IAM 認可を使用するリソースでサポートされています。
$context.identity.cognitoAuthenticationProvider

リクエスト元の発信者が使用するすべての Amazon Cognito 認証プロバイダーのカンマ区切りのリスト。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。

たとえば、Amazon Cognito ユーザープールのアイデンティティの場合、cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim

利用可能な Amazon Cognito 認証プロバイダーについては、「Amazon Cognito 開発者ガイド」の「フェデレーティッド ID の使用」を参照してください。
$context.identity.cognitoAuthenticationType

リクエストを行う発信者の Amazon Cognito 認証タイプ。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。有効な値は、認証されたアイデンティティauthenticatedおよび認証されていないアイデンティティunauthenticatedです。
$context.identity.cognitoIdentityId

リクエストを行う発信者の Amazon Cognito ID。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。
$context.identity.cognitoIdentityPoolId

リクエストを行う発信者の Amazon Cognito ID プール ID。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。
$context.identity.principalOrgId

AWS 組織 ID。
$context.identity.sourceIp

API Gateway エンドポイントへのリクエストを行う即時 TCP 接続のソース IP アドレス。
$context.identity.clientCert.clientCertPem

クライアントが相互 TLS 認証中に提示した PEM エンコードされたクライアント証明書。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。
$context.identity.clientCert.subjectDN

クライアントが提示する証明書のサブジェクトの識別名。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。
$context.identity.clientCert.issuerDN

クライアントが提示する証明書の発行者の識別名。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。
$context.identity.clientCert.serialNumber

証明書のシリアル番号。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。
$context.identity.clientCert.validity.notBefore

証明書が無効になる前の日付。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。
$context.identity.clientCert.validity.notAfter

証明書が無効になった日付。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。
$context.identity.vpcId

API Gateway エンドポイントへのリクエストを行う VPC の VPC ID。
$context.identity.vpceId

API Gateway エンドポイントへのリクエストを行う VPC エンドポイントの VPC エンドポイント ID。プライベート API がある場合にのみ表示されます。
$context.identity.user

リソースアクセスに対して許可されるユーザーのプリンシパル識別子。IAM 認可を使用するリソースでサポートされています。
$context.identity.userAgent

API 発信者の User-Agent ヘッダー。
$context.identity.userArn

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

リクエストが canary に送信された場合は true を返し、リクエストが canary に送信されなかった場合は false を返します。canary が有効になっている場合にのみ表示されます。
$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 などのリクエストプロトコル。
注記

API Gateway API は HTTP/2 リクエストを受け入れることができますが、API Gateway は HTTP/1.1 を使用してバックエンド統合にリクエストを送信します。その結果、クライアントが HTTP/2 を使用するリクエストを送信した場合でも、リクエストプロトコルは HTTP/1.1 として記録されます。
$context.requestId

リクエストの ID。クライアントは、このリクエスト ID を上書きできます。API Gateway が生成する一意のリクエスト ID に $context.extendedRequestId を使用します。
$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 非プロキシ統合を使用して REST API を作成する」を参照してください。
$context.stage

API リクエストのデプロイステージ (Beta、Prod など)。
$context.wafResponseCode

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

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

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

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

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

注記

変数の 1 つは API キーです。この例では、メソッドが 1 つの 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"
}

このマッピングテンプレートの出力は、次のようになります。

{
  stage: 'prod',
  request_id: 'abcdefg-000-000-0000-abcdefg',
  api_id: 'abcd1234',
  resource_path: '/',
  resource_id: 'efg567',
  http_method: 'GET',
  source_ip: '192.0.2.1',
  user-agent: 'curl/7.84.0',
  account_id: '111122223333',
  api_key: 'MyTestKey',
  caller: 'ABCD-0000-12345',
  user: 'ABCD-0000-12345',
  user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}

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

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

パラメータ 説明
$context.authorize.error 認可エラーメッセージ。
$context.authorize.latency 認可レイテンシー (ミリ秒単位)。
$context.authorize.status 認可の試行から返されたステータスコード。
$context.authorizer.error オーソライザーから返されたエラーメッセージ。
$context.authorizer.integrationLatency 許可統合レイテンシー (ミリ秒)。
$context.authorizer.integrationStatus Lambda オーソライザーから返されたステータスコード。
$context.authorizer.latency オーソライザーのレイテンシー (ミリ秒単位)。
$context.authorizer.requestId AWS エンドポイントのリクエスト ID。
$context.authorizer.status オーソライザーから返されたステータスコード。
$context.authenticate.error 認証の試行から返されたエラーメッセージ。
$context.authenticate.latency 認証レイテンシー (ミリ秒単位)。
$context.authenticate.status 認証の試行から返されたステータスコード。
$context.customDomain.basePathMatched

受信リクエストが一致した API マッピングのパス。クライアントがカスタムドメイン名を使用して API にアクセスする場合に適用されます。たとえば、クライアントがリクエストを https://api.example.com/v1/orders/1234 に送信し、リクエストがパス v1/orders を持つ API マッピングと一致する場合 、値は v1/orders になります。詳細については、「API ステージを REST API のカスタムドメイン名にマッピングする」を参照してください。
$context.endpointType

API のエンドポイントタイプ。
$context.integration.error 統合から返されたエラーメッセージ。
$context.integration.integrationStatus Lambda プロキシ統合の場合、バックエンドの Lambda 関数コードからではなく、AWS Lambda から返されるステータスコード。
$context.integration.latency 統合レイテンシー (ミリ秒)。$context.integrationLatency と同等です。
$context.integration.requestId AWS エンドポイントのリクエスト ID。$context.awsEndpointRequestId と同等です。
$context.integration.status 統合から返されたステータスコード。Lambda プロキシ統合では、これは Lambda 関数コードから返されたステータスコードです。
$context.integrationLatency 統合レイテンシー (ミリ秒)。
$context.integrationStatus Lambda プロキシ統合の場合、このパラメータはバックエンド Lambda 関数コードからではなく、AWS Lambda から返されるステータスコードを表します。
$context.responseLatency レスポンスレイテンシー (ミリ秒)。
$context.responseLength レスポンスペイロードの長さ (バイト単位)。
$context.status メソッドレスポンスのステータス。
$context.waf.error から返されたエラーメッセージAWS WAF
$context.waf.latency AWS WAF レイテンシー (ミリ秒単位)。
$context.waf.status から返されたステータスコードAWS WAF
$context.xrayTraceId

X-Rayトレースのトレース ID。詳細については、「API Gateway REST API で AWS X-Ray を設定する」を参照してください。

$input 変数

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

変数と関数 説明
$input.body

文字列として raw リクエストペイロードを返します。$input.body を使用して、浮動小数点数全体 (10.00 など) を保持できます。
$input.json(x)

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

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

JSONPath の詳細については、JSONPath または JSONPath for Java を参照してください。
$input.params()

すべてのリクエストパラメータのマップを返します。インジェクション攻撃の可能性を避けるため、$util.escapeJavaScript を使用して結果をサニタイズすることをお勧めします。リクエストのサニタイズを完全に制御するには、テンプレートなしでプロキシ統合を使用し、統合でリクエストのサニタイズを処理します。
$input.params(x)

パラメータ名文字列 x が指定された場合に、パス、クエリ文字列、またはヘッダー値から (この順番で検索される) メソッドリクエストパラメータの値を返します。インジェクション攻撃の可能性を避けるため、$util.escapeJavaScript を使用してパラメータをサニタイズすることをお勧めします。パラメータのサニタイズを完全に制御するには、テンプレートなしでプロキシ統合を使用し、統合でリクエストのサニタイズを処理します。
$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').size() は "3" を返します。

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

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

以下の例は、マッピングテンプレートで $input 変数を使用する方法を示しています。これらの例を試すには、入力イベントを API Gateway に返す Mock 統合または Lambda 非プロキシ統合を使用できます。

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

次の例では、path、querystring、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
  }
}

以下の入力パラメータを含むリクエストの場合:

  • myparam という名前のパスパラメータ

  • クエリ文字列パラメータ querystring1=value1,value2&querystring2=value3

  • ヘッダー "header1" : "value1"、"header2" : "value2"、"header3" : "value3"

このマッピングテンプレートの出力は、次のようになります。

{
  "params" : {
        "path" : {
            "path" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

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

クエリ文字列を取得する $input 変数やモデルを使用するまたは使用しないリクエストボディを使用することが必要な場合があります。さらに、パラメータとペイロードまたはペイロードのサブセクションを取得することもできます。以下の 3 つ例は、これを行う方法を示しています。

次の例では、マッピングテンプレートを使用してペイロードのサブセクションを取得します。この例では、入力パラメータ name と、さらに POST 本文全体を取得します。

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

クエリ文字列パラメータ name=Bella&type=dog と次の本文を含むリクエストの場合:

{
    "Price" : "249.99",
    "Age": "6"
}

このマッピングテンプレートの出力は、次のようになります。

{
    "name" : "Bella",
    "body" : {"Price":"249.99","Age":"6"}
}

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

前の例に $util.escapeJavaScript($input.json('$')) を適用した結果は次のとおりです。

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

この場合、このマッピングテンプレートの出力は、次のようになります。

{
    "name" : "Bella",
    "body": {\"Price\":\"249.99\",\"Age\":\"6\"}
}

JSONPath 式の例

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

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

クエリ文字列パラメータ name=Bella&type=dog と次の本文を含むリクエストの場合:

{
    "Price" : "249.99",
    "Age": "6"
}

このマッピングテンプレートの出力は、次のようになります。

{
    "name" : "Bella",
    "body" : "6"
}

メソッドリクエストのペイロードに JavaScript で解析できない文字がエスケープされずに含まれている場合、API Gateway は 400 レスポンスを返すことがあります。JSON の入力を正しく解析できるようにするには、$util.escapeJavaScript() を適用します。

前の例に $util.escapeJavaScript($input.json('$.Age')) を適用した結果は次のとおりです。

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

この場合、このマッピングテンプレートの出力は、次のようになります。

{
    "name" : "Bella",
    "body": "\"6\""
}

リクエストとレスポンスの例

次の例では、パス /things/{id} でリソースに $input.params()、$input.path()、$input.json() を使用しています。

{
    "id" : "$input.params('id')",
    "count" : "$input.path('$.things').size()",
    "things" : $input.json('$.things')"
}

パスパラメータ 123 と次の本文を含むリクエストの場合:

{
      "things": {
            "1": {},
            "2": {},
            "3": {}
      }
}

このマッピングテンプレートの出力は、次のようになります。

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

メソッドリクエストのペイロードに JavaScript で解析できない文字がエスケープされずに含まれている場合、API Gateway は 400 レスポンスを返すことがあります。JSON の入力を正しく解析できるようにするには、$util.escapeJavaScript() を適用します。

前の例に $util.escapeJavaScript($input.json('$.things')) を適用した結果は次のとおりです。

{
     "id" : "$input.params('id')",
     "count" : "$input.path('$.things').size()",
     "things" : "$util.escapeJavaScript($input.json('$.things'))"
}

このマッピングテンプレートの出力は、次のようになります。

{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}

マッピングのその他の例については、REST API のマッピングテンプレート を参照してください。

$stageVariables

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

構文 説明
$stageVariables.<variable_name>, $stageVariables['<variable_name>'], または ${stageVariables['<variable_name>']}

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

$util 変数

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

注記

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

関数 説明
$util.escapeJavaScript()

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

注記

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

 "input" : "$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 エンコードされた文字列からデータをデコードします。