建構簡單的 API Proxy

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。info

Apigee Edge 可讓您快速將後端服務公開為 API。方法是建立 API Proxy，為您要公開的後端服務提供外觀。您只需要提供後端服務的網路位址，以及 Edge 用來建立 API Proxy 並公開給開發人員的部分資訊。

API Proxy 會將後端服務實作與開發人員使用的 API 分離。這可以防止開發人員日後更動後端服務。當您更新後端服務時，開發人員可以繼續呼叫 API，不受這些變更影響。

觀看這部影片，概略瞭解建立 API Proxy 的程序。

使用 UI 建立 API Proxy

如要建立 API Proxy，最簡單的方法就是使用「建立 Proxy」精靈。

Edge

如要使用 Edge UI 存取「建立 Proxy」精靈，請按照下列步驟操作：

  1. 登入 apigee.com/edge。
  2. 在左側導覽列中，依序選取「Develop」>「API Proxies」。
  3. 按一下「+Proxy」。

「Create Proxy」精靈會顯示並引導您逐步產生基本功能，並將功能新增至 API Proxy。

「建立 Proxy 服務」精靈的第一頁會提示您選取反向 Proxy 服務、SOAP 服務、無目標或 Proxy 服務組合，以便自訂精靈流程。

傳統版 Edge (Private Cloud)

如要使用 Edge 傳統版 UI 存取「建立 Proxy」精靈，請按照下列步驟操作：

  1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
  2. 在頂端導覽列中，依序選取「APIs」>「API Proxies」。
  3. 按一下「+ API Proxy」。

「建立 Proxy」精靈會顯示並引導您完成產生 API Proxy 及新增基本功能的步驟。

「建立 Proxy 服務」精靈的第一頁會提示您選取反向 Proxy 服務、SOAP 服務、無目標或 Proxy 服務組合，以便自訂精靈流程。

在精靈的第一頁中，您可以從下列來源建立 API Proxy：

類型 說明
反向 Proxy (最常見)

將傳入要求轉送至現有 HTTP 後端服務的 API Proxy。可以是 JSON 或 XML API。請參閱下一節的「為 HTTP 服務建立反向 Proxy」。

按一下「Use OpenAPI Spec」，即可根據有效的 OpenAPI 規格產生 Proxy。如要進一步瞭解這個選項，請參閱本節稍後的「使用 OpenAPI 規格產生 Proxy」。
SOAP 服務 從 WSDL 檔案產生的 API Proxy。請參閱「以 API Proxy 的形式公開以 SOAP 為基礎的網路服務」。
沒有指定目標

沒有 API 後端的 API Proxy (「無目標」)。這與前述的為 HTTP 服務建立反向 Proxy類似，但在定義 API Proxy 詳細資料時，您不會指定現有的 API。

按一下「Use OpenAPI Spec」，即可根據有效的 OpenAPI 規格產生 Proxy。如要進一步瞭解這個選項，請參閱本節稍後的「使用 OpenAPI 規格產生 Proxy」。
託管目標

將導向已部署至代管目標環境的 Node.js 應用程式的 API Proxy。請參閱代管目標總覽。
上傳 Proxy 套件 現有的 API proxy 套件 (例如 GitHub 上提供的 API proxy 範例)。請參閱從 API Proxy 套件匯入 API Proxy。

以下各節將說明如何使用各個來源建立 API 代理程式。

建立 HTTP 服務的反向 Proxy

Edge 會根據以下兩項資訊產生反向 Proxy：

  • 後端服務的網址
  • 可明確識別 API 的 URI 路徑，API 代理程式會將此 API 公開給消費者應用程式

後端服務網址通常代表貴機構擁有的服務啟用應用程式。也可以指向公開的 API。API 或服務可以由您控管 (例如，內部人力資源應用程式或雲端中的 Rails 應用程式)，也可以是第三方 API 或服務 (例如 Twitter 或 Instagram)。

