建構簡單的 API Proxy

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

注意：在啟用封存部署作業的環境中，您無法使用 Apigee UI、API 或 gcloud 建構 API Proxy。 如要使用 VS Code 中的 Apigee，為封存部署作業建構 API Proxy，請參閱使用 VS Code 中的 Apigee 開發 API Proxy。

Apigee 可協助您快速將後端服務公開為 API。方法是建立 API Proxy，為要公開的後端服務提供門面。您只需要提供後端服務的網路位址，以及 Apigee 用來建立 API Proxy 的一些資訊，即可向開發人員公開 API Proxy。

API Proxy 會將後端服務實作與開發人員使用的 API 分離。這樣一來，開發人員就不會受到後端服務日後變更的影響。更新後端服務時，開發人員不會受到影響，可以繼續呼叫 API。

本主題提供各種 Proxy 類型和相關設定的資訊。 如需建立 Proxy 的逐步操作說明，請參閱下列主題：

• 教學課程：建構第一個 API Proxy
• 建立 API Proxy

使用 UI 建立 API Proxy

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

1. 在 Google Cloud 控制台中，前往「Apigee」>「Proxy 開發」>「API Proxy」頁面。

   前往 API Proxy

2. 點選「+ 建立」。

「建立 Proxy」精靈會顯示，並引導您完成產生 API Proxy 和新增最少功能的步驟。

您可以使用精靈，透過下列來源建立 API Proxy：

類別	類型	說明
一般範本	反向 Proxy (最常見)	API Proxy 會將傳入要求轉送至現有的 HTTP 後端服務。可以是 JSON 或 XML API。請參閱本節稍後的「為 HTTP 服務建立反向 Proxy」。
	未設定目標	沒有 API 後端的 API Proxy (「無目標」)。與先前所述的為 HTTP 服務建立反向 Proxy 類似，但定義 API Proxy 詳細資料時，您不會指定現有 API。
	上傳 Proxy 套件	現有的 API Proxy 套件 (例如 GitHub 上的範例 API Proxy)。請參閱 從 API Proxy 套件匯入 API Proxy。
	使用伺服器傳送事件 (SSE) 的 Proxy	API Proxy，其中包含用於串流伺服器推送事件 (SSE) 的 EventFlow。 詳情請參閱「串流伺服器傳送事件」。
AI 範本	提示詞權杖限制	這項政策與尖峰用量限制類似，可協助您控管使用者提示的權杖用量，防範濫用行為。詳情請參閱「 開始使用 Apigee AI 權杖政策」。
	LLM 詞元配額	管理及限制 LLM API 呼叫的詞元用量。 詳情請參閱「 開始使用 Apigee AI 權杖政策」。
	透過 Model Armor 進行 Proxy	透過清理使用者提示和模型回覆，確保 AI 互動安全。詳情請參閱「 開始使用 Apigee Model Armor 政策」。
	使用語意快取的 Proxy	快取類似要求的回覆，縮短回覆時間並減少 LLM 呼叫次數。詳情請參閱「 開始使用語意快取政策」。
OpenAPI 規格範本	反向 Proxy (最常見)	從有效的 OpenAPI 規格產生 Proxy。如要進一步瞭解這個選項，請參閱本節稍後的「使用 OpenAPI 規格產生 Proxy」。
	未設定目標	沒有 API 後端的 API Proxy (「無目標」)。與先前所述的「為 HTTP 服務建立反向 Proxy」類似，但定義 API Proxy 詳細資料時，您不會指定現有 API。

以下各節將詳細說明每種 Proxy 類型。

為 HTTP 服務建立反向 Proxy

Apigee 會根據下列資訊產生反向 Proxy：

• 後端服務的網址。
• URI 路徑，可明確識別 API Proxy 將向消費者應用程式公開的 API。

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

存取「建立 Proxy 精靈」並選取Proxy 類型後，即可使用下列「Proxy 詳細資料」：

欄位	說明
名稱	API 的顯示名稱。指定英數字元、破折號 (-) 或底線 (_)。
基本路徑	API Proxy 的 http://[host] 或 https://[host] 位址後顯示的 URI 片段。Apigee 會使用基本路徑 URI 比對及轉送傳入的要求訊息至適當的 API Proxy。 注意：API Proxy 的基本路徑預設為 Name 欄位指定的值，並轉換為全小寫。 基本路徑後方是任何其他資源網址。用戶端用來呼叫 API 代理的完整網址結構如下： https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH 注意：基本路徑必須是唯一的，您無法部署兩個基本路徑相同的 API 代理項目。如果您編輯已部署的 API Proxy，並將基本路徑設為與另一個 API Proxy 的基本路徑相同的值，Apigee 會在您儲存時自動取消部署該 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 叫用的後端服務網址。

