以 API Proxy 的形式公開 SOAP 服務

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

本主題說明如何為 SOAP 式網路服務建立 API Proxy。您可以在 Edge 中建立兩種 SOAP Proxy。其中一個會對後端 SOAP 服務產生 符合 REST 樣式的介面，另一個則會將 SOAP 訊息的「傳遞」至後端。本主題將說明這兩種技術。

這部影片提供端對端示範，說明如何使用 API Proxy 精靈，將 SOAP 服務轉換成 REST 服務。不過，如要進一步控管 SOAP 到 REST 的轉換，您可以使用政策建立 Proxy。詳情請參閱 教學課程：在 Apigee Edge 中手動建構 SOAP 至 REST API Proxy。

為 SOAP 服務建立符合 REST 樣式的 API Proxy

本節說明如何在「建構 Proxy」精靈中，使用「從 SOAP 到 REST」選項建立符合 REST 樣式的 SOAP API Proxy。

總覽

「REST 到 REST」選項會處理 WSDL 以產生符合 REST 樣式的 API Proxy。邊緣會根據 WSDL 決定服務支援的作業、輸入參數等。邊緣「猜測」每項作業要使用的 HTTP 方法。一般而言，Edge 會將作業轉譯為 GET 要求，這類要求具有可快取的優勢。Edge 也會設定後端目標端點，這個端點會因 SOAP 作業而異。

Edge 會自動為這類 Proxy 產生 OpenAPI 規範，讓您用來建立 API 說明文件。

基本步驟

Edge

如何使用 Edge UI 建立符合 REST 樣式的 API Proxy 至 SOAP 式服務：

  1. 登入 apigee.com/edge。
  2. 在左側導覽列中，依序選取「Develop」(開發) >「API Proxy」。
  3. 按一下「+Proxy」。
  4. 按一下「SOAP 服務」。
  5. 在 Proxy 詳細資料頁面中，提供 WSDL 檔案。
    欄位 說明
    提供 WSDL 檔案

    選取 WSDL 來源。

    • 從網址 (URL)：輸入或貼上 WSDL 的網址。
    • 從我的電腦：從本機目錄上傳 WSDL 檔案。如有依附元件，您也可以上傳多個檔案。
  6. 按一下「驗證」來驗證 WSDL。
  7. 輸入下列 Proxy 詳細資料：
    欄位 說明
    名稱 您的 API 顯示名稱。請指定英數字元、破折號 (-) 或底線 (_)。
    基本路徑

    URI 片段顯示在 API Proxy 的 http(s)://[host] 位址後方。邊緣使用基本路徑 URI 來比對傳入要求訊息，並將訊息轉送至適當的 API Proxy。

    注意：API Proxy 基本路徑預設為 Name 欄位指定的值，並轉換成所有小寫格式。

    以下是所有額外的資源網址。以下是用戶端用來呼叫 API Proxy 的完整網址結構：

    https://[host]/base_path/conditional_flow_path

    注意：基本路徑不得重複；您不能使用相同的基本路徑部署兩個 API Proxy。如果您編輯已部署的 API Proxy，並將基本路徑設為與其他 API Proxy 的基本路徑相同的值，Edge 會在儲存 API Proxy 時自動取消部署。重新部署 API Proxy 前，必須先編輯基本路徑，使其不重複。

    在基本路徑中使用萬用字元

    在 API Proxy 基本路徑中使用一或多個 /*/ 萬用字元，確保 API Proxy 能因應未來需求。舉例來說，/team/*/members 的基本路徑可讓用戶端呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members，而不需要建立新的 API Proxy 來支援新團隊。請注意，系統不支援 /**/。
    說明 (選填) API 的說明。
  8. 點選「下一步」。
  9. 在精靈的「常用政策」頁面中設定下列內容：
    • 「安全性：授權」之下的安全性授權要求。請參閱增加安全性。
    • 支援「安全性：瀏覽器」中的跨源資源共享 (CORS)。請參閱「新增 CORS 支援」。
    • 設定配額可避免後端服務受到「配額」高流量的影響。請參閱配額一文。(如果已選取直通授權，則不適用)。
  10. 在「WSDL 作業」頁面上，選取「從 SOAP 到 REST」的 API Proxy 類型。

    畫面上隨即會顯示一個資料表，當中列出 WSDL 檔案中 Edge「探索」的作業。您可以選取並設定要整合至 API Proxy 的作業。表格如下圖所示。

  11. 在下拉式選單中選取「通訊埠類型」，指定要使用的作業組合。在 WSDL 中，通訊埠類型元素會定義您可以在網路服務中呼叫的作業。
  12. 視需要變更作業的 REST API 路徑。這個路徑會用來當做 API Proxy 網址中的資源名稱。
  13. 視需要變更與作業相關聯的 Verb (HTTP 方法)。
  14. 按一下「Next」。
  15. 在精靈的「虛擬主機」頁面中，選取 API Proxy 部署後將繫結至的虛擬主機。詳情請參閱「關於虛擬主機」。
  16. 按一下「Next」。
  17. 選取部署環境，然後按一下「建立及部署」
    建立新的 API Proxy 並部署至所選環境。
  18. 按一下「編輯 Proxy」以顯示 API Proxy 的詳細資料頁面。