Edge

  1. 存取「建立 Proxy」精靈，如先前本節的使用 UI 建立 API Proxy 所述。
  2. 在「建立 Proxy」精靈中，按一下「Reverse proxy (most common)」。如要從現有的有效 OpenAPI 規格產生 Proxy，請按一下「Use OpenAPI Spec」。如要瞭解這個選項的詳細資訊，請參閱下方的「使用 OpenAPI 規格產生 Proxy」。
  3. 在精靈的「Details」(詳細資料) 頁面中輸入以下資訊。
    欄位 說明
    名稱 顯示的 API 名稱。指定英數字元、破折號 (-) 或底線 (_)。
    基本路徑

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

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

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

    https://[host]/base_path/conditional_flow_path

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

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

    在 API Proxy 基礎路徑中使用一或多個 /*/ 萬用字元，讓 API Proxy 能因應未來需求。舉例來說，/team/*/members 的基本路徑可讓用戶端呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members，而您不必建立新的 API Proxy 來支援新的團隊。請注意，我們不支援 /**/。
    說明 (選用) API 說明。
    目標 (現有 API) 這個 API Proxy 叫用的後端服務網址。
  4. 在精靈的「Common policies」頁面中，設定下列項目：
    • 請參閱「安全性：授權」下的安全性授權規定。請參閱本節稍後的「新增安全性」一節。
    • 在「安全性：瀏覽器」下方支援跨來源資源共享 (CORS)。請參閱本節稍後的「新增 CORS 支援」一節。
    • 配額：可保護後端服務免受高流量影響。請參閱「配額」一文。(如果選取快速授權授權，則無法使用這個選項)。
    • 在「營利」下，為已啟用營利功能的機構強制執行營利限制。請參閱「對 API Proxy 強制執行營利限制」。
  5. 在精靈的「虛擬主機」頁面中，選取 API 代理程式在部署時要繫結的虛擬主機。詳情請參閱「關於虛擬主機」。
  6. 在「Summary」頁面中，選取所需的部署環境，然後按一下「Create and deploy」。

    系統會建立新的 API Proxy，並在所選環境中部署。

  7. 按一下「編輯 Proxy」，即可顯示 API Proxy 的詳細資料頁面。

Classic Edge (Private Cloud)

  1. 存取「建立 Proxy」精靈，如先前本節的使用 UI 建立 API Proxy 所述。
  2. 在「Build a Proxy」精靈中，選取「Reverse proxy (most common)」。如要根據現有的有效 OpenAPI 規格產生 Proxy，請按一下「Use OpenAPI」。如需此選項的詳細資訊，請參閱下方的「使用 OpenAPI 規格產生 Proxy」。
  3. 點選「下一步」。
  4. 在精靈的「Details」頁面中輸入下列資訊。
    欄位 說明
    Proxy 名稱 API 的顯示名稱。
    Proxy 基本路徑

    Proxy Base Path 是 API proxy 的 http(s)://[host] 位址後方的 URI 片段。Edge 會使用 Base Path URI 比對並將傳入的請求訊息轉送至適當的 API Proxy。

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

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

    https://[host]/base_path/conditional_flow_path

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

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

    您可以在 API 代理程式基本路徑中使用一或多個 /*/ 萬用字元，讓代理程式不受時間限制。舉例來說，/team/*/members 的基本路徑可讓用戶端呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members，而您不必建立新的 API Proxy 來支援新的團隊。請注意，系統不支援 /**/。

    注意：除非您明確編輯「Proxy 基本路徑」欄位中的內容，否則「Proxy 基本路徑」預設為「Proxy 名稱」的指定值，且該值會轉換為所有小寫。
    現有 API API 平台代表透過 API Proxy 網址呼叫您的 API 的應用程式所叫用的網址。
    說明 API 的說明。
  5. 在精靈的「安全性」頁面中，設定下列項目：
    • 安全性驗證規定。請參閱本節稍後的「新增安全性」一節。
    • 支援跨來源資源共享 (CORS)。請參閱本節稍後的「新增 CORS 支援」一節。
  6. 在精靈的「虛擬主機」頁面上，選取 API Proxy 在部署時要繫結的虛擬主機。詳情請參閱「關於虛擬主機」。
  7. 選取部署環境，然後按一下「Build and Deploy」
    系統會傳送確認訊息，證明新 API Proxy 已成功建立並部署至所選環境。
  8. 按一下「在編輯器中查看 <proxy name> proxy」，即可顯示 API proxy 的詳細資料頁面。

從 API Proxy 套件匯入 API Proxy

您通常會將 API 代理程式定義為 XML 檔案集合，以及任何其他支援檔案。只要將 API 代理程式定義為 Edge 外部的一系列檔案，您就可以在來源管控系統中維護這些檔案，然後將這些檔案匯入 Edge 進行測試和部署。

歡迎觀看這部影片，瞭解如何透過 API Proxy 套件建立及匯入 API Proxy。

Edge

