本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
Amazon API 閘道API請求和回應資料對應參考
本節說明如何設定從方法要求資料 (包括儲存在context、或util變數中的其他資料) 至對應整合要求參數的資料 stage,以及從整合回應資料 (包括其他資料) 到方法回應參數的資料對映。API方法請求資料包含請求參數 (路徑、查詢字串、標頭) 和內文。整合回應資料包含回應參數 (標頭) 和內文。如需使用階段變數的詳細資訊,請參閱「API閘道RESTAPIs中API的閘道階段變數參考」。
將方法請求資料對應到整合請求參數
格式為路徑變數、查詢字串或標頭的整合請求參數,可以從任何已定義的方法請求參數和承載對應。
在下表中,
是給定參數類型的方法請求參數的名稱。它必須符合規則表達式 PARAM_NAME
'^[a-zA-Z0-9._$-]+$]'
。它必須先經過定義,才能被引用。
是要求或回應主體JSON欄位的JSONPath運算式。JSONPath_EXPRESSION
注意
"$"
字首在這個語法中予以省略。
對映的資料來源 |
對映表示式 |
---|---|
方法請求路徑 | method.request.path. |
方法請求查詢字串 | method.request.querystring. |
多值方法請求查詢字串 | method.request.multivaluequerystring. |
方法請求標頭 | method.request.header. |
多值方法請求標頭 | method.request.multivalueheader. |
方法請求內文 | method.request.body |
方法請求主體(JsonPath) | method.request.body. . |
階段變數 | stageVariables. |
環境變數 | context. 必須是支援的環境變數之一。 |
靜態值 | 。 該 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數
範例 從 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. |
整合回應標頭 | integration.response.multivalueheader. |
整合回應內文 | integration.response.body |
整合回應主體 (JsonPath) | integration.response.body. |
階段變數 | stageVariables. |
環境變數 | context. 必須是支援的環境變數之一。 |
靜態值 | 。 該 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
金鑰的請求範本。