API 閘道映射範本和存取日誌變數參考

本節提供 Amazon API Gateway 定義用於資料模型、授權方、映射範本和 CloudWatch 存取日誌的變數和函數參考資訊。如需如何使用這些變數和函數的詳細資訊，請參閱的映射範本 REST APIs。如需 Velocity 範本語言 （VTL） 的詳細資訊，請參閱VTL參考 。

$context 資料模型、授權方、映射範本和 CloudWatch 存取記錄的變數

下列$context變數可用於資料模型、授權方、映射範本和 CloudWatch 存取日誌。API Gateway 可能會新增其他內容變數。

如需只能在 CloudWatch 存取日誌中使用的$context變數，請參閱 僅適用於存取記錄的 $context 變數。

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

$context 變數範本範例

如果您的API方法將結構化資料傳遞至需要資料以特定格式顯示的後端，您可能想要在映射範本中使用$context變數。

以下範例顯示一個映射範本，其會將傳入的 $context 變數映射至整合請求承載中名稱稍有不同的後端變數：

{
    "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 RESTAPIs中設定 CloudWatch 的記錄。（如需 WebSocket APIs，請參閱 使用 CloudWatch 指標監控 WebSocket API執行。）

$input 變數

$input 變數代表映射範本要處理的方法請求承載和參數。它提供下列函數：

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

$input 變數範本範例

下列範例示範如何在映射範本中使用$input變數。您可以使用模擬整合或 Lambda 非代理整合，將輸入事件傳回給 API Gateway，以嘗試這些範例。

參數對應範本範例

下列範例會透過JSON承載將所有請求參數傳遞至整合端點header，包括 querystring、 path和 ：

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

對於包含下列輸入參數的請求：

此映射範本的輸出應如下所示：

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

JSON 映射範本範例

建議您使用 $input 變數來取得查詢字串和請求內文，而不論是否使用模型。您可能也想要取得 參數和承載，或承載的子區段。下列三個範例示範如何執行此操作。

下列範例使用映射範本來取得承載的子區段。此範例會取得輸入參數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，APIGateway 可能會傳回 400 回應。套用$util.escapeJavaScript($input.json('$'))以確保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，APIGateway 可能會傳回400回應。套用$util.escapeJavaScript()以確保JSON輸入可以正確剖析。

$util.escapeJavaScript($input.json('$.Age')) 套用的上一個範例如下所示：

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

在此情況下，此映射範本的輸出應如下所示：

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

請求和回應範例

下列範例$input.json()針對路徑為 的資源使用 $input.params()$input.path()、 和 /things/{id}：

{
    "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，APIGateway 可能會傳回400回應。套用$util.escapeJavaScript()以確保JSON輸入可以正確剖析。

$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 APIs」。

$stageVariables

階段變數可用於參數映射和映射範本，以及作為方法整合中ARNs和URLs方法整合中使用的預留位置。如需詳細資訊，請參閱RESTAPI在API閘道中使用階段變數。

$util 變數

$util 變數包含要在映射範本中使用的公用程式函數。

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

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

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

{
   "errorMessageObjKey2ArrVal" : 1
}