如要從 API Proxy 套件匯入 API Proxy，請按照下列步驟操作：

  1. 存取「建立 Proxy」精靈，如先前本節的使用 UI 建立 API Proxy 所述。
  2. 按一下「上傳 Proxy 套件」。
  3. 在 Proxy 精靈的「上傳 Proxy 組合」頁面中，輸入下列資訊。

    欄位 說明
    ZIP 檔案組合 包含 API Proxy 設定的 ZIP 檔案。拖曳或點選檔案。
    名稱 顯示的 API 名稱。預設為不含副檔名的 ZIP 檔案名稱。
  4. 點選「下一步」。
  5. 在「Summary」頁面上，選取所需的部署環境(如有)，然後按一下「Create and deploy」
    系統會顯示確認訊息，證明您已成功建立新的 API Proxy。
  6. 按一下「編輯 Proxy」，即可顯示 API Proxy 的詳細資料頁面。

Classic Edge (Private Cloud)

  1. 如使用 UI 建立 API proxy一節所述，請存取「建立 Proxy」精靈。
  2. 在「Build a Proxy」精靈中，選取「Proxy bundle」。
  3. 點選「下一步」。
  4. 在 Proxy 精靈的「Details」頁面中輸入以下資訊。

    欄位 說明
    ZIP 檔案組合 按一下「選擇檔案」，然後前往含有 API 代理程式設定的 ZIP 檔案。
    Proxy 名稱 API 的顯示名稱。
  5. 查看建構資訊，然後按一下「Build」。
    如果成功，系統會顯示訊息，Edge 也會自動將匯入的 API 代理程式部署至機構中所選的環境。可叫用 API Proxy 公開的 API。
  6. 按一下編輯器中的「查看 <proxy name> Proxy」，顯示 API Proxy 的詳細資料頁面。
  7. 如要部署 Proxy，請按一下「Deployment」下拉式選單，選取要部署至的環境，然後回應提示。

以 API Proxy 的形式公開 SOAP 型網路服務

在「建立 Proxy」精靈中，按一下「SOAP 服務」，然後按照精靈的說明建立 SOAP 服務的直通或 REST 型 Proxy。詳情請參閱「以 API Proxy 的形式公開 SOAP 服務」。

增強安全性

在「建立 Proxy」精靈的通用原則 (Edge) 或安全性 (經典邊緣) 頁面中，選取您要新增的安全性授權類型。下表摘要列出可用的選項：

安全性授權 說明
API 金鑰 在您定義的 API Proxy 中加入簡易的 API 金鑰驗證機制。作為回應，API 平台會在 API 代理程式中新增 VerifyAPIKey 政策和 AssignMessage 政策。「VerifyAPIKey」政策會驗證要求應用程式提供的 API 金鑰。AssignMessage 政策會從轉送至後端伺服器的要求中，移除在 API 呼叫中做為查詢參數提供的 API 金鑰。
OAuth 2.0 為 API Proxy 新增 OAuth 2.0 驗證機制。Apigee Edge 會自動在 API Proxy 中新增兩個政策：一個用於驗證存取權杖，另一個則會在將訊息轉送至後端服務前，先從訊息中移除存取權杖。如要瞭解如何取得存取權杖，請參閱 OAuth。
直接放行 (未經授權) 無須授權。要求會傳送至後端，但不會在 Apigee Edge 上進行任何安全性檢查。

新增 CORS 支援

CORS (跨源資源共享) 是一種標準機制，可讓網路瀏覽器向其他網域提出直接要求。CORS 標準會定義一組 HTTP 標頭，網路瀏覽器和伺服器可用來實作跨網域通訊。

您可以前往「建立 Proxy」精靈的「常見政策」 (Edge) 或「安全性」 (舊版 Edge) 頁面，選取「新增 CORS 標頭」，為 API 新增 CORS 支援。

如要進一步瞭解 CORS 支援，包括如何在 Proxy 中新增 CORS 預檢支援，請參閱「為 API Proxy 新增 CORS 支援」。

使用 OpenAPI 規格產生 Proxy

本節將說明「使用 OpenAPI」選項，可從 OpenAPI 規格產生以下類型的 API Proxy：反向、Node.js 或無目標。

什麼是 OpenAPI 規範？

Open API Initiative 標誌「Open API Initiative (OAI) 專注於根據 Swagger 規範，建立、改良及推廣供應商中立的 API 說明格式。」如要進一步瞭解開放 API 計畫，請前往 https://openapis.org。

OpenAPI 規格使用標準格式說明 RESTful API。OpenAPI 規格是以 JSON 或 YAML 格式編寫，可供機器讀取，但也易於使用者閱讀及理解。規格說明會描述 API 的基礎路徑、路徑和動詞、標頭、查詢參數、作業、內容類型、回應說明等元素。此外，OpenAPI 規格通常用於產生 API 說明文件。

