API Gateway 中 REST API 的映射範本轉換 - Amazon API Gateway
方法請求和整合請求整合回應和方法回應

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

API Gateway 中 REST API 的映射範本轉換

映射範本轉換會使用映射範本來修改您的整合請求或整合回應。映射範本是以 Velocity 範本語言 (VTL) 表達的指令碼，會使用 JSONPath 並根據 Content-type 標頭套用至承載。您會使用映射範本來進行映射範本轉換。本節說明與映射範本相關的概念性資訊。

下圖顯示與 PetStore 整合端點整合之 POST /pets 資源的請求生命週期。在此 API 中，使用者會傳送有關寵物的資料，而整合端點會傳回與寵物相關聯的認養費。在此請求生命週期中，映射範本轉換會篩選傳送至整合端點的請求內文，以及篩選來自整合端點的回應內文。

請求生命週期範例

以下各節說明請求和回應生命週期。

方法請求和整合請求

在上述範例中，如果這是傳送至方法請求的請求內文：

POST /pets
    HTTP/1.1
    Host:abcd1234.us-west-2.amazonaws.com
    Content-type: application/json
    
  {
    "id": 1,
    "type": "dog",
    "Age": 11,
  }

此請求內文的格式不正確，無法供整合端點使用，因此 API Gateway 會執行映射範本轉換。API Gateway 只會執行映射範本轉換，因為有針對 Content-Type application/json 定義的映射範本。如果您未針對 Content-Type 定義映射範本，則根據預設，API Gateway 會透過整合請求將內文傳遞至整合端點。若要修改此行為，請參閱 API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為。

下列映射範本會先轉換整合請求中的方法請求資料，再將其傳送至整合端點：

#set($inputRoot = $input.path('$'))
  {
    "dogId" : "dog_"$elem.id,
    "Age": $inputRoot.Age
  }

  1. $inputRoot 變數代表上一節中原始 JSON 資料的根物件。指令以 # 符號開始。

  2. dog 是使用者的 id 和字串值的串連。

  3. Age 來自方法請求內文。

然後，下列輸出會轉送至整合端點：

{
    "dogId" : "dog_1",
    "Age": 11
  }

整合回應和方法回應

成功對整合端點發出請求後，端點會將回應傳送至 API Gateway 的整合回應。以下是來自整合端點的輸出資料範例：

{
    "dogId" : "dog_1",
    "adoptionFee": 19.95,
}

方法回應預期的承載與整合回應傳回的承載不同。API Gateway 會執行映射範本轉換。API Gateway 只會執行映射範本轉換，因為有針對 Content-Type application/json 定義的映射範本。如果您未針對 Content-Type 定義映射範本，則根據預設，API Gateway 會透過整合回應將內文傳遞至方法回應。若要修改此行為，請參閱 API Gateway 中 REST API 沒有映射範本時，承載的方法請求行為。

#set($inputRoot = $input.path('$'))
  {
    "adoptionFee" : $inputRoot.adoptionFee,
  }

下列輸出會傳送至方法回應：

{"adoptionFee": 19.95}

映射範本轉換範例至此完成。我們建議您盡可能使用代理整合來轉換資料，而不要使用映射範本轉換。如需詳細資訊，請參閱選擇 API Gateway API 整合類型。