API 管理與 Apigee

API 管理簡介

在現代微服務架構中，API 是服務的「門面」。對於 Professional Cloud Architect 來說，API 管理不僅僅是流量路由，更關乎安全性、可觀測性、流量限制以及開發者體驗。

Google Cloud 提供兩種主要解決方案：

1. API Gateway: 一種簡單、按需付費的閘道，適用於 Cloud Functions、Cloud Run 和 App Engine。
2. Apigee: 一個功能齊全的 API 管理平台，適用於複雜的企業需求，包括遺留系統和多雲環境。

白話文解釋（Plain English Explanation）

在深入 Apigee 的技術元件前，三個真實世界的比喻能幫助你掌握 API 管理平台在 proxy 層背後實際在做什麼。

比喻 1 — 餐廳前台 (Apigee X Proxy 層)

想像一間繁忙的餐廳。廚房是你的後端微服務（Cloud Run、GKE、地端 SAP）。客戶（行動 App、合作夥伴）永遠不會走進廚房——他們只跟接待台和服務生互動，這就是 Apigee X。接待台檢查訂位（VerifyAPIKey）、優先安排 VIP（Quota 分級）、請大聲的客人安靜（SpikeArrest），並把「我要義大利麵」翻譯成廚師看得懂的點單格式（JSONToXML）。如果廚房失火，接待台可以把客人引導到姊妹店（failover target endpoint）。廚師煮的菜不變——前台才是契約層。

比喻 2 — 機場 Customs 海關 (API Proxy 政策流程)

