本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
Apigee 可讓您快速將後端服務公開為 API。方法是建立 API Proxy,為要公開的後端服務提供外觀。您只需要提供後端服務的網路位址,以及 Apigee 用來建立 API Proxy 的一些資訊,這些 API Proxy 會向開發人員公開。
API Proxy 會將後端服務實作與開發人員使用的 API 分離。這可避免開發人員受到後端服務日後變更的影響。更新後端服務時,開發人員不會受到影響,可以繼續呼叫 API。
本主題提供各種 Proxy 類型和相關設定的資訊。 如需建立 Proxy 的逐步操作說明,請參閱下列主題:
使用 UI 建立 API Proxy
建立 API Proxy 最簡單的方法是使用「建立 Proxy」精靈。
Cloud 控制台中的 Apigee 使用者介面
-
在 Google Cloud 控制台中,前往「Proxy development」(Proxy 開發) >「API proxies」(API Proxy) 頁面。
- 點選「+ 建立」。
傳統版 UI
如要使用 Apigee UI 存取「建立 Proxy」精靈,請按照下列步驟操作:
- 登入 Apigee 使用者介面。
- 在導覽列中,依序選取「開發」>「API Proxy」。
- 按一下「建立新項目」。
「建立 Proxy」精靈會顯示,並引導您完成產生 API Proxy 和新增最少功能的步驟。
精靈的第一頁可讓您從下列來源建立 API Proxy:
類型 | 說明 |
---|---|
反向 Proxy (最常見) |
API Proxy 會將傳入要求轉送至現有的 HTTP 後端服務。可以是 JSON 或 XML API。請參閱本節稍後的「為 HTTP 服務建立反向 Proxy」。 按一下「使用 OpenAPI 規格」,從有效的 OpenAPI 規格產生 Proxy。如要進一步瞭解這個選項,請參閱本節稍後的「使用 OpenAPI 規格產生 Proxy」。 |
未設定目標 |
沒有 API 後端的 API Proxy (「沒有目標」)。與先前所述的「為 HTTP 服務建立反向 Proxy」類似,但定義 API Proxy 詳細資料時,您不會指定現有 API。 按一下「使用 OpenAPI 規格」,從有效的 OpenAPI 規格產生 Proxy。如要進一步瞭解這個選項,請參閱本節稍後的「使用 OpenAPI 規格產生 Proxy」。 |
上傳 Proxy 套件 | 現有的 API Proxy 套件 (例如 GitHub 上的範例 API Proxy)。請參閱 從 API Proxy 套件匯入 API Proxy。 |
使用伺服器推送事件 (SSE) 的 Proxy | API Proxy,其中包含用於串流伺服器傳送事件 (SSE) 的 EventFlow 。
詳情請參閱「串流傳送伺服器事件」。 |
以下各節將詳細說明每種 Proxy 類型。
為 HTTP 服務建立反向 Proxy
Apigee 會根據下列資訊產生反向 Proxy:
- 後端服務的網址。
- URI 路徑,可做為 API Proxy 向消費者應用程式公開的 API 專屬 ID。
後端服務網址通常代表貴機構擁有的服務啟用應用程式。也可以指向公開 API。API 或服務可由您控管 (例如內部 HR 應用程式或 Cloud 中的 Rails 應用程式),也可以是第三方 API 或服務 (例如 Twitter 或 Instagram)。
存取「建立 Proxy 精靈」並選取Proxy 類型後,即可查看下列 Proxy 詳細資料:
欄位 | 說明 |
---|---|
名稱 | API 的顯示名稱。指定英數字元、破折號 (-) 或底線 (_)。 |
基本路徑 |
API Proxy 的 基本路徑後方是任何其他資源網址。用戶端用來呼叫 API Proxy 的完整網址結構如下:
在基本路徑中使用萬用字元 在 API Proxy 基礎路徑中使用一或多個 |
說明 | (選用) API 說明。 |
目標 (現有 API) | 這個 API Proxy 叫用的後端服務網址。 |
從 API Proxy 套件匯入 API Proxy
您通常會將 API Proxy 定義為 XML 檔案的集合,以及任何其他支援檔案。將 API Proxy 定義為 Apigee 外部的一組檔案,即可在來源控管系統中維護這些檔案,然後匯入 Apigee 進行測試及部署。
如要從 API Proxy 組合匯入 API Proxy,請按照下列步驟操作:
- 按照「使用 UI 建立 API Proxy」一文中的說明,存取「建立 Proxy」精靈。
- 指定 API Proxy 組合詳細資料。
- 在「Proxy template」(Proxy 範本) 選單中,選取「Upload proxy bundle」(上傳 Proxy 組合)。
- 在「Proxy details」(Proxy 詳細資料) 部分,輸入「Proxy name」(Proxy 名稱),上傳 zip 檔案,然後按一下「Next」(下一步)。
- 在「Deploy」(部署) 區段中,視需要選取部署環境,然後按一下「Create」(建立)。
- 按一下「上傳 Proxy 組合」。
-
在 Proxy 精靈的「Upload proxy bundle」(上傳 Proxy 套裝組合) 頁面中,輸入下列資訊:
欄位 說明 ZIP 檔案組合 內含 API Proxy 設定的 ZIP 檔案。拖曳或按一下即可前往檔案。 名稱 API 的顯示名稱。預設為 ZIP 檔案的名稱 (不含副檔名)。 - 點選「下一步」。
在「Summary」(摘要) 頁面上,視需要選取部署環境,然後按一下「Create and deploy」(建立及部署)。
畫面會顯示確認訊息,指出新的 API Proxy 已成功建立。
- 按一下「編輯 Proxy」,即可顯示 API Proxy 的詳細資料頁面。
Cloud 控制台中的 Apigee 使用者介面
傳統版 UI
建立 gRPC API Proxy
除了 REST API Proxy,Apigee 目前也支援 僅具直通支援功能的 gRPC API Proxy。有了直通支援,gRPC 酬載本身對 Apigee 而言是不透明的,流量會從 gRPC 用戶端路由至目標設定中預先設定的 gRPC 目標伺服器。目前,Apigee gRPC API Proxy:
- 支援一元 gRPC 要求。
- 無法使用會影響酬載的政策。
- 可用於未與 GraphQL 或 REST 代理程式建立關聯的 API 產品。API 產品專屬配額和其他作業設定會套用至產品中的所有 Proxy。
- Apigee Hybrid 不支援。
- 使用兩個 gRPC 專屬流程變數:
request.grpc.rpc.name
和request.grpc.service.name
。 -
可透過下列 gRPC 專屬 Apigee Analytics 變數監控:
x_apigee_grpc_rpc_name
、x_apigee_grpc_service_name
和x_apigee_grpc_status
。 - 傳回 gRPC 狀態碼。
您也必須設定負載平衡器,才能支援 gRPC。請參閱「將 gRPC 與您的應用程式搭配使用」和「使用 gcloud CLI 指令為 gRPC 建立路由」。
如要建立 gRPC API Proxy,請先定義 gRPC 目標伺服器 (請參閱「建立 TargetServer」),然後在建立新 Proxy 時指定該目標伺服器。
使用 gcloud CLI 指令為 gRPC 建立路由
本節將使用 gcloud CLI,示範如何建立 gRPC Proxy 的路由。操作說明包括設定負載平衡器、目標伺服器和 MIG。
本節並非建立路徑的完整指南。 這些範例可能不適用於所有用途。此外,這些操作說明假設您熟悉外部路由 (MIG) 和 Cloud Load Balancer gRPC 設定。
設定環境變數
這些環境變數會用於子章節中的指令。
PROJECT_ID=YOUR_PROJECT_ID MIG_NAME=YOUR_MIG_NAME VPC_NAME=default VPC_SUBNET=default REGION=REGION_NAME APIGEE_ENDPOINT=ENDPOINT CERTIFICATE_NAME=CERTIFICATE_NAME DOMAIN_HOSTNAME=DOMAIN_HOSTNAME
新增安全防護
只要在 Proxy 中新增政策,即可確保 Proxy 安全。如要進一步瞭解政策,請參閱「什麼是政策」。如要進一步瞭解安全性,請參閱「保護 Proxy 安全」。
如要在 Proxy 中新增安全性政策,請按照下列步驟操作:
Cloud 控制台中的 Apigee
- 按照「建立 API Proxy」一文的說明建立 Proxy。
- 如「保護 Proxy 安全」一文所述,新增安全性政策。最常用的安全性政策是 API 金鑰和 OAuth2。
傳統版 Apigee UI
在「建立 Proxy」精靈的「Common policies」(通用政策) 頁面中,選取要新增的安全授權類型。下表摘要列出可用的選項:
安全授權 | 說明 |
---|---|
API 金鑰 | 在您定義的 API Proxy 中加入簡單的 API 金鑰驗證。API 平台隨即會在 API 代理中新增 VerifyAPIKey 政策和 AssignMessage 政策。VerifyAPIKey 政策會驗證要求應用程式提供的 API 金鑰。AssignMessage 政策會從轉送至後端伺服器的要求中,移除 API 呼叫中以查詢參數形式提供的 API 金鑰。 |
OAuth 2.0 | 在 API Proxy 中新增以 OAuth 2.0 為基礎的驗證機制。Apigee 會自動將下列政策新增至 API Proxy:一項政策用於驗證存取權杖,另一項政策則用於從訊息中移除存取權杖,再將訊息轉送至後端服務。如要瞭解如何取得存取權杖,請參閱 OAuth。 |
直接放行 (不需授權) | 無須授權。要求會傳送至後端,Apigee 不會進行任何安全性檢查。 |
新增 CORS 支援
跨源資源共享 (CORS) 是一種標準機制,可讓網路瀏覽器直接向其他網域提出要求。CORS 標準定義了一組 HTTP 標頭,供網頁瀏覽器和伺服器用於實作跨網域通訊。
如要新增 CORS 支援,請將 CORS 政策新增至 ProxyEndpoint 的要求 PreFlow。
如要進一步瞭解 CORS 支援,包括如何為 Proxy 新增 CORS 預檢支援,請參閱「為 API Proxy 新增 CORS 支援」。
新增配額
配額可保護後端服務,避免在「配額」下出現高流量。請參閱「配額」。 (如果選取「直通授權」,則無法使用這項功能)。
使用 OpenAPI 規格產生 Proxy
本節將說明「使用 OpenAPI」選項,這個選項可用於從 OpenAPI 規格產生下列類型的 API Proxy:反向或無目標。
什麼是 OpenAPI 規格?
「Open API Initiative (OAI) 致力於根據 Swagger 規格,建立、演進及推廣與供應商無關的 API 說明格式。」詳情請參閱 OpenAPI 計畫。
OpenAPI 規格採用標準格式說明 RESTful API。OpenAPI 規格可採用 JSON 或 YAML 格式,不僅可供機器讀取,也方便使用者閱讀及瞭解。規格說明 API 元素,例如基本路徑、路徑和動詞、標頭、查詢參數、作業、內容類型、回應說明等。此外,OpenAPI 規格通常用於產生 API 說明文件。
以下 OpenAPI 規格片段說明 Apigee 的模擬目標服務 http://mocktarget.apigee.net。詳情請參閱 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 後,您可以使用 Apigee UI 進一步開發,例如新增政策、實作自訂程式碼等,就像任何 Apigee Proxy 一樣。
使用 OpenAPI 規格建立 API Proxy
使用 OpenAPI 規格建立 API Proxy。只要按幾下,系統就會自動產生路徑、參數、條件流程和目標端點,建立 API 代理。然後新增 OAuth 安全性、頻率限制和快取等功能。
在「建立 Proxy」精靈中,按一下「使用 OpenAPI 規格」,然後按照精靈指示,使用 OpenAPI 規格建立反向或無目標 Proxy。詳情請參閱「使用 OpenAPI 規格建立 API Proxy」。
建立新的 API Proxy 修訂版本
如要建立 API Proxy 的新修訂版本,請按照下列步驟操作:
- 開啟 Apigee UI。
- 登入 Apigee 使用者介面。
- 在導覽列中,依序選取「開發」>「API Proxy」。
- 在清單中,按一下要複製的 API Proxy。
-
按一下「開發」分頁標籤。
- 選取「儲存」按鈕,然後選取「另存為新修訂版本」。
Cloud 控制台中的 Apigee
在 Google Cloud 控制台中,前往「Proxy development」(Proxy 開發) >「API proxies」(API Proxy) 頁面。
傳統版 Apigee UI
備份 API Proxy
您可以將現有 API Proxy 備份為 API Proxy 套件中的一組 XML 檔案。匯出至套件後,您可以將 API 代理程式匯入新的代理程式,如本節稍早的「從 API 代理程式套件匯入 API 代理程式」所述。詳情請參閱「下載 API Proxy」。
使用 API 建立 API Proxy
如要使用 API 建立 API Proxy,請參閱建立 API Proxy。
關於沒有目標 Proxy
如果您想在 Apigee 本身處理要求,而不將要求轉送至後端服務,Apigee 中的無目標 Proxy 就非常實用。請務必瞭解何時適合採用這種做法。
常見用途
- 與 Apigee 管理的資料互動: 如果您只需要與 Apigee 管理的資料互動,例如儲存在鍵/值對應 (KVM) 或 Apigee 快取中的資料,則無目標 Proxy 就非常實用。 舉例來說,您可以使用無目標 Proxy 從 KVM 擷取資料,例如使用者工作階段資料或設定資料。在這種情況下,不需要呼叫後端服務。您只需要在 Proxy 流程中加入 KeyValueMapOperations 政策。再舉一例,您可能希望來電者要求清除快取。您可透過叫用 InvalidateCache 政策來完成這項操作,不必連線至目標。
- 使用模擬 API:您可以在後端實作完成前建立模擬 API,模擬 API 行為,讓前端開發作業能獨立進行。如要進一步瞭解如何建立模擬 API,請參閱 OpenAPI 模擬 API Proxy。
- 權杖管理:Apigee 可以發行 OAuthV2 權杖,通常是透過無目標 Proxy 進行。
- 測試政策行為:如果您想試用 Apigee 政策來測試其行為,無目標 Proxy 就很實用。