Amazon API 閘道API請求和回應資料對應參考 - Amazon API 网关
將方法請求資料對應到整合請求參數將整合回應資料對應到方法回應標頭對應方法和整合之間的請求和回應承載

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

Amazon API 閘道API請求和回應資料對應參考

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

主題

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

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

在下表中,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 是字串常值，且必須以一對單引號括住。
範例 [開啟] 中方法要求參數的對應 API

下列範例顯示對應的 Open API 程式碼片段：

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

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


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

您也可以使用運算式從要JSON求主體中的欄位對應整合要求參JSONPath數。下表顯示了一個方法請求主體及其JSON字段的映射表達式。

範例 從 Open 中的方法請求主體映射 API

下列範例會示範將 1) 方法要求主體對應至整合要求標頭的 Open API 程式碼片段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 是字串常值，且必須以一對單引號括住。
範例 開啟中整合回應的資料對應 API

下面的示例顯示了一個 Open API 片段redirect.url，它將 1）集成響應的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閘道使用 Velocity 範本語言 (VTL) 引擎來處理整合要求和整合回應的主體對應範本。對應範本會將方法請求承載轉譯為對應的整合請求承載，並將整合回應內文轉譯成方法回應內文。

VTL範本會使用JSONPath運算式、其他參數 (例如呼叫前後關聯和階段變數)，以及公用程式函數來處理JSON資料。

如果將模型定義為描述有效負載的資料結構，APIGateway 可以使用該模型來產生整合要求或整合回應的骨架映射範本。您可以使用骨架範本做為自訂和展開對應VTL指令碼的輔助工具。不過，您可以從頭開始建立對應範本，且無須定義承載資料結構的模型。

選取對VTL應範本

APIGateway 會使用下列邏輯在 Velocity 範本語言 (VTL) 中選取對應範本，以將方法要求中的承載對應至對應的整合要求，或將整合回應的承載對應至對應的方法回應。

針對要求承載，APIGateway 會使用要求的Content-Type標頭值做為索引鍵，以選取要求承載的對應範本。對於響應有效負載，APIGateway 使用傳入請求的Accept標題值作為選擇映射模板的鍵。

當標Content-Type頭在請求中不存在時，APIGateway 假定其默認值為application/json。對於此類要求，APIGateway 會使用application/json預設金鑰來選取對應範本 (如果已定義)。當沒有任何範本符合此金鑰時，如果passthroughBehavior內容設定為WHEN_NO_MATCH或WHEN_NO_TEMPLATES，APIGateway 會透過未對映來傳遞承載。

如果未在要求中指定Accept標頭，APIGateway 會假設其預設值為application/json。在這種情況下，APIGateway 會為選取現有的對應範本，application/json以對應回應裝載。如果沒有定義的範本application/json，APIGateway 會選取第一個現有範本，並使用它做為預設來對應回應承載。同樣地，當指定的Accept標頭值與任何現有的範本金鑰不相符時，APIGateway 會使用第一個現有範本。如果沒有定義任何範本，APIGateway 只會透過未映射傳遞回應裝載。

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

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