Amazon API Gateway API 請求和回應資料映射參考 - Amazon API Gateway
將方法請求資料對應到整合請求參數將整合回應資料對應到方法回應標頭對應方法和整合之間的請求和回應承載

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

Amazon API Gateway API 請求和回應資料映射參考

本節會說明如何設定將資料 (包含 context、stage 或 util 變數中存放的其他資料) 從 API 方法請求資料映射到映射的整合請求參數；以及如何設定將資料 (包含其他資料) 從整合回應資料映射到方法回應參數。方法請求資料包含請求參數 (路徑、查詢字串、標頭) 和內文。整合回應資料包含回應參數 (標頭) 和內文。如需使用階段變數的詳細資訊，請參閱「API Gateway 中 REST API 的 API Gateway 階段變數參考」。

主題

將方法請求資料對應到整合請求參數

格式為路徑變數、查詢字串或標頭的整合請求參數，可以從任何已定義的方法請求參數和承載對應。

在下表中，PARAM_NAME 是指定參數類型的方法請求參數名稱。它必須符合規則表達式 '^[a-zA-Z0-9._$-]+$]'。它必須已先定義，您才能參考它。JSONPath_EXPRESSION 是請求或回應內文之 JSON 欄位的 JSONPath 表達式。

注意

"$" 字首在這個語法中予以省略。

映射的資料來源

映射表達式
方法請求路徑 method.request.path.PARAM_NAME
方法請求查詢字串 method.request.querystring.PARAM_NAME
多值方法請求查詢字串 method.request.multivaluequerystring.PARAM_NAME
方法請求標頭 method.request.header.PARAM_NAME
多值方法請求標頭 method.request.multivalueheader.PARAM_NAME
方法請求內文 method.request.body
方法請求內文 (JsonPath) method.request.body.JSONPath_EXPRESSION.
階段變數 stageVariables.VARIABLE_NAME
環境變數 context.VARIABLE_NAME 必須是支援的環境變數之一。
靜態值 'STATIC_VALUE'。STATIC_VALUE 是字串常值，而且必須以一對單引號括住。
範例 從 OpenAPI 的方法請求參數對應

下列範例顯示的 OpenAPI 程式碼片段會：

  • 將名為 methodRequestHeaderParam 的方法請求標頭對應到名為 integrationPathParam 的整合請求路徑參數

  • 將名為 methodRequestQueryParam 的多值方法請求查詢字串對應到名為 integrationQueryParam 的整合請求查詢字串


...
"requestParameters" : {
            
    "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam",        
    "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam"
            
}
...

您也可以使用 JSONPath 表達式從 JSON 請求內文中的欄位，對應整合請求參數。下表顯示方法請求內文的對應表達式及其 JSON 欄位。

範例 從 OpenAPI 的方法請求內文對應

下列範例顯示的 OpenAPI 程式碼片段將 1) 方法請求內文對應到名為 body-header 的整合請求標頭；以及對應 2) 內文的 JSON 欄位，如 JSON 表達式所表示 (petstore.pets[0].name，無 $. 字首)。


...
"requestParameters" : {
            
    "integration.request.header.body-header" : "method.request.body",
    "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name",
            
}
...

將整合回應資料對應到方法回應標頭

您可以從任何整合回應標頭或整合回應內文、$context 變數或靜態值，映射方法回應標頭參數。下表描述方法回應標頭映射表達式。

映射的資料來源 對應表達式
整合回應標頭 integration.response.header.PARAM_NAME
整合回應標頭 integration.response.multivalueheader.PARAM_NAME
整合回應內文 integration.response.body
整合回應內文 (JsonPath) integration.response.body.JSONPath_EXPRESSION
階段變數 stageVariables.VARIABLE_NAME
環境變數 context.VARIABLE_NAME 必須是支援的環境變數之一。
靜態值 'STATIC_VALUE'。STATIC_VALUE 是字串常值，而且必須以一對單引號括住。
範例 從 OpenAPI 整合回應對應的資料

下列範例顯示的 OpenAPI 程式碼片段將 1) 整合回應的 redirect.url，即 JSONPath 欄位對應到請求回應的 location 標頭；將 2) 整合回應的 x-app-id 標頭對應到方法回應的 id 標頭。


...
"responseParameters" : {
            
    "method.response.header.location" : "integration.response.body.redirect.url",
    "method.response.header.id" : "integration.response.header.x-app-id",
    "method.response.header.items" : "integration.response.multivalueheader.item",
            
}
...

對應方法和整合之間的請求和回應承載

API Gateway 使用 Velocity 範本語言 (VTL) 引擎來處理整合請求和整合回應的內文映射範本。對應範本會將方法請求承載轉譯為對應的整合請求承載，並將整合回應內文轉譯成方法回應內文。

VTL 範本使用 JSONPath 表達式、其他參數 (例如呼叫的環境與階段變數) 和公用程式函數來處理 JSON 資料。

如果模型定義成說明承載的資料結構，則 API Gateway 可以使用模型來產生整合請求或整合回應的骨架映射範本。您可以使用骨架範本協助自訂和擴展對應的 VTL 指令碼。不過，您可以從頭開始建立對應範本，且無須定義承載資料結構的模型。

選取 VTL 對應範本

API Gateway 使用下列邏輯來選取使用 Velocity 範本語言 (VTL) 的映射範本，將承載從方法請求映射到映射的整合請求，或將承載從整合回應映射到映射的方法回應。

針對請求承載，API Gateway 會將請求的 Content-Type 標頭值用作選取請求承載映射範本的金鑰。針對回應承載，API Gateway 會將傳入請求的 Accept 標頭值用作選取映射範本的金鑰。

當請求中沒有 Content-Type 標頭時，API Gateway 會假設其預設值為 application/json。對於這種請求，API Gateway 會將 application/json 用作預設金鑰來選取映射範本 (如果有已定義的映射範本)。當沒有符合此金鑰的範本時，如果 passthroughBehavior 屬性設定為 WHEN_NO_MATCH 或 WHEN_NO_TEMPLATES，則 API Gateway 會傳送未映射的承載。

當請求中未指定 Accept 標頭時，API Gateway 會假設其預設值為 application/json。在此情況下，API Gateway 會選取現有的 application/json 映射範本來映射回應承載。若未針對 application/json 定義任何範本，則 API Gateway 會選取第一個現有的範本並使用它作為預設值來映射回應承載。同樣地，當指定的 Accept 標頭值不符合任何現有的範本金鑰時，API Gateway 會使用第一個現有的範本。若未定義任何範本，API Gateway 只會傳遞未映射的回應承載。

例如，假設 API 針對請求承載定義了 application/json 範本，且針對回應承載定義了 application/xml 範本。如果用戶端在請求中設定 "Content-Type : application/json" 和 "Accept : application/xml" 標頭，則請求和回應承載都會使用對應的對應範本來處理。如果沒有 Accept:application/xml 標頭，則會使用 application/xml 對應範本來對應回應承載。若要改傳回未對應的回應承載，您必須為 application/json 設定空的範本。

選取對應範本時，只有 MIME 類型是從 Accept 和 Content-Type 標頭使用。例如，"Content-Type: application/json; charset=UTF-8" 的標頭會有已選取 application/json 金鑰的請求範本。