國際旅客通過海關的流程，就是 Apigee proxy 內部的請求流程。PreFlow 是簽證檢查（OAuth token 驗證）。Conditional Flow 是「有東西要申報」的通道，只對 /payments/* 路徑觸發（額外的 JSONThreatProtection）。PostFlow 是海關蓋章和貨幣兌換（response transformation、masking PII）。Target Endpoint 是你要入境的國家（你的後端）。如果海關在任一步拒絕你（policy failure），你永遠到不了目的地——Apigee 短路並回傳 fault response。

比喻 3 — 銀行櫃台 (Quotas、mTLS、Monetization)

銀行櫃台行員坐在客戶與金庫之間。行員驗證你的身分（OAuthV2）、執行每日提款限制（Quota：10,000 calls/day），通往金庫的門使用只有行員才有的特殊鑰匙（到後端 Cloud Run 的 mTLS 憑證）。對於 premium 客戶，行員提供不同產品與不同手續費——這就是 Apigee Monetization 裡的 API Product 搭配 Rate Plan。金庫不知道也不在乎你是誰；行員（櫃台）才是政策邊界。

為什麼選擇 Apigee？全生命週期管理

Apigee 處理整個 API 生命週期：

• 設計 (Design): 建立 OpenAPI 規範。
• 安全 (Secure): 執行 OAuth、JWT 和 Spike Arrest 政策。
• 分析 (Analyze): 監控誰在使用您的 API 以及其效能表現。
• 營利 (Monetize): 向開發者收取 API 使用費用。
• 開發者入口網站 (Developer Portal): 一個自助服務網站，開發者可以在此探索並測試 API。

Apigee X vs Apigee Hybrid — 部署拓樸深入解析

任何 Apigee 專案最大的架構決策就是選擇 Apigee X（全受管 SaaS）或 Apigee Hybrid（控制面分離）。PCA 考試中，這個選擇由資料落地、網路 egress 與營運責任驅動——而不是功能差異，因為兩者共用同樣的 runtime 引擎。

Apigee X 拓樸

Apigee X 完全運行在 Google 的 tenant project 中。Runtime 部署於兩個以上的 GCP region，並由 Google 處理全球負載平衡。你建立一個 Apigee Organization（與 GCP project 1:1 對應），然後附加 Environment（例如 dev、prod）與 Environment Group 綁定 hostname。資料路徑使用 Service Networking peering 與你的 VPC 連通，以便存取私有後端。

• Capacity Unit: Apigee X 以 pay-as-you-go 或 subscription 級別計算大小。Subscription 會預留吞吐量（calls/sec）與 PSC attachment。
• Cloud Armor 整合: 公開 ingress 經過 Google 受管 external HTTPS LB 與 Cloud Armor WAF 規則。
• Egress: 後端可透過 VPC peering、PSC endpoint 或公網存取。

Apigee Hybrid 拓樸

Hybrid 把架構切開：Management Plane（API Proxy 編寫、analytics 聚合、developer portal）留在 Google Cloud，但 Runtime Plane（apigee-runtime、apigee-synchronizer、apigee-cassandra、apigee-mart pod）跑在你自己的 GKE、Anthos、AKS、EKS 或地端 Kubernetes。

• 使用場景: 銀行、醫療、政府工作負載，payload 不能經過 Google 擁有的 data plane。
• 營運成本: 你要 patch K8s node、管理 Cassandra 備份、自行執行 apigeectl upgrade lifecycle。
• Synchronizer: 單向元件，從 management plane 拉取部署 manifest——只有 outbound HTTPS，沒有 inbound。

API Proxy 結構與政策流程

每一個 Apigee API 都是一個 proxy bundle——壓縮成 zip 的資料夾，內含 endpoint、policy 與資源的 XML 設定。理解流程順序對於除錯考題場景（policy 在錯誤位置觸發）至關重要。

四階段流程

1. ProxyEndpoint.PreFlow: 每個進入 proxy 的 request 都會跑。通常放 VerifyAPIKey 與 OAuthV2。
2. ProxyEndpoint.Conditional Flows: 路徑式 routing（例如 proxy.pathsuffix MatchesPath "/orders/*"）。在這裡套用 Quota 或 JSONThreatProtection。
3. TargetEndpoint.PreFlow: 在呼叫離開 Apigee 前往後端之前執行。通常放 AssignMessage（加上 X-Forwarded-For）或 ServiceCallout（做 token 交換）。
4. TargetEndpoint.PostFlow → ProxyEndpoint.PostFlow: Response transformation、response cache（ResponseCache）、最後 masking（MessageLogging 搭配 PII 清洗）。

Shared Flow

SharedFlow 是可重複使用的政策序列（例如標準的認證鏈），透過 FlowHook 機制掛在 organization 或 environment 範圍。企業就是這樣強制執行「每個 proxy 都要過 threat protection」而不必複製貼上 policy。

Apigee 政策：代理邏輯

政策是 Apigee 的構建塊。您不需要編寫程式碼，而是設定 XML/JSON 政策。

• 流量管理: SpikeArrest (防止 DoS) 和 Quota (隨時間限制使用量)。
• 安全性: VerifyAPIKey、OAuthV2 和 JSONThreatProtection。
• 調解 (Mediation): JSONToXML 或 XMLToJSON 用於格式轉換。
• 擴充: JavaScript 或 Python 政策，用於開箱即用功能之外的自定義邏輯。

流量管理 — SpikeArrest vs Quota 實務

兩種政策看起來很像，但運行在完全不同的層。混淆它們是 Apigee 考題最常見的陷阱。

SpikeArrest — Burst 平滑

SpikeArrest 是類 token-bucket 的 rate limiter，以每秒或每分鐘計算。它是每個 Message Processor instance 各自執行，不是 global。<Rate>30ps</Rate> 實際上翻譯為「每 33ms 一次 request」——同一毫秒到達的三個 request，其中兩個會被拒絕，即使平均下來遠低於 30/sec。

• 目的: 保護下游服務免於瞬間洪峰。
• 計數器位置: 每個 MP 節點的記憶體中。
• Identifier: 可選 <Identifier> 元素；預設為呼叫端 client IP。

Quota — 商業計數

Quota 是儲存在 Cassandra（Hybrid）或受管資料儲存（X）中的分散式計數器。它支援 calendar、rolling、flexi window type，並跨整個 organization 計數。

• 目的: 執行 per-app 或 per-product 商業上限（例如免費層 = 10K/day）。
• 計數器範圍: Apigee X 為跨 region 全域；Hybrid 為 per-region，除非啟用 global distribution。
• Identifier: 通常綁定到從 API Key 或 OAuth token 解析出的 client_id。

分層 Pattern

1. SpikeArrest 放在 ProxyEndpoint.PreFlow——保護 Apigee runtime 本身。
2. Quota 放在認證之後——只計入已驗證的呼叫者。
3. ConcurrentRatelimit（可選）——限制每個後端的 in-flight request。

安全性政策 — OAuth、API Key、JWT、SAML

Apigee 同時扮演 OAuth 2.0 Authorization Server 和 Resource Server。安全政策目錄比多數考生想像的更廣。

API Key 驗證

<VerifyAPIKey> 從 query parameter、header 或 message body 讀取 key，然後到內部 KMS 風格的資料儲存查找。成功驗證後會把 oauthv2.developer.id、apiproduct.name、developer.email 填入 message context——供後續 policy 使用。

OAuthV2 政策

<OAuthV2> 多用途：VerifyAccessToken、GenerateAccessToken、RefreshAccessToken、RevokeAccessToken。Apigee 支援四種 grant type（Authorization Code、Implicit、Password、Client Credentials）。PCA 場景中，Client Credentials 對服務間流量最常見。

JWT 政策

<VerifyJWT>、<GenerateJWT>、<DecodeJWT> 處理已簽章與加密的 token。Apigee 可以對遠端 jwks_uri（會輪替的 Identity Platform key）驗證，無需本地儲存 public key。

SAML

<ValidateSAMLAssertion> 用於合作夥伴傳遞 SAML token 而非 OAuth bearer token 的遺留企業整合。Apigee 透過 ServiceCallout + OAuthV2.GenerateAccessToken 把 SAML 轉成 OAuth。

Cloud Endpoints vs API Gateway vs Apigee — 決策樹

GCP 有三個第一方 API 管理產品。PCA 考試常測驗何時該選哪一個。

決策啟發法

• 「只是想把 Cloud Run 用 API key 包起來」→ API Gateway。
• 「GKE 上的 gRPC 微服務需要認證」→ Cloud Endpoints（ESPv2）。
• 「對外部合作夥伴賣 API 並依用量計費」→ Apigee X。
• 「Runtime 要跑在我們自己的地端 K8s 叢集」→ Apigee Hybrid（甚至沒在這張表上）。

Apigee 中的 API Monetization

Monetization 是 Apigee 獨有的能力——Cloud Endpoints 和 API Gateway 都不支援向開發者收取 API 消費費用。

核心物件

1. API Product: proxy 資源 + quota + 存取等級的組合。
2. Rate Plan: 附加到 API Product；定義定價——Standard（單一費率）、Volume Banded（量級折扣）、Bundle（額度 + 超用）、Revenue Share。
3. Developer: 擁有錢包與帳單資訊。
4. App: 屬於 Developer；依 Rate Plan 消費一個或多個 API Product。

帳單流程

• Apigee 依 client_id 對應到 active Rate Plan 計算每次呼叫。
• 每月帳單以 PDF/CSV 匯出產生；與 Zuora、Stripe、SAP 等帳務系統整合可透過 Monetization API（REST）。
• Revenue share 比例可依合作夥伴設定，對市集型 API 很有用。

常見架構

• Pay-per-call: 每個成功 2xx response 對應一筆 transaction 紀錄；每筆固定價格。
• Freemium: 第一階 Rate Plan 設定 0 元到 10K calls/月，之後自動升級到付費階。
• Revenue share: Apigee 留 30%，合作夥伴拿 70%——透過合作夥伴自己的 Stripe 帳戶收款。

Apigee Analytics — 內建可觀測性

Apigee 自帶強大的 analytics 堆疊，考試常拿來跟 Cloud Logging + Looker Studio 這種外掛方案對比。

Analytics 維度

• API Proxy 效能: 平均回應時間、錯誤率、p95/p99 延遲。
• Developer 互動: 熱門 App、熱門 Developer、每個 API Product 的呼叫數。
• 地理分佈: 依國家、region 的請求來源。
• 自訂維度: 任何透過 <StatisticsCollector> 政策擷取的 message variable。

資料流

每個 Message Processor 會把 analytics 事件批次上傳到 Unified Analytics Platform (UAP)。Apigee X 中 UAP 全受管。在 Hybrid 中，apigee-udca（Universal Data Collection Agent）pod 把資料向外推送到 control plane。

長期保留

Apigee analytics 資料預設保留 14 個月。要長期保留或自訂 BI dashboard，請設定 Apigee Analytics Export to BigQuery 整合，每小時批次寫入到你 project 的 dataset。

Developer Portal — Drupal-based 自助服務

Integrated Developer Portal 是受管的 Drupal CMS，發佈：

• OpenAPI/Swagger spec viewer（透過 SmartDocs 渲染）。
• App 註冊 UI: Developer 登入（Firebase Auth、SAML、Google IdP）、建立 App、選擇 API Product、取得 client_id / client_secret。
• API Catalog: 可讀的 API 描述與 Rate Plan。
• 論壇與文件: 可客製化的 Drupal 頁面。

你可以選 Integrated Portal（零維運、Google host、theming 有限）或 Drupal Self-Hosted Portal（完整 theming、自行在 Cloud Run 或 GKE 跑 Drupal stack）。

到後端的 mTLS — 保護南向跳點

Apigee → 後端的通訊是南向路徑。對受監管的工作負載，mTLS 是必要的。

設定

1. 上傳後端信任憑證到 Apigee Keystore（per environment）。
2. 在 TargetEndpoint.HTTPTargetConnection.SSLInfo 中設定 <Enabled>true</Enabled>、<ClientAuthEnabled>true</ClientAuthEnabled>、<KeyStore> 與 <KeyAlias> 參照。
3. 參照包含後端 CA 的 Truststore。

憑證輪替

• Keystore 支援 alias rotation：以新 alias 上傳新憑證、更新 TargetEndpoint 參照、重新部署。
• 使用 Key Value Map (KVM) 把 alias 名稱外部化，這樣輪替時不需要重新部署 proxy。

常見後端目標

• Cloud Run + 自訂網域 + Cert Manager — Apigee 終結客戶端 TLS，再對 Cloud Run 開啟全新 mTLS。
• GKE Gateway + 受管憑證 — 同 pattern，但 ingress 是你自己的 Gateway controller。
• 透過 Cloud Interconnect 的地端 API — mTLS 跑在私有 peering 之上；Apigee X 用 PSC + VPC SC 連到私有 endpoint。

API Gateway vs. Apigee 摘要表

常見問題 — API 管理與 Apigee

Q1. 何時該選擇 API Gateway 而非 Apigee？

如果您的架構簡單，使用 Google Serverless 後端且僅需基本的身分驗證，請選擇 API Gateway。如果您需要進階分析、營利、開發者入口網站，或有混合雲/多雲需求，請選擇 Apigee。

Q2. Apigee 中的 「API 產品 (API Product)」是什麼？

API 產品是 API 資源 (路徑) 的組合，並帶有特定的配額與安全設定。這是您「銷售」或「發佈」給開發者的內容，而不是讓他們直接存取原始代理。

Q3. Apigee 如何處理高可用性？

Apigee 是全球分佈的。在 Apigee X 中，Google 會管理跨多個區域的擴展與可用性。在 Apigee Hybrid 中，您需負責 Kubernetes 叢集中運行層的可用性。

Q4. Apigee 可以防禦 SQL 注入嗎？

可以。JSONThreatProtection 和 RegularExpressionProtection 等政策可以在惡意負載到達後端之前掃描傳入內容。

Q5. 什麼是「北向 (Northbound)」與「南向 (Southbound)」流量？

北向是從 App/客戶端到 Apigee 的流量。南向是從 Apigee 到您後端服務的流量。

最後的架構師提示

在 PCA 考試中，如果您看到 「開發者入口網站 (Developer Portal)」、「營利 (Monetization)」 或 「將 SOAP 轉換為 REST」 的需求，答案始終是 Apigee。如果需求僅是 「使用 API Key 公開 Cloud Function」，答案很可能是 API Gateway。始終考慮 權責分離 (Separation of Concerns)：Apigee 處理 「API 的業務」，而您的後端處理 「服務的邏輯」。