從 API Proxy 套件匯入 API Proxy

注意：從 API Proxy 套件匯入 API Proxy 時，您必須負責在套件中設定安全性並新增政策。匯入套件時，UI 不會提示您新增安全性或政策，如本節稍後的「新增安全性」所述。

您通常會將 API Proxy 定義為 XML 檔案的集合，以及任何其他支援檔案。將 API Proxy 定義為 Apigee 外部的一組檔案，即可在來源控管系統中維護這些檔案，然後匯入 Apigee 進行測試及部署。

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

1. 按照「使用 UI 建立 API Proxy」一文中的說明，存取「建立 Proxy」精靈。
2. 指定 API Proxy 套件詳細資料。
1. 在「Proxy template」(Proxy 範本) 選單中，選取「Upload proxy bundle」(上傳 Proxy 組合)。
2. 在「Proxy details」(Proxy 詳細資料) 部分中，輸入「Proxy name」(Proxy 名稱)，上傳 zip 檔案，然後按一下「Next」(下一步)。
3. 在「部署」部分中，視需要選取部署環境，然後按一下「建立」。

建立 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

使用新負載平衡器為 gRPC 代理程式建立路由的 gcloud CLI 指令範例

本節顯示使用 gcloud CLI 和新負載平衡器建立 gRPC Proxy 的範例指令。操作說明包括設定負載平衡器、目標伺服器和 MIG。

建立執行個體範本

gcloud compute instance-templates create $MIG_NAME \
--project $PROJECT_ID \
--region $REGION \
--network $VPC_NAME \
--subnet $VPC_SUBNET \
--tags=https-server,apigee-mig-proxy,gke-apigee-proxy \
--machine-type e2-medium --image-family debian-12 \
--image-project debian-cloud --boot-disk-size 20GB \
--no-address \
--metadata ENDPOINT=$APIGEE_ENDPOINT,startup-script-url=gs://apigee-5g-saas/apigee-envoy-proxy-release/latest/conf/startup-script.sh

建立代管執行個體群組

gcloud compute instance-groups managed create $MIG_NAME \
--project $PROJECT_ID --base-instance-name apigee-mig \
--size 2 --template $MIG_NAME --region $REGION

設定自動調度資源功能

gcloud compute instance-groups managed set-autoscaling $MIG_NAME \
--project $PROJECT_ID --region $REGION --max-num-replicas 50 \
--target-cpu-utilization 0.75 --cool-down-period 90

定義具名通訊埠

gcloud compute instance-groups managed set-named-ports $MIG_NAME \
--project $PROJECT_ID --region $REGION --named-ports https:443

為負載平衡器建立 Google 代管的 SSL 憑證和金鑰

gcloud compute ssl-certificates create $CERTIFICATE_NAME \
--domains=$DOMAIN_HOSTNAME \
--project $PROJECT_ID \
--global

驗證憑證是否已佈建完成

gcloud compute ssl-certificates describe $CERTIFICATE_NAME \
--global \
--format="get(name,managed.status, managed.Status)"

建立全球 Cloud Load Balancer (GCLB)

1. 建立健康狀態檢查
   

   gcloud compute health-checks create https hc-apigee-envoy-443 \
   --project $PROJECT_ID --port 443 --global \
   --request-path /healthz/ingress

2. 建立 http1 的後端服務
   

   gcloud compute backend-services create YOUR_BACKEND_1 \
   --project $PROJECT_ID \
   --protocol HTTPS \
   --health-checks hc-apigee-envoy-443 \
   --port-name https \
   --timeout 302s \
   --connection-draining-timeout 300s \
   --global

3. 建立 http2 的後端服務
   

   gcloud compute backend-services create YOUR_BACKEND_2 \
   --project $PROJECT_ID \
   --protocol HTTP2 \
   --health-checks hc-apigee-envoy-443 \
   --port-name https \
   --timeout 302s \
   --connection-draining-timeout 300s \
   --global

4. 將 MIG 新增至後端服務。在本例中，我們重複使用 MIG，但您也可以建立一對新的 MIG。
   

   gcloud compute backend-services add-backend YOUR_BACKEND_1 \
   --project $PROJECT_ID --instance-group $MIG_NAME \
   --instance-group-region $REGION \
   --balancing-mode UTILIZATION --max-utilization 0.8 --global

   gcloud compute backend-services add-backend YOUR_BACKEND_2 \
   --project $PROJECT_ID --instance-group $MIG_NAME \
   --instance-group-region $REGION \
   --balancing-mode UTILIZATION --max-utilization 0.8 --global

