以 API Proxy 的形式公開 SOAP 服務

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本主題說明如何為 SOAP 型網路服務建立 API Proxy。您可以在 Edge 中建立兩種 SOAP Proxy。一個會產生後端 SOAP 服務的 RESTful 介面，另一個則會對後端執行 SOAP 訊息的「直通」。本主題將說明這兩種技術。

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

建立 RESTful API Proxy，以存取 SOAP 服務

本節說明如何使用「Build a Proxy」(建立 Proxy) 精靈中的「REST to SOAP to REST」(REST 到 SOAP 到 REST) 選項，建立 RESTful SOAP API Proxy。

總覽

「REST 到 SOAP 到 REST」選項會處理 WSDL，產生 RESTful API 代理。Edge 會根據 WSDL 判斷服務支援的作業、輸入參數等。Edge 會「猜測」每個作業要使用的 HTTP 方法。通常 Edge 會將作業轉換為 GET 要求，這類要求可快取，因此具有優勢。Edge 也會設定後端目標端點，這項端點可能會因 SOAP 作業而異。

對於這類 Proxy，Edge 會自動產生 OpenAPI 規格，您可以使用這項規格建立 API 說明文件。

基本步驟

Edge

如要使用 Edge UI 建立 RESTful API Proxy，將要求轉送至 SOAP 型服務，請按照下列步驟操作：

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

    選取 WSDL 的來源。

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

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

    NOTE：API 代理伺服器基本路徑預設為 Name 欄位指定的值，並轉換為全小寫。

    基本路徑後方是任何其他資源網址。以下是用戶端用來呼叫 API Proxy 的完整網址結構：

    https://[host]/base_path/conditional_flow_path

    NOTE：基本路徑不得重複，您無法部署兩個基本路徑相同的 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. 在精靈的「Common policies」(一般政策) 頁面中，設定以下項目：
    • 「安全性：授權」一節中的安全授權規定。請參閱「新增安全性」。
    • 「安全性：瀏覽器」下方支援跨源資源共享 (CORS)。請參閱「新增 CORS 支援」。
    • 在「配額」Quota下方設定配額，防止後端服務因流量過高而中斷。請參閱「配額」。(如果選取「直通授權」，則無法使用這項功能)。
  10. 在「WSDL operations」(WSDL 作業) 頁面上，選取「REST to SOAP to REST」(REST 到 SOAP 再到 REST) API 代理類型。

    系統會顯示表格，列出 Edge 在 WSDL 檔案中「探索」到的作業。您可以選取並設定要併入 API Proxy 的作業。下圖顯示該資料表。

  11. 從下拉式選單選取「Port Type」(通訊埠類型)，指定要使用的作業集。在 WSDL 中，通訊埠類型元素會定義您可在 Web 服務上呼叫的作業。
  12. 視需要變更作業的 REST API 路徑。路徑會用做 API Proxy 網址中的資源名稱。
  13. 您可以視需要變更與作業相關聯的「動詞」(HTTP 方法)。
  14. 點選 [下一步]。
  15. 在精靈的「虛擬主機」頁面中，選取 API Proxy 部署時要繫結的虛擬主機。詳情請參閱「關於虛擬主機」。
  16. 點選 [下一步]。
  17. 選取部署環境，然後按一下「建立並部署」
    系統會建立新的 API Proxy， 並部署至所選環境。
  18. 按一下「Edit proxy」，即可顯示 API Proxy 的詳細資料頁面。

傳統 Edge (Private Cloud)

如要使用 Classic Edge UI 建立 RESTful API Proxy，將要求轉送至 SOAP 型服務，請按照下列步驟操作：

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

    選取 WSDL 的來源。

    • 網址：輸入要使用的 WSDL 網址。
    • 「檔案」：選擇檔案系統中的 WSDL 檔案。如有其他相依檔案，可以全部選取。
    • 範例網址 - 從公開網路服務的 WSDL 清單中選取。這些範例有助於試用 Edge 的 SOAP/API Proxy 功能。
    Proxy 名稱

    這是您要建立的 Proxy 名稱。
    Proxy Base Path

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

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

    基本路徑後方是任何其他資源網址。以下是用戶端用來呼叫 API 代理的完整網址結構：

    https://[host]/base_path/conditional_flow_path

    注意：基本路徑必須是唯一的，您無法部署兩個基本路徑相同的 API 代理項目。如果您編輯已部署的 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 頁面中，選取 API 代理類型「REST to SOAP to REST」。

    系統會顯示表格，列出 Edge 在 WSDL 檔案中「探索」到的作業。您可以選取並設定要併入 API Proxy 的作業。下圖顯示該資料表。

    在 WSDL 作業頁面中，API Proxy 類型會設為「REST to SOAP to REST」，且表格會顯示一列結果，其中包含「add」作業。

  9. 在「連接埠類型」欄中，選取要使用的作業集。在 WSDL 中，通訊埠類型元素會定義您可在 Web 服務上呼叫的作業。
  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) 對話方塊中的「Pass-Through Proxy」(直通 Proxy) 選項，建立直通 Proxy。