以下是 OpenAPI 規範的片段，說明 Apigee 的模擬目標服務 http://mocktarget.apigee.net。詳情請參閱 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi。

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

您可以透過「建立 Proxy」精靈，匯入 OpenAPI 規格，並用於產生 API Proxy。產生 Proxy 後，您可以使用 Edge UI 進一步開發 Proxy，例如新增政策、實作自訂程式碼等等，就像任何 Edge Proxy 一樣。

使用 OpenAPI 規格建立 API Proxy

使用 OpenAPI 規格建立 API Proxy。只要按幾下滑鼠，您就能取得 API 代理程式，其中包含自動產生的路徑、參數、條件流程和目標端點。接著，您可以新增 OAuth 安全性、頻率限制和快取等功能。

在「建立 Proxy」精靈中，按一下「Use OpenAPI Spec」，然後按照精靈指示，使用 OpenAPI 規格建立反向或無目標 Proxy。詳情請參閱「使用 OpenAPI 規格建立 API Proxy」。

請觀看這部影片，瞭解如何依據 OpenAPI 規格建立 API Proxy。

使用 OpenAPI 規格更新 API Proxy 中的流程

根據 OpenAPI 規格建立 API Proxy 後，如果您修改規格以新增其他資源路徑，可以使用該規格將相關的條件式流程新增至 API Proxy。

如要使用 OpenAPI 規格更新 API Proxy 中的流程，請按照下列步驟操作：

  1. 將新的資源路徑新增至 OpenAPI 規格。請參閱「編輯現有的 OpenAPI 規範」。
  2. 在 UI 中開啟 API Proxy，然後按一下「Develop」分頁。
  3. 在導覽器中，按一下要更新的 Proxy 端點旁的「+」。
    系統會隨即開啟「New Conditional Flow」對話方塊。
  4. 如果尚未選取「From OpenAPI」，請按一下這個選項。
    如果 OpenAPI 規格中的資源在 API 代理程式中沒有對應的條件式流程，對話方塊會列出這些資源，如下圖所示。 在目前的 API 代理程式中，未以流量形式呈現的資源。這個範例包含 /loveapis、/ip、/json 和 /xml。
  5. 選取要新增條件式流程的每個資源。
  6. 按一下 [新增]。

系統會將條件式流程新增至 API Proxy。

建立 API Proxy 的新修訂版本

按照下方說明建立新的 API Proxy 修訂版本。

Edge

如要使用 Edge UI 建立 API Proxy 的新修訂版本，請按照下列步驟操作：

  1. 登入 apigee.com/edge。
  2. 在左側導覽列中，依序選取「Develop」>「API Proxies」。
  3. 在清單中按一下要複製的 API 代理程式。
  4. 依序選取「Project」>「Save as New Revision」。

Classic Edge (Private Cloud)

如要使用 Classic Edge UI 建立 API Proxy 的新修訂版本，請按照下列步驟操作：

  1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
  2. 依序選取頂端導覽列中的「API」>「API 代理程式」。
  3. 在清單中按一下要複製的 API 代理程式。
  4. 依序選取「Project」>「Save as New Revision」。

複製 API Proxy

將現有的 API Proxy 複製到新的 API Proxy，如下所述。

Edge

如何使用 Edge UI 複製 API Proxy：

  1. 登入 apigee.com/edge。
  2. 在左側導覽列中，依序選取「Develop」>「API Proxies」。
  3. 在要複製的清單中按一下 API Proxy。
  4. 依序選取「Project」>「Save as New API Proxy」。
  5. 在「Save as New Proxy」對話方塊中，輸入新的 API Proxy 名稱。
  6. 按一下 [新增]。

Classic Edge (Private Cloud)

如要使用 Edge 傳統版 UI 複製 API Proxy，請按照下列步驟操作：

  1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
  2. 依序選取頂端導覽列中的「API」>「API 代理程式」。
  3. 在清單中按一下要複製的 API 代理程式。
  4. 依序選取「Project」>「Save as New API Proxy」。
  5. 在「Save as New Proxy」對話方塊中，輸入新的 API Proxy 名稱。
  6. 按一下 [新增]。

備份 API Proxy

您可以將現有的 API 代理程備份為 API 代理程套件的 XML 檔案組合。匯出至套件後，您可以將 API 代理程式匯入新的代理程式，如本節前述的「從 API 代理程式套件匯入 API 代理程式」一節所述。詳情請參閱「下載 API Proxy」。

使用 API 建立 API Proxy

如要使用 API 建立 API Proxy，請參閱 API Proxy API。