傳統邊緣 (Private Cloud)

如何使用傳統版 Edge UI 建立符合 REST 樣式的 API Proxy 至 SOAP 式服務：

  1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
  2. 在頂端導覽列中，依序選取「API」>「API Proxy」。
  3. 按一下「+ API Proxy」。
  4. 在「建立 Proxy」精靈中，選取 SOAP 服務。
  5. 按一下「Next」。
  6. 在「詳細資料」頁面中選取這些選項。選取 WSDL 後，您必須按一下「驗證」。
    這個欄位中 採取行動
    WSDL

    選取 WSDL 來源。

    • 網址 - 輸入您要使用的 WSDL 網址。
    • 檔案：選擇檔案系統中的 WSDL 檔案。如有其他相依檔案，您可以選取所有檔案。
    • 範例網址：從 WSDL 清單中選取用於公開的網路服務。在使用 Edge 的 SOAP/API Proxy 功能時，這些資訊可派上用場。
    Proxy 名稱

    此為要建立的 Proxy 名稱。
    Proxy 基本路徑

    URI 片段顯示在 API Proxy 的 http(s)://[host] 位址後方。邊緣使用基本路徑 URI 來比對傳入要求訊息，並將訊息轉送至適當的 API Proxy。

    注意：API Proxy 基本路徑預設為 Name 欄位指定的值，並轉換成全部小寫。

    以下是所有額外的資源網址。以下是用戶端用來呼叫 API Proxy 的完整網址結構：

    https://[host]/base_path/conditional_flow_path

    注意：基本路徑不得重複；您無法部署具有相同基本路徑的兩個 API Proxy。如果您編輯已部署的 API Proxy，並將基本路徑設為與其他 API Proxy 的基本路徑相同的值，Edge 會在儲存 API Proxy 時自動取消部署。重新部署 API Proxy 前，必須先編輯基本路徑，使其不重複。

    在基本路徑中使用萬用字元

    在 API Proxy 基本路徑中使用一或多個 /*/ 萬用字元，確保 API Proxy 能因應未來需求。舉例來說，/team/*/members 的基本路徑可讓用戶端呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members，而不需要建立新的 API Proxy 來支援新團隊。請注意，系統不支援 /**/。
    說明 Proxy 的簡短說明。
  7. 點選「下一步」。
  8. 在 WSDL 頁面中，選取「REST 至 SOAP 至 REST」API Proxy 類型。

    畫面上隨即會顯示一個資料表，當中列出 WSDL 檔案中 Edge「探索」的作業。您可以選取並設定要整合至 API Proxy 的作業。表格如下圖所示。

    在 WSDL 作業頁面中，API Proxy 類型設為 REST 為 SOAP 至 REST，且表格會顯示包含新增作業的一列結果。

  9. 在「通訊埠類型」欄中，選取您想要使用的作業組合。在 WSDL 中，通訊埠類型元素會定義您可以在網路服務中呼叫的作業。
  10. 視需要變更與作業相關聯的 HTTP 方法。

    注意：Edge 會「最接近」的判斷結果，以決定每項作業要使用的 HTTP 方法。由於 GET 要求可以快取，因此通常建議使用 GET。
  11. 視需要變更作業的 REST API 路徑。這個路徑會用來當做 API Proxy 網址中的資源名稱。
  12. 點閱精靈的其餘部分，以新增安全性、選取虛擬主機和部署環境。
  13. 在「Build」頁面中，按一下「Build and Deploy」。Edge 會根據 WSDL 產生及部署新的 API Proxy。
  14. 前往新 API Proxy 的摘要頁面。請注意，系統會根據在 WSDL 檔案中找到的作業來建構一組資源。

    在 Proxy 的「總覽」頁面上，「資源」清單會提供新版 API、其作業及參數的詳細說明。您可以將此表示法視為 API 的參考說明文件。Edge 會自動為您產生這個 API 模型的檢視畫面。只要展開資源即可查看其說明和路徑資訊。

關於最終 Proxy