總覽

透過「直通 Proxy」選項，您可以建立 Proxy，將要求中的 SOAP 訊息「原封不動」地傳送至後端服務，輕鬆為 SOAP 型 Web 服務建立 Proxy。在幕後，Edge 會自動為您處理任何轉換和其他流程活動。舉例來說，如果要求是 JSON 格式，Edge 會先將其轉換為具有正確命名空間的有效 XML SOAP 訊息，然後再以 POST 方式傳送至服務。同樣地，當服務傳回以 XML 為基礎的 SOAP 回應時，Edge 會先將其翻譯回 JSON，再傳回給用戶端。此外，Edge 會設定後端目標端點，這可能會因 SOAP 作業而異。

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

基本步驟

Edge

如要使用 Edge UI 建立 SOAP 服務的直通 Proxy，請按照下列步驟操作：

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

    選取 WSDL 的來源。

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

    API Proxy 的名稱。
    基本路徑

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

    注意：如要瞭解 Apigee 的 API 版本管理建議，請參閱「Web API Design: The Missing Link」電子書中的「 版本管理」一節。

    基本路徑後方是任何其他資源網址。以下是用戶端用來呼叫 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 即可支援新團隊。請注意，系統不支援 /**/。

    注意：API Proxy 的基本路徑預設為「名稱」欄位指定的值 (轉換為全小寫)，除非您明確編輯「基本路徑」欄位中的內容。
    說明 (選用) API 說明。
  6. 點選「下一步」。
  7. 在精靈的「Common policies」(一般政策) 頁面中，設定以下項目：
  8. 在 WSDL 頁面中，選取「Pass-Through SOAP」(直通 SOAP) API Proxy 類型。

  9. 從下拉式選單選取「Port Type」(通訊埠類型)，指定要使用的作業集。在 WSDL 中，通訊埠類型元素會定義您可在 Web 服務上呼叫的作業。
  10. 點選 [下一步]。
  11. 在精靈的「虛擬主機」頁面中，選取 API Proxy 部署時要繫結的虛擬主機。詳情請參閱「關於虛擬主機」。
  12. 選取部署環境，然後按一下「建立並部署」
    系統會在所選環境中建立並部署新的 API Proxy。
  13. 按一下「Edit proxy」，即可顯示 API Proxy 的詳細資料頁面。

傳統 Edge (Private Cloud)

如要使用 Classic Edge UI 建立 SOAP 服務的直通代理，請按照下列步驟操作：

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

    選取 WSDL 的來源。

    • 網址：輸入要使用的 WSDL 網址。
    • 「檔案」：選擇檔案系統中的 WSDL 檔案。如有其他相依檔案，可以全部選取。
    • 範例網址 - 從公開網路服務的 WSDL 清單中選取。這些範例有助於試用 Edge 的 SOAP/API Proxy 功能。
    Proxy 名稱

    這是您要建立的 Proxy 名稱。
    Proxy Base Path Proxy Base Path 是 URI 片段，可唯一識別這個 API Proxy 公開的 API。API 服務會使用 Base Path URI 比對傳入的要求訊息，並將訊息轉送至適當的 API Proxy。(系統會根據您的機構名稱和 API Proxy 部署的環境，自動產生 API 的網域，並將 Base Path 附加至該網域)。建議在專案名稱中加入版本號碼，例如 /v1/delayedstockquote。這會決定消費者應用程式如何叫用您的 API。

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

  8. 點選 [下一步]。
  9. 在 WSDL 頁面中，選取「Pass-Through SOAP」 API Proxy 類型。

    注意：系統會顯示表格，列出每個 WSDL 作業及其對應的 SOAP 酬載。這是「傳遞至」後端 SOAP 服務的酬載。

    在 WSDL 頁面中，API Proxy 類型設為 Pass-Through SOAP，且作業清單 (例如 GetQuote) 會依連接埠類型整理。
  10. 在「連接埠類型」欄中，選取要使用的作業集。在 WSDL 中，通訊埠類型元素會定義您可在 Web 服務上呼叫的作業。
  11. 按一下精靈的其餘部分，即可新增安全性、選取虛擬主機和部署環境。
  12. 在「Build」(建構) 頁面中，按一下「Build and Deploy」(建構及部署)。Edge 會根據 WSDL 產生並部署新的 API Proxy。

關於最終 Proxy

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

舉例來說，下圖顯示直通 Proxy 的目標端點前置流程部分。在要求端，系統會使用 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。