建構簡單的 API Proxy

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

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 Proxy」
  3. 按一下「+Proxy」

「建立 Proxy」精靈會顯示並引導您逐步完成產生作業,並將最少的功能新增至 API Proxy。

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

傳統邊緣 (Private Cloud)

如何使用傳統版 Edge UI 存取「建立 Proxy」精靈:

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

「建立 Proxy」精靈會顯示並引導您逐步完成產生作業,並將最少的功能新增至 API Proxy。

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

精靈的第一頁可讓您從下列來源建立 API Proxy:

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

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

按一下「Use OpenAPI Spec」,透過有效的 OpenAPI 規範產生 Proxy。如要進一步瞭解這個選項,請參閱本節後續的使用 OpenAPI 規範產生 Proxy

SOAP 服務 從 WSDL 檔案產生的 API Proxy。請參閱「將 SOAP 網路服務以 API Proxy 的形式公開」一文。
沒有指定目標

沒有 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 Proxy。

為 HTTP 服務建立反向 Proxy

Edge 會根據兩項資訊產生反向 Proxy:

  • 後端服務的網址
  • 專門用來識別 API Proxy 將公開應用程式向消費者應用程式公開 API 的 URI 路徑

後端服務網址通常代表貴機構擁有的已啟用服務功能應用程式。也可能指向公開的 API。您可以控管 API 或服務 (例如內部 HR 應用程式或 Cloud 中的 Rails 應用程式),也可以是第三方 API 或服務 (例如 Twitter 或 Instagram)。

Edge

  1. 存取「建立 Proxy」精靈,如本節先前章節「使用 UI 建立 API Proxy」所述。
  2. 在「建立 Proxy」精靈中,按一下「反向 Proxy (最常用)」。如要從現有的有效的 OpenAPI 規範產生 Proxy,請按一下「使用 OpenAPI 規格」。如要進一步瞭解這個選項,請參閱下方的使用 OpenAPI 規範產生 Proxy
  3. 在精靈的「詳細資料」頁面中輸入以下資訊。
    欄位 說明
    名稱 您的 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/membershttps://[host]/team/green/members,而不需要建立新的 API Proxy 來支援新團隊。請注意,系統不支援 /**/

    說明 (選填) API 的說明。
    目標 (現有的 API) 這個 API Proxy 叫用的後端服務網址。
  4. 在精靈的「常用政策」頁面中設定下列內容:
    • 「安全性:授權」之下的安全性授權要求。請參閱本節後續的新增安全性一節。
    • 支援「安全性:瀏覽器」中的跨源資源共享 (CORS)。請參閱本節後段的新增 CORS 支援
    • 設定配額可避免後端服務受到「配額」高流量的影響。請參閱配額一文。(如果已選取直通授權,則不適用)。
    • 針對已啟用營利功能的機構採取的營利限制違規處置。請參閱「對 API Proxy 強制執行營利限制」。
  5. 在精靈的「虛擬主機」頁面中,選取 API Proxy 部署後將繫結至的虛擬主機。詳情請參閱「關於虛擬主機」。
  6. 在「摘要」頁面中,視需要選取部署環境,然後按一下「建立及部署」

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

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

傳統邊緣 (Private Cloud)

  1. 存取「建立 Proxy」精靈,如本節先前章節「使用 UI 建立 API Proxy」所述。
  2. 在「建構 Proxy 精靈」中,選取「反向 Proxy (最常用)」。如要利用現有的有效的 OpenAPI 規格產生 Proxy,請按一下「Use OpenAPI」。如要進一步瞭解這個選項,請參閱下方的使用 OpenAPI 規範產生 Proxy
  3. 按一下「Next」
  4. 在精靈的「詳細資料」頁面中,輸入以下資訊。
    欄位 說明
    Proxy 名稱 您的 API 顯示名稱。
    Proxy 基本路徑

    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/membershttps://[host]/team/green/members,而不需要建立新的 API Proxy 來支援新團隊。請注意,不支援 /**/。

    注意:除非您明確編輯「Proxy 基本路徑」欄位中的內容,否則 Proxy 基本路徑預設為 Proxy 名稱的指定值,會轉換為全部小寫。

    現有 API API 平台代表透過 API Proxy 網址呼叫 API 的應用程式叫用的網址。
    說明 API 的說明。
  5. 在精靈的「安全性」頁面中設定下列內容:
  6. 在精靈的「Virtual Hosts」頁面中,選取 API Proxy 部署後將繫結至的虛擬主機。詳情請參閱「關於虛擬主機」。
  7. 選取部署環境,然後按一下「Build and Deploy」
    系統會傳送確認訊息,確認您已成功在所選環境中建立及部署新的 API Proxy。
  8. 按一下「在編輯器中查看 <proxy name> Proxy」,顯示 API Proxy 的詳細資料頁面。

從 API Proxy 套裝組合匯入 API Proxy