當 Edge 根據 WSDL 產生 API Proxy 時，產生的 Proxy 實際上是複雜的流程，其中包含轉換資料、擷取和設定變數、操控訊息等。根據 WSDL 產生 Proxy 後，請在 API 管理 UI 的「開發」檢視畫面中查看產生的流程。您可以在這裡查看已新增的政策。

舉例來說，在要求端使用 AssignMessage 政策來設定目標網址。在回應端執行政策，將回應從 XML 轉換為 JSON，將回應的 SOAP 主體部分擷取為變數，並設定回應訊息。系統會在您建立 Proxy 時自動新增這些政策 (和其他政策)。

OpenAPI 規格：如要查看這個 Proxy 自動產生的 OpenAPI 規格，請前往 http(s)://[proxy_domain]/[proxy_base_path]/openapi.json。不過，轉換不一定準確，因為並非 XML 結構定義的所有規則都能以 OpenAPI 規格表示。

建立直通式 Proxy 至 SOAP 式服務

本節說明如何在「Create New Proxy」對話方塊中使用「直通式 Proxy」選項建立直通式 Proxy。

總覽

「傳遞 Proxy」選項可讓您建立 Proxy，將要求中的 SOAP 訊息「未經修飾」傳送至後端服務，讓您輕鬆建立 SOAP 網路服務的 Proxy。Edge 會在背景自動處理所有轉換作業和其他資料流活動。舉例來說，如果要求剛好是 JSON 格式，Edge 會採取步驟來將要求轉換為包含正確命名空間的有效 XML SOAP 訊息，然後再發布至服務。同樣地，當服務傳回以 XML 為基礎的 SOAP 回應時，Edge 會先將其轉換回 JSON，然後再將其傳回用戶端。此外，Edge 會設定後端目標端點，這個端點可能會因 SOAP 作業而異。

