使用 API Gateway 主控台設定請求與回應資料映射 - Amazon API Gateway

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

使用 API Gateway 主控台設定請求與回應資料映射

若要使用 API Gateway 主控台來定義 API 的整合請求/回應，請遵循這些說明進行。

注意

這些說明假設您已完成使用 API Gateway 主控台設定 API 整合請求中的步驟。

  1. 在 [資源] 窗格中，選擇您的方法。

  2. 在整合請求索引標籤上，於整合請求設定下，選擇編輯。

  3. 選擇要求主體傳遞的選項，以設定未對應內容類型的方法要求主體如何透過整合要求傳遞，而不需轉換至 Lambda 函數、HTTP Proxy 或 AWS 服務 Proxy。共有三個選項：

    • 當方法請求內容類型不符合與下一個步驟中定義之映射範本相關聯的任何內容類型時，如果您想要讓方法請求內文透過整合請求傳遞到後端而不進行轉換，請選擇沒有範本符合請求內容類型標頭時。

      注意

      呼叫 API Gateway API 時，您可以透過在整合資源上將 WHEN_NO_MATCH 設定為 passthroughBehavior 屬性值，以選擇此選項。

    • 當整合請求中未定義任何映射範本時，如果您想要讓方法請求內文透過整合請求傳遞到後端而不進行轉換，請選擇 When there are no templates defined (recommended) (未定義範本時 (建議))。如果選取此選項時已定義範本，未映射內容類型的方法請求會遭到拒絕，並顯示 HTTP 415 Unsupported Media Type (不支援的媒體類型) 回應。

      注意

      呼叫 API Gateway API 時，您可以透過在整合資源上將 WHEN_NO_TEMPLATE 設定為 passthroughBehavior 屬性值，以選擇此選項。

    • 當方法請求內容類型不符合與整合請求中定義之映射範本相關聯的任何內容類型時，或是當整合請求中未定義任何映射範本時，如果您不想要讓方法請求傳遞，請選擇 Never (永不)。未映射內容類型的方法請求會遭到拒絕，並顯示 HTTP 415 Unsupported Media Type (不支援的媒體類型) 回應。

      注意

      呼叫 API Gateway API 時，您可以透過在整合資源上將 NEVER 設定為 passthroughBehavior 屬性值，以選擇此選項。

    如需整合傳遞行為的詳細資訊，請參閱「整合傳遞行為」。

  4. 對於 HTTP Proxy 或 AWS 服務 Proxy，若要將路徑參數、查詢字串參數或標頭參數與 HTTP Proxy 或服 AWS 務 Proxy 方法要求中的對應路徑參數、查詢字串參數或標頭參數產生關聯，請執行下列動作：

    1. 分別選擇 URL 路徑參數、URL 查詢字串參數或 HTTP 請求標頭，然後分別選擇 新增路徑、新增查詢字串或新增標頭。

    2. 在「名稱」中，輸入 HTTP 代理主機或服務代理伺 AWS 服器中的 path 參數、查詢字串參數或標頭參數的名稱。

    3. 針對映射自，輸入路徑參數、查詢字串參數或標頭參數的映射值。請使用下列其中一個格式：

      • method.request.path.parameter-name，代表方法請求頁面中所定義之名為 parameter-name 的路徑參數。

      • method.request.querystring.parameter-name，代表方法請求頁面中所定義之名為 parameter-name 的查詢字串參數。

      • method.request.multivaluequerystring.parameter-name，代表方法請求頁面中所定義之名為 parameter-name 的多值查詢字串參數。

      • method.request.header.parameter-name，代表方法請求頁面中所定義之名為 parameter-name 的標頭參數。

        或者，您可以將字串常值 (以一對單引號括住) 設定為整合標頭。

      • method.request.multivalueheader.parameter-name，代表方法請求頁面中所定義之名為 parameter-name 的多值標頭參數。

    4. 若要新增其他參數，請選擇新增按鈕。

  5. 若要新增對應範本，請選擇對應範本。

  6. 若要定義傳入請求的對應範本，請選擇新增對應範本。針對內容類型，輸入內容類型 (例如 application/json)。然後，輸入對映樣板。如需詳細資訊，請參閱 了解對應範本。

  7. 選擇 Save (儲存)。

  8. 您可以將後端整合回應映射到傳回給呼叫應用程式的 API 方法回應。這包括將從後端可用回應標頭中選取的回應標頭傳回給用戶端，並將後端回應承載的資料格式轉換成 API 指定的格式。您可以設定方法回應與整合回應，來指定這類對應。

    若要讓方法根據 Lambda 函數、HTTP 代理或 AWS 服務代理所傳回的 HTTP 狀態碼接收自訂回應資料格式，請執行下列動作：

    1. 選擇整合回應。選擇預設 - 回應上的編輯，以指定從方法設定 200 HTTP 回應碼，或選擇建立回應，以指定從方法設定任何其他 HTTP 回應狀態碼。

    2. 對於 Lambda 錯誤正則表達式（用於 Lambda 函數）或 HTTP 狀態正則表達式（適用於 HTTP 代理或 AWS 服務代理），請輸入一般表示式以指定哪些 Lambda 函數錯誤字串（針對 Lambda 函數）或 HTTP 回應狀態碼（適用於 HTTP 代理或 AWS 服務代理）對應至此輸出對應。例如，若要將所有 2xx HTTP 回應狀態碼從 HTTP 代理對應到此輸出對應，請針對 HTTP status regex (HTTP 狀態 regex) 輸入「2\d{2}」。若要從 Lambda 函數傳回包含「無效請求」的錯誤訊息給 400 Bad Request 回應，請輸入「.*Invalid request.*」作為 Lambda 錯誤 regex 表達式。另一方面，若要對來自 Lambda 的所有未映射錯誤訊息傳回 400 Bad Request，請在 Lambda 錯誤 regex 中輸入「(\n|.)+」。最後一個規則表達式可作為 API 的預設錯誤回應使用。

      注意

      API Gateway 使用 Java 模式 regex 進行回應映射。如需詳細資訊，請參閱 Oracle 文件中的模式一節。

      錯誤模式會與 Lambda 回應中 errorMessage 屬性的整個字串進行比對，該屬性在 Node.js 中是由 callback(errorMessage) 填入，在 Java 中是由 throw new MyException(errorMessage) 填入。此外，逸出字元在套用規則表達式之前為未逸出。

      如果您使用「.+」做為選取模式來篩選回應，請注意它可能不會比對含有新行 (「\n」) 字元的回應。

    3. 如果啟用，請針對方法回應狀態，選取您在方法回應頁面上定義的 HTTP 回應狀態碼。

    4. 針對您在方法回應頁面中為 HTTP 回應狀態碼定義之每個標頭的標頭對應，指定對應值。對於 Mapping value (對應值)，請使用以下其中一個格式：

      • integration.response.multivalueheaders.header-name，其中 header-name 是後端多值回應標頭的名稱。

        例如，若要傳回後端回應的 Date 標頭做為 API 方法回應的 Timestamp 標頭，Response header (回應標頭) 欄會包含 Timestamp (時間戳記) 項目，且相關聯的 Mapping value (對應值) 應設為 integration.response.multivalueheaders.Date。

      • integration.response.header.header-name，其中 header-name 是後端單一值回應標頭的名稱。

        例如，若要傳回後端回應的 Date 標頭做為 API 方法回應的 Timestamp 標頭，Response header (回應標頭) 欄會包含 Timestamp (時間戳記) 項目，且相關聯的 Mapping value (對應值) 應設為 integration.response.header.Date。

    5. 選擇對應範本，然後選擇新增對應範本。在 [內容類型] 方塊中，輸入將從 Lambda 函數、HTTP 代理或 AWS 服務代理傳送至方法之資料的內容類型。然後，輸入對映樣板。如需詳細資訊，請參閱 了解對應範本。

    6. 選擇 Save (儲存)。