您通常會將 API Proxy 定義為 XML 檔案的集合,或任何其他支援檔案。只要將 API Proxy 定義為 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. 按一下「Next」
  5. 如有需要,在「摘要」頁面中選取部署環境,然後按一下「建立及部署」
    系統會顯示確認訊息,確認已成功建立新的 API Proxy。
  6. 按一下「編輯 Proxy」以顯示 API Proxy 的詳細資料頁面。

傳統邊緣 (Private Cloud)

  1. 存取「建立 Proxy」精靈,如本節先前章節「使用 UI 建立 API Proxy」所述。
  2. 在「建構 Proxy」精靈中,選取「Proxy 套件」
  3. 按一下「Next」
  4. 在 Proxy 精靈的「詳細資料」頁面中輸入下列資訊。

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

以 API Proxy 的形式公開以 SOAP 為基礎的網路服務

在「建立 Proxy」精靈中按一下「SOAP 服務」,然後按照精靈的指示為 SOAP 服務建立直通或 REST 式 Proxy。詳情請參閱「將 SOAP 服務公開為 API Proxy」一文。

增加安全性

在「建立 Proxy」精靈的「一般政策」 (邊緣) 或「安全性」 (傳統版 Edge) 頁面中,選取要新增的安全性授權類型。下表摘要列出可用選項:

安全性授權 說明
API 金鑰 為您定義的 API Proxy 新增簡單的 API 金鑰驗證。為回應,API 平台會在您的 API Proxy 中新增 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) 或「安全性 (傳統邊緣)」頁面中,選取「新增 CORS 標頭」來為 API 新增 CORS 支援。

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

使用 OpenAPI 規格產生 Proxy

本節將討論使用 OpenAPI 選項 (可透過 OpenAPI 規範產生下列類型的 API Proxy:反向、Node.js,或者沒有目標)。

什麼是 OpenAPI 規範?

Open API 計畫標誌「Open API 計畫 (OAI) 著重於根據 Swagger 規範,建立、改進和宣傳供應商中立的 API 說明格式。」如要進一步瞭解 Open API 計畫,請參閱 https://openapis.org

OpenAPI 規格使用標準格式來描述符合 REST 樣式的 API。以 JSON 或 YAML 格式編寫的 OpenAPI 規範是機器可讀取的,但也容易讓使用者閱讀和理解。這個規範將 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 Proxy,其中包含系統自動產生的路徑、參數、條件式流程和目標端點。接著,您可以新增 OAuth 安全性、頻率限制和快取等功能。

在「建立 Proxy」精靈中,按一下「使用 OpenAPI 規格」,然後按照精靈的指示,透過 OpenAPI 規範建立反向目標 Proxy 或不使用目標 Proxy。詳情請參閱「使用 OpenAPI 規範建立 API Proxy」。

請觀看這部影片,瞭解如何根據 OpenAPI 規範建立 API Proxy。

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

透過 OpenAPI 規範建立 API Proxy 後,如果您修改規格來新增其他資源路徑,則可以使用規格將相關聯的條件式流程新增至 API Proxy。

如何使用 OpenAPI 規範更新 API Proxy 中的流程:

  1. 將新的資源路徑新增至 OpenAPI 規格。請參閱編輯現有的 OpenAPI 規格
  2. 在使用者介面中開啟 API Proxy,然後按一下「Develop」(開發) 分頁標籤。
  3. 在導覽器中,按一下您要更新的 Proxy 端點旁的「+」+
    系統隨即會開啟「新增條件式流程」對話方塊。
  4. 如果尚未選取「From OpenAPI」,請按一下「From OpenAPI」。
    如果 OpenAPI 規範中的資源在 API Proxy 中沒有相應的條件式流程,則這些資源會列在對話方塊中,如下圖所示。 未在目前 API Proxy 中以資料流表示的資源。此範例包含 /loveapis、/ip、/json 和 /xml。
  5. 選取要新增條件式流程的各項資源。
  6. 按一下 [新增]。

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

建立新的 API Proxy 修訂版本

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

Edge

如何使用 Edge UI 建立新的 API Proxy 修訂版本:

  1. 登入 apigee.com/edge
  2. 在左側導覽列中,依序選取「Develop」(開發) >「API Proxy」
  3. 在清單中按一下要複製的 API Proxy。
  4. 依序選取「Project」>「Save as New Revision」

傳統邊緣 (Private Cloud)

如何使用傳統版 Edge UI 建立新的 API Proxy 修訂版本:

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

複製 API Proxy

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

Edge

如何使用 Edge UI 複製 API Proxy:

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

傳統邊緣 (Private Cloud)

如何使用傳統版 Edge UI 複製 API Proxy:

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

備份 API Proxy

您可以將現有的 API Proxy 備份為 API Proxy 軟體包中的一組 XML 檔案。匯出至軟體包之後,您就能按照本節的「從 API Proxy 套件匯入 API Proxy」一節所述,將 API Proxy 匯入新的 Proxy。詳情請參閱「下載 API Proxy」。

使用 API 建立 API Proxy

如要使用 API 建立 API Proxy,請參閱 API Proxy