5. 建立負載平衡網址對應。請先檢查是否已有網址對應。如有，請務必根據下列規定修改該地圖，而非覆寫地圖。
   

   在 /tmp/apigee-map.yaml 建立 YAML 檔案或使用現有檔案，並採用下列設定。請注意，網址對應 http1 後端是預設值。

   defaultService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_1
   name: matcher1
   routeRules:
   - matchRules:
   - headerMatches:
   - headerName: Content-Type
   prefixMatch: application/grpc
   prefixMatch: /
   priority: 100
   routeAction:
   weightedBackendServices:
   - backendService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_2
   weight: 100

   驗證網址對應：

   gcloud compute url-maps validate --source /tmp/apigee-map.yaml --project $PROJECT_ID

   使用以標頭為準的轉送功能建立網址對應：

   gcloud compute url-maps import apigee-http1-http2 \
   --source /tmp/apigee-map.yaml  \
   --global --project $PROJECT_ID

建立負載平衡目標 HTTPS Proxy

gcloud compute target-https-proxies create apigee-envoy-https-proxy \
--project $PROJECT_ID --url-map apigee-envoy-proxy-map \
--ssl-certificates $CERTIFICATE_NAME

預留 IPv4 外部 IP，並為負載平衡器建立防火牆規則

gcloud compute addresses create lb-ipv4-vip-1 \
--project $PROJECT_ID \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global

  gcloud compute addresses describe lb-ipv4-vip-1 \
--project $PROJECT_ID --format="get(address)" --global

  gcloud compute forwarding-rules create apigee-envoy-https-lb-rule \
--project $PROJECT_ID --address lb-ipv4-vip-1 --global \
--target-https-proxy apigee-envoy-https-proxy --ports 443

建立防火牆規則

gcloud compute firewall-rules create k8s-allow-lb-to-apigee-envoy \
--description "Allow incoming from GLB on TCP port 443 to Apigee Proxy" \
--project $PROJECT_ID --network $VPC_NAME --allow=tcp:443 \
--source-ranges=130.211.0.0/22,35.191.0.0/16 --target-tags=gke-apigee-proxy

為現有負載平衡器建立 gRPC Proxy 路由的 gcloud CLI 指令範例

本節顯示使用 gcloud CLI 和現有負載平衡器建立 gRPC 代理程式的指令範例。操作說明包括設定負載平衡器、目標伺服器和 MIG。

為 http2 建立另一個後端服務

# Create backend service for http2
    gcloud compute backend-services create YOUR_BACKEND_2 \
--project $PROJECT_ID \
--protocol HTTP2 \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

將第二個後端服務附加至 MIG

gcloud compute backend-services add-backend YOUR_BACKEND_2 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

列出現有 Apigee GCLB 的網址對應

gcloud compute url-maps list -project $PROJECT_ID

找出用於 Apigee 負載平衡的正確網址對應名稱

gcloud compute url-maps export APIGEE_URL_MAP_NAME -project $PROJECT_ID

建立負載平衡網址對應 YAML 檔案

如果您已有網址對應，請將這項設定併入其中。否則，請在 /tmp/apigee-map.yaml 建立 YAML 檔案，並使用這項設定。

defaultService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_1
name: matcher1
routeRules:
- matchRules:
- headerMatches:
- headerName: Content-Type
prefixMatch: application/grpc
prefixMatch: /
priority: 100
routeAction:
weightedBackendServices:
- backendService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_2
weight: 100

套用 gRPC 路由的新 YAML

gcloud compute url-maps import APIGEE_URL_MAP_NAME\
--source /tmp/apigee-map.yaml  \
--global -project $PROJECT_ID

新增安全性

只要在 Proxy 中新增政策，即可確保 Proxy 安全。如要進一步瞭解政策，請參閱「什麼是政策」。如要進一步瞭解安全性，請參閱「保護 Proxy 安全」。

如要為 Proxy 新增安全性政策，請按照下列步驟操作：

1. 按照「建立 API Proxy」一文的說明建立 Proxy。
2. 如「保護 Proxy 安全」一文所述，新增安全性政策。最常用的安全性政策是 API 金鑰和 OAuth2。

新增 CORS 支援

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

如要新增 CORS 支援，請將 CORS 政策新增至 ProxyEndpoint 的要求 PreFlow。

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

新增配額

配額可保護後端服務，避免在「配額」Quota下出現高流量。請參閱「配額」。 (如果選取「直通授權」，則無法使用這項功能)。

使用 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 或無目標 Proxy。詳情請參閱「使用 OpenAPI 規格建立 API Proxy」。

建立 API Proxy 的新修訂版本

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

1. 開啟 Apigee UI。

在 Google Cloud 控制台中，前往「Apigee」>「Proxy 開發」>「API Proxy」頁面。

前往 API Proxy

2. 在清單中，按一下要複製的 API Proxy。

3. 按一下「開發」分頁標籤。

4. 選取「儲存」按鈕，然後選取「另存為新的修訂版本」。

備份 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 就很有用。