對於這類 Proxy，Edge 會託管 WSDL，並在 Proxy 中建立流程來讓您存取。指向這個 Edge 託管 WSDL 的位址 (http(s)://[proxy_domain]/[proxy_base_path]?wsdl) 會成為透過 Proxy 呼叫 SOAP 服務的用戶端新的服務端點網址。

基本步驟

Edge

如要使用 Edge UI 建立直通式 Proxy 至 SOAP 式服務，請按照下列指示操作：

  1. 登入 apigee.com/edge。
  2. 在左側導覽列中，依序選取「Develop」(開發) >「API Proxy」。
  3. 按一下「+Proxy」。
  4. 按一下「SOAP 服務」。
  5. 在 Proxy 詳細資料頁面上，提供 WSDL 詳細資料。
    欄位 說明
    WSDL

    選取 WSDL 來源。

    • 從網址 (URL)：輸入或貼上 WSDL 的網址。
    • 從我的電腦：從本機目錄上傳 WSDL 檔案。如有依附元件，您也可以上傳多個檔案。
    名稱

    API Proxy 的名稱。
    基本路徑

    API Proxy 的 http(s)://[host] 位址後方的 URI 片段。邊緣使用基本路徑 URI 來比對傳入要求訊息，並將訊息轉送至適當的 API Proxy。

    附註：如需 Apigee 的 API 版本管理建議，請參閱《Web API Design: The Missing Link》(網路 API 設計：遺漏的連結) 中的「 版本管理」一節。

    基本路徑之後會列出任何額外的資源網址。以下是用戶端用來呼叫 API Proxy 的完整網址結構：

    https://[host]/base_path/conditional_flow_path

    注意：基本路徑不得重複。如果您之後編輯這個 Proxy，並將其基本路徑設為與其他 API Proxy 相同，系統會在您儲存這個 API Proxy 時自動取消部署。您必須先編輯基礎路徑才能重新部署。

    在基本路徑中使用萬用字元

    您可以在 API Proxy 基本路徑中使用一或多個 /*/ 萬用字元，確保 Proxy 能因應未來需求。舉例來說，/team/*/members 的基本路徑可讓用戶端呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members，而不需要建立新的 API Proxy 來支援新團隊。請注意，不支援 /**/。

    注意：除非您明確編輯「Base Path」欄位中的內容，否則 API Proxy 基本路徑預設為「Name」欄位指定的值會轉換為所有小寫。
    說明 (選填) API 的說明。
  6. 點選「下一步」。
  7. 在精靈的「常用政策」頁面中設定下列內容：
  8. 在 WSDL 頁面上，選取「Pass-Through SOAP」API Proxy 類型。

  9. 在下拉式選單中選取「通訊埠類型」，指定要使用的作業組合。在 WSDL 中，通訊埠類型元素會定義您可以在網路服務中呼叫的作業。
  10. 按一下「Next」。
  11. 在精靈的「虛擬主機」頁面中，選取 API Proxy 部署後將繫結至的虛擬主機。詳情請參閱「關於虛擬主機」。
  12. 選取部署環境，然後按一下「建立及部署」
    新的 API Proxy 會在所選環境中建立及部署。
  13. 按一下「編輯 Proxy」以顯示 API Proxy 的詳細資料頁面。

傳統邊緣 (Private Cloud)

如要使用傳統版 Edge UI 建立直通式 Proxy，連至 SOAP 式服務，請按照下列指示操作：

  1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
  2. 在頂端導覽列中，依序選取「API」>「API Proxy」。
  3. 按一下「+ API Proxy」。
  4. 在「建立 Proxy」精靈中，選取 SOAP 服務。
  5. 按一下「Next」。
  6. 在「詳細資料」頁面中選取這些選項。選取 WSDL 後，您必須按一下「驗證」。
    這個欄位中 採取行動
    WSDL

    選取 WSDL 來源。

    • 網址：輸入您要使用的 WSDL 網址。
    • 檔案：選擇檔案系統中的 WSDL 檔案。如有其他相依檔案，您可以選取所有檔案。
    • 範例網址：從 WSDL 清單中選取用於公開的網路服務。在使用 Edge 的 SOAP/API Proxy 功能時，這些資訊可派上用場。
    Proxy 名稱

    此為要建立的 Proxy 名稱。
    Proxy 基本路徑 Proxy 基本路徑是一個 URI 片段，專門識別這個 API Proxy 所公開的 API。API 服務會使用基礎路徑 URI 來比對傳入要求訊息，並將訊息轉送至適當的 API Proxy。(基本路徑會附加在 API 的網域後方，系統是根據您的機構名稱和部署 API Proxy 的環境自動產生)。最佳做法是在專案名稱中加入版本號碼，例如 /v1/delayedstockquote。這會決定消費者應用程式叫用您的 API 的方式。

    注意：除非您明確編輯「Proxy 基本路徑」欄位中的內容，否則 Proxy 基礎路徑預設為 Proxy 名稱的指定值，會轉換為小寫。
    說明 Proxy 的簡短說明。

  8. 按一下「Next」。
  9. 在 WSDL 頁面中，選取「通過 SOAP」API Proxy 類型。

    注意：隨即顯示的表格會列出各項 WSDL 作業及其對應的 SOAP 酬載。這是會「傳遞」到後端 SOAP 服務的酬載。

    在 WSDL 頁面中，API Proxy 類型設為「通過 SOAP」，而「Getquote」等作業清單會按照通訊埠類型分類。
  10. 在「通訊埠類型」欄中，選取您想要使用的作業組合。在 WSDL 中，通訊埠類型元素會定義您可以在網路服務中呼叫的作業。
  11. 點閱精靈的其餘部分，以新增安全性、選取虛擬主機和部署環境。
  12. 在「Build」頁面中，按一下「Build and Deploy」。Edge 會根據 WSDL 產生及部署新的 API Proxy。

關於最終 Proxy

當 Edge 產生直通 Proxy 時，產生的 Proxy 實際上是一個複雜的流程，其中包含轉換資料、擷取和設定變數、操控訊息等。產生直通 Proxy 後，請在 API 管理 UI 的「開發」檢視畫面中查看產生的流程。您可以在這裡查看已新增的政策。

舉例來說，下圖顯示直通 Proxy 的「目標端點 Preflow」部分。在要求端使用 AssignMessage 政策來設定目標網址。在回應端執行政策，將回應從 XML 轉換為 JSON，將回應的 SOAP 主體部分擷取為變數，並設定回應訊息。系統會在您建立 Proxy 時自動新增這些政策 (和其他政策)。

在「開發」檢視畫面中，流程面板中的箭頭代表從要求到回應的流程，以及代表政策的圖示。

Edge 代管的 WSDL：如要查看這個 Proxy 類型產生的 Edge 託管 WSDL，請前往 http(s)://[proxy_domain]/[proxy_base_path]?wsdl。

進階 SOAP 到 REST Proxy 開發

前幾節說明如何使用 Edge 中的 API Proxy 精靈建立 SOAP 至 REST API Proxy。不過，如果您要更精細地控制 SOAP 到 REST 的轉換，則可略過精靈提供的自動化動作，並透過手動新增和設定政策來建構 Proxy，藉此取得您想要的行為。詳情請參閱 教學課程：在 Apigee Edge 中手動建構 SOAP 至 REST API Proxy。