Amazon API Gateway

Amazon API Gateway 是什麼？

Amazon API Gateway 是 AWS 的全託管服務，讓你在任意規模下建立、發布、保護、監控及商業化 API。在 DVA-C02 考試中，Amazon API Gateway 完全屬於 Domain 1（使用 AWS 服務進行開發），因為開發者會以 Amazon API Gateway 作為 HTTPS 入口，銜接 Lambda 函式、整合任何 HTTP 後端，以及直接將 AWS 服務 API 暴露給網際網路或 VPC 客戶端——全程無需運行任何 EC2 執行個體。Amazon API Gateway 免除了在每個微服務裡手工搭建 TLS 終止、請求驗證、授權、throttling 與配額執行層的需要，讓這些曾是樣板程式碼的事全交給 API Gateway 處理。

DVA-C02 考試指南在 Task Statement 1.3（「為 AWS 上的應用程式開發程式碼」）和 Task Statement 3.3（「將應用程式設計實作到程式碼中」）都明確點出 Amazon API Gateway。考題測試三項實作能力：用正確的 integration type 將 Amazon API Gateway 接上 Lambda 函式、用正確的 authorizer 保護 Amazon API Gateway 端點，以及透過 usage plans、stage variables、canary releases、throttling 和 caching 來操作 Amazon API Gateway 部署。AWS 推出的每一套 serverless 參考架構——Web 後端、行動後端、公開 API、聊天應用程式、IoT 指令端點——都以 Amazon API Gateway 作為邊緣入口，因此這個主題的知識會與 DVA-C02 藍圖其他部分相互增強。

Amazon API Gateway 提供三種 API 類型，開發者必須清楚區分：REST API（原始、功能最完整的變體）、HTTP API（更便宜、延遲更低，2019 年推出）、以及 WebSocket API（雙向即時訊息）。本篇 DVA-C02 學習指南涵蓋 Amazon API Gateway 的每一個設定細節，從以 Velocity Template Language（VTL）撰寫的 request-response mapping templates，到 Cognito User Pool authorizers、Lambda authorizers、usage plans、stage variables、canary deployments、throttling、caching、CORS preflight、AWS WAF 整合、custom domain names，以及 OpenAPI 匯入／匯出。讀完之後，DVA-C02 上的 Amazon API Gateway 題目應該如同送分題。

白話文解釋 Amazon API Gateway

Amazon API Gateway 負責的事情太多，初學者往往難以建立清晰的心智模型。以下三個類比從不同角度詮釋 Amazon API Gateway——挑最符合你直覺的那一個。

類比一——Amazon API Gateway 是便利商店的服務台

想像 Amazon API Gateway 是一家大型便利商店的服務台。顧客（API 呼叫方）帶著各種需求走進來：退換貨、儲值、取包裹、詢問優惠。服務台（Amazon API Gateway）是唯一的入口。它核對身份（authorizer）、查詢會員等級確認可用服務（usage plan 與 API key）、把需求轉介給對應的部門（Lambda 函式、HTTP 後端、AWS 服務整合）、將請求翻譯成部門內部的作業語言（mapping template、VTL）、把部門的回覆轉換成顧客看得懂的語言（response mapping），並記錄每一筆互動（CloudWatch Logs、access logs）。服務台同時執行店規：每位顧客每分鐘最多 10 次服務（throttling）、每天上限 500 次（quota）、某些服務需要特殊會員卡才能使用（IAM 或 Cognito authorizer）。商品倉庫、廚房、物流部門（你的 Lambda 函式與後端）從不直接面對顧客——所有事都經過服務台。這正是 Amazon API Gateway 將後端與混亂的網際網路隔開的方式。

類比二——Amazon API Gateway 是瑞士刀

Amazon API Gateway 是 API 開發的瑞士刀。REST API 刀片給你完整的工作台：request validation、response mapping、API keys、usage plans、caching、WAF 整合、private APIs、mutual TLS。HTTP API 刀片是輕量口袋刀：內建 JWT authorizer、更低成本、更低延遲，適合直接代理 Lambda 的場景。WebSocket API 刀片是雙向刀：$connect、$disconnect、$default 路由讓伺服器可主動推送訊息給客戶端，這是 REST 和 HTTP API 做不到的。三把刀共用同一個刀柄（Amazon API Gateway 控制平面、帳單、監控），但各自擅長不同的切割。用錯刀片代價不輕：在只需要 HTTP API 的場景硬用 REST API，每次請求的費用可能高出三倍。DVA-C02 很喜歡出這個陷阱。

類比三——Amazon API Gateway 是捷運站閘門系統

Amazon API Gateway 是繁忙捷運站的閘門系統。每位乘客（HTTP 請求）都必須通過閘門才能進入月台（後端）。閘門驗證票卡（authorizer）、確認乘客的票種符合進站條件（request validation）、根據當前人流分配閘道（throttling、burst control）、在閘道滿載時讓乘客等候（429 Too Many Requests），並記錄每一筆進出紀錄（CloudWatch metrics、X-Ray traces）。Canary deployments 如同分階段開放新月台：10% 的乘客導入新月台，90% 留在舊月台，觀察後再逐步調高比例。Stage variables 是路線變數：prod 站台指向正式路線，dev 站台指向測試路線，同一套閘門系統、同一個操作介面，卻指向不同目的地。WAF 則是進站前的安全掃描系統，過濾威脅後乘客才能抵達閘門。

掌握服務台、瑞士刀與捷運閘門這三個類比之後，Amazon API Gateway 的其他功能都能自然套入這套心智模型。

Amazon API Gateway API 類型——REST vs HTTP vs WebSocket

DVA-C02 考試中，Amazon API Gateway 最常考的決策就是選擇正確的 API 類型。Amazon API Gateway 提供三種類型，各有獨特的功能矩陣、定價與延遲特性。

REST API

Amazon API Gateway 的原始提案。REST API 是功能最完整的變體，支援所有 Amazon API Gateway 能力：request validation、mapping templates（VTL）、method-level IAM／Cognito／Lambda authorizers（含結果快取）、API keys、usage plans、per-method caching、request/response transformations、透過 VPC Link 連接 NLB 的 private integrations、僅限 VPC 存取的 private REST APIs、mutual TLS、AWS WAF，以及 OpenAPI 匯入／匯出。

當你需要 VTL mapping templates、針對不同路由設定不同 method-level throttling、用 API keys 搭配 usage plans 實現商業化、建立 VPC 內的 private APIs、mutual TLS，或整合 Lambda 以外的 AWS 服務（例如直接整合 DynamoDB 或 Step Functions）時，請選擇 REST API。

HTTP API

2019 年推出，定位為 Amazon API Gateway 中針對常見 serverless 使用案例更便宜、延遲更低的變體。HTTP API 比 REST API 便宜約 70%，由於執行路徑較短，p99 延遲也更低。HTTP API 原生支援 JWT token（通常來自 Amazon Cognito User Pools）、將 CORS 設定為單鍵完成，並支援自動部署。

HTTP API 以簡單性換取功能性。HTTP API 不支援：VTL mapping templates、API keys、usage plans、per-method caching（完全無快取）、JSON schema 的 request validation、AWS WAF、private APIs（只有公開端點和 VPC Link v2）、自訂 CA 的 mutual TLS，以及 AWS X-Ray（部分場景於後期加入）。

當你的工作負載是直接代理 Lambda 或 HTTP 後端、搭配 JWT 授權，且不需要上述 REST API 進階功能時，請選擇 HTTP API。

WebSocket API

Amazon API Gateway 的雙向通訊變體。WebSocket API 管理持久的全雙工連線，讓伺服器可主動推送訊息給客戶端——對聊天應用程式、即時儀表板、協同編輯、運動即時比分和 IoT 指令控制不可或缺。WebSocket API 的路由以 route selection expression 為鍵（通常是 $request.body.action），而非 HTTP path 加 method。內建三個路由：$connect（新連線時觸發，適合用於授權）、$disconnect（連線斷開時觸發）和 $default（預設 fallback）。

每個連線以 connectionId 識別。Lambda 函式透過 @connections 管理 API 搭配 connection ID 向客戶端傳送訊息。計費方式為每連線分鐘加每訊息，閒置連線比活躍連線便宜，但仍會計費。

REST vs HTTP vs WebSocket 功能與費用矩陣

Amazon API Gateway Integration 類型——後端的接線方式

Amazon API Gateway 位於後端前方，但「後端」可以代表很多東西。Integration type 告訴 Amazon API Gateway 如何呼叫後端，以及如何塑造 payload。REST API 有六種 integration types；HTTP API 的選項較少。

Lambda Proxy Integration（AWS_PROXY）

Lambda proxy integration 是預設且最常用的接線方式。Amazon API Gateway 將整個 HTTP 請求（method、path、headers、query parameters、body、request context）打包成一個 JSON event 物件交給 Lambda。Lambda 函式必須回傳特定格式的 JSON 物件：{statusCode, headers, body, isBase64Encoded}，Amazon API Gateway 再以此作為 HTTP 回應。整個過程不涉及 mapping templates——開發者在 Lambda 函式內部負責解析和格式化。

95% 的 Lambda 工作負載使用 Lambda proxy。它更容易理解、開發速度更快，並與 AWS SAM、Serverless Framework 和 Lambda Powertools 程式庫相容。

Lambda Non-Proxy Integration（AWS，自訂整合）

Lambda non-proxy integration（又稱「custom integration」）在 request 和 response 兩端都使用 VTL mapping templates。你撰寫一個 integration request template，將傳入的 HTTP 請求轉換成 Lambda 預期的精確 JSON 格式；再撰寫一個 integration response template，將 Lambda 輸出重塑為 HTTP 回應。這使 Lambda 函式的內部契約與公開 API 介面解耦。

當必須讓 Lambda 函式對 HTTP 無感知（例如從 Step Functions 重複使用、接受扁平物件的函式）、需要在邊緣移除或重新命名欄位，或需要 per-status-code response mapping 時，請選擇 Lambda non-proxy。

HTTP Integration 與 HTTP Proxy

HTTP integration 將 Amazon API Gateway 指向任何公開的 HTTP 後端——ELB、第三方 API，或可從網際網路存取的本地端點。HTTP proxy 原封不動地傳遞請求；HTTP non-proxy（自訂整合）以與 Lambda non-proxy 相同的方式使用 mapping templates。

AWS Service Integration

Amazon API Gateway 可直接呼叫許多 AWS 服務 API，中間不需要 Lambda。常見範例：PUT 到 DynamoDB、啟動 Step Functions 執行、發布到 SNS、發送到 SQS、上傳到 S3。你將呼叫模型化為 SigV4 簽名請求，Amazon API Gateway 假設 IAM 角色來執行動作。這種「無 Lambda」模式在工作只是簡單的 AWS 服務呼叫時可節省成本與 cold-start 延遲。

Mock Integration

Mock integration 直接回傳預設回應，不呼叫任何後端。適用於 CORS preflight OPTIONS 回應、開發期間的佔位端點，或對負載測試進行依賴項 stubbing。

VPC Link（Private Integration）

VPC Link 讓 Amazon API Gateway 連接到私有 VPC 內的資源。對於 REST API，VPC Link 的目標是 Network Load Balancer（NLB），前方有 ECS tasks、EC2 執行個體，或透過 Direct Connect／VPN 連接的本地資源。對於 HTTP API，VPC Link v2 的目標可以是 ALB、NLB 或 AWS Cloud Map 服務，彈性更大。

Lambda Proxy vs Lambda Non-Proxy——最經典的陷阱

DVA-C02 上 Amazon API Gateway 出現頻率最高的陷阱，就是區分 Lambda proxy 和 Lambda non-proxy。請背下這段：

• Lambda proxy（AWS_PROXY）：無 mapping templates，Lambda 必須回傳精確的 API Gateway response 格式，更簡單，大多數 serverless 應用程式的預設選擇。
• Lambda non-proxy（AWS）：request 和 response 兩端都需要 mapping templates，Lambda 對 HTTP 無感知，適合需要在邊緣做 reshaping 的場景。

若題目提到 VTL、mapping templates 或 request transformation，答案是 Lambda non-proxy。若題目提到 event.requestContext、event.pathParameters，或 {statusCode, body, headers} 的回傳格式，答案是 Lambda proxy。

Request 與 Response Mapping Templates（VTL）

Velocity Template Language（VTL）是 Amazon API Gateway 在 non-proxy integrations 中用來轉換 request 和 response 的腳本語言。Mapping templates 掛載在 integration request（傳入 HTTP → 後端 payload）或 integration response（後端輸出 → HTTP 回應）上，並對應特定的 content type（通常是 application/json）。

關鍵 VTL 變數

Amazon API Gateway 在每個 template 中提供豐富的 $input、$context、$stageVariables 和 $util 物件：

• $input.body — 原始 request body（字串形式）。
• $input.json('$.path') — JSONPath 擷取，回傳 JSON。
• $input.params() — 合併的 path、query、header 參數。
• $input.params('name') — 跨 path、query、headers 的單一參數查詢。
• $context.identity.sourceIp — 呼叫方 IP 位址（亦有 $context.identity.userAgent、$context.identity.cognitoIdentityId）。
• $context.authorizer.claims.sub — 已驗證的 Cognito 使用者 sub（Cognito authorizer 觸發時）。
• $context.authorizer.principalId — Lambda authorizer 回傳的自訂 principal。
• $stageVariables.varName — 當前 stage 的 stage variable 值。
• $util.escapeJavaScript(value) — 安全地將字串轉義為 JSON 格式。
• $util.base64Encode(value) / $util.base64Decode(value) — 二進位輔助函式。

範例——Request Mapping Template

{
  "userId": "$context.authorizer.claims.sub",
  "product": $input.json('$.product'),
  "quantity": $input.json('$.quantity'),
  "sourceIp": "$context.identity.sourceIp",
  "env": "$stageVariables.targetEnv"
}

此 template 將傳入的 REST 請求轉換成 Lambda（或 Step Functions、DynamoDB 等）預期的扁平物件，並附加已驗證使用者的 sub 和 stage 環境名稱。

Integration Response Mapping 與 Status Codes

在 response 端，Amazon API Gateway 透過 regex 比對後端輸出的錯誤字串，對應到 method responses。例如，Lambda 拋出 "NotFound: user abc123" 可以對應到 404 status 並回傳整理過的 body：

{
  "error": "USER_NOT_FOUND",
  "message": "$util.escapeJavaScript($input.path('$.errorMessage'))"
}

Amazon API Gateway 授權選項

Amazon API Gateway 為 REST API 支援五種授權機制，HTTP／WebSocket 的支援範圍較少。選擇正確的 authorizer 是 DVA-C02 的高頻考點。

1. IAM 授權（AWS_IAM）

使用 SigV4 簽名。最適合呼叫方已有 AWS 憑證的內部服務對服務呼叫（EC2 instance role、Lambda execution role、另一個 AWS 帳戶）。呼叫方的 IAM policy 必須在 Amazon API Gateway ARN 上授予 execute-api:Invoke。

使用情境：內部管理用的 Lambda 呼叫內部 API，或行動應用程式使用 Cognito Identity Pools 取得暫時 AWS 憑證並簽名請求。

2. Cognito User Pool Authorizer

Amazon API Gateway 驗證 Cognito User Pool 核發的 JSON Web Token（JWT）。客戶端對 Cognito 驗證後取得 ID token 和 access token，再透過 Authorization header（通常以 bearer token 形式）傳送 token。Amazon API Gateway 驗證簽名、issuer、audience 和到期時間，並將 claims 以 $context.authorizer.claims.* 形式提供給下游使用。

使用情境：由 Cognito 處理註冊／登入的消費者行動或 Web 應用程式。

3. Lambda Authorizer（TOKEN 類型）

Lambda authorizer 是開發者撰寫的函式，Amazon API Gateway 在路由請求前先呼叫它。TOKEN 類型只接收一個 token 值（來自特定 header，通常是 Authorization），並必須回傳允許或拒絕呼叫的 IAM policy 文件。TOKEN 適用於 bearer token 方案：來自非 Cognito issuer（Auth0、Okta、Firebase）的 JWT、OAuth 2.0 不透明 token，或自訂 token。

4. Lambda Authorizer（REQUEST 類型）

REQUEST 類型接收完整的 request context——headers、query strings、stage variables、source IP、path——並根據其任意組合作出決策。當授權邏輯依賴的不只是單一 token 時使用 REQUEST：多 header 方案、IP 允許清單結合 token，或需查詢外部系統的業務規則檢查。

Lambda Authorizer 結果快取

TOKEN 和 REQUEST authorizers 都支援透過 authorizer result TTL 設定的快取（預設 300 秒，最長 3600 秒，設為 0 則停用快取）。Amazon API Gateway 以 identity source 為鍵快取回傳的 IAM policy（TOKEN 類型使用 token；REQUEST 類型使用開發者指定的 headers／query／stage variables 子集）。快取大幅降低 Lambda authorizer 呼叫次數和延遲，但也意味著已撤銷的 token 在 TTL 內仍有效——設計時需考慮此點。

REQUEST authorizers 的快取鍵定義在 identity sources 欄位中。若 identity source 包含 $request.header.Authorization, $request.header.X-Tenant-Id，則快取以兩者組合為鍵。相同值命中快取；不同值則 miss 並重新呼叫 authorizer。

5. API Keys 加 Usage Plans（非真正的授權）

API keys 本身不是驗證機制——洩漏的 API key 就能直接使用。它們的用途是識別呼叫方，以便透過 usage plans 執行配額和 throttling。要實現真正的安全性，請將 API keys 與另一個 authorizer（IAM、Cognito、Lambda）搭配使用。

Authorizer 類型決策矩陣

Usage Plans 與 API Keys——Throttling 與 Quota

Usage plans 是 REST API 獨有的功能，讓你對每個 API key 執行 throttling（每秒請求數）和 quota（每日／週／月請求數）。它們是 API 商業化模式的基礎。

建立 Usage Plan

一個 usage plan 關聯一個或多個 API stages，並定義三個參數：

• Throttle rate limit — 允許的穩態每秒請求數。
• Throttle burst limit — 短暫高峰的 token bucket 大小。
• Quota — 滾動視窗上限（例如每日 10,000 次請求）。

然後將 API keys 與 usage plan 關聯。當請求帶有 x-api-key 時，Amazon API Gateway 查找該 key 的 usage plan 並執行 throttling 和 quota 限制。超出限制回傳 HTTP 429 Too Many Requests。

分層方案模式

一個經典的商業化模式使用三個 usage plans——Free（每日 100 次）、Silver（每日 10,000 次）、Gold（每日 1,000,000 次）——搭配不同的 throttle 和 burst 設定。每位客戶取得一個綁定其層級的 API key。升級客戶只需將其 key 移至更高層級的方案。

必要設定步驟

1. 建立 API key（或為每位客戶產生專屬 key）。
2. 建立帶有 throttle 和 quota 的 usage plan。
3. 將 usage plan 關聯到想計量的 stage。
4. 將 API key 關聯到 usage plan。
5. 在 stage 上將對應 method 標記為 API Key Required: true。
6. 客戶端在每次請求的 x-api-key header 中傳送 key。

Stage Variables 與 Canary Deployments

Stage Variables

Stage variables 是綁定到特定 Amazon API Gateway stage（例如 dev、qa、prod）的名稱-值對。它們對 API 而言就像環境變數：同一個部署成品依據呼叫的 stage 指向不同的後端。常見用途：

• 依 stage 指向不同的 Lambda alias（$stageVariables.lambdaAlias），讓 prod 呼叫 LIVE alias，dev 呼叫 DEV alias。
• 在 mapping templates 中嵌入 stage 特定值（$stageVariables.targetEnv）。
• 依 stage 改寫 HTTP integration 端點（https://$stageVariables.backendHost/orders）。

Stage variables 不是秘密管理工具——它們是明文設定，在 console 中可見。請使用 AWS Systems Manager Parameter Store 或 AWS Secrets Manager 儲存機密。

Canary Deployments

Amazon API Gateway REST API 原生支援 canary deployments。Canary 是附加到現有 stage 的第二個部署，接收可設定比例的流量。兩個部署共用同一個 stage，而 stage variables 可獨立設定（讓 canary 指向新的 Lambda alias 或後端，而 baseline 維持現有版本）。

Canary 工作流程：

1. 將 v1 部署到 prod stage。100% 流量導向 v1。
2. 在 prod stage 建立指向部署 v2 的 canary，設定 10% 流量。
3. 觀察 canary 的 CloudWatch metrics 和 access logs。
4. 若健康，逐步調高至 50%，再到 100%，或將 canary 提升為基礎部署。
5. 若不健康，刪除 canary——所有流量留在 v1。

Canaries 支援 per-canary stage variables、per-canary Amazon API Gateway caching，以及以 $context.canary 為範圍的獨立 CloudWatch metrics。

Amazon API Gateway Throttling——帳戶、Stage、Method 與 Burst

Amazon API Gateway 的 throttling 是分層模型。請求依序對多個限制進行檢查；最嚴格的限制獲勝。

帳戶層級 Throttling（軟性限制）

每個 AWS 帳戶在 Region 內所有 API 共享預設的 Amazon API Gateway throttle：穩態 10,000 requests per second，burst 為 5,000 requests。這是透過 AWS Support 提升的軟性限制。若超出帳戶層級 throttle，呼叫方會收到 429，不論個別 API 的設定為何。

Stage 層級 Throttling

在每個 stage 設定 throttle rate limit 和 burst limit。這為整個 stage（所有 method 合計）設定上限。適合保護測試 stage 免於失控的負載。

Method 層級 Throttling

在特定 route + method 組合上覆蓋 stage 層級設定。當某個端點的成本遠低於或遠高於其他端點、需要更嚴或更寬鬆的限制時使用。在 Stage > Method Settings 中設定。

Per-Client（Usage Plan）Throttling

在全域 throttle 之上針對每個 API key 套用。（帳戶、stage、method、usage-plan）四者中最嚴格的獲勝。

Burst 解釋

Amazon API Gateway 使用 token bucket 演算法。穩態速率持續補充 token；burst size 是 bucket 的深度。Burst 5,000、速率 10,000/s 意味著呼叫方可以瞬間發出最多 5,000 個請求，但後續請求以 10,000/s 的速率補充 token。Burst 在不懲罰行為良好的呼叫方的情況下處理自然的請求叢聚。

HTTP 429 Too Many Requests

被 throttle 時，Amazon API Gateway 回傳 HTTP 429，並在可用時附帶 Retry-After header。客戶端應實作帶 jitter 的指數退避。AWS SDK 會自動處理此行為。

Amazon API Gateway Caching

Amazon API Gateway REST API 在 stage 層級支援專用的 response cache。啟用後，Amazon API Gateway 會佈建快取叢集，並以請求參數為鍵快取 GET 回應。

快取叢集大小

Amazon API Gateway 提供 0.5 GB 到 237 GB 的快取叢集大小，按小時計費，不論使用量多少。可選大小：0.5、1.6、6.1、13.5、28.4、58.2、118、237 GB。叢集越大，命中率越高，費用也越高。

TTL

預設 TTL 為 300 秒，可依 method 設定為 0（停用）到 3600 秒。較短的 TTL 資料更新鮮但命中率較低；較長的 TTL 命中率較高但有資料過時的風險。請根據底層資料的更新頻率來選擇。

快取鍵參數

預設快取鍵為 method path。當回應因參數而不同時，請將 request parameters（headers、query strings、path parameters、stage variables）加入快取鍵。範例：快取 /products/{id} 自然以 {id} 區分；快取 /search?q=... 應將 q query string 加入快取鍵參數。

快取失效

客戶端可透過傳送 Cache-Control: max-age=0 header 來使快取項目失效，前提是他們擁有 InvalidateCache 權限（呼叫身份的 IAM policy）。否則不論 header 為何，請求都從快取提供。

靜態加密

為合規性啟用快取的靜態加密。此設定不增加延遲，但無法在不重建快取叢集的情況下切換。

CORS——跨來源資源共享與 Preflight

瀏覽器執行 Same-Origin Policy：從 https://app.example.com 提供的頁面無法向 https://api.example.com 發送 XHR／fetch 請求，除非 API 透過 CORS response headers 明確開放。Amazon API Gateway 在不同 API 類型中的 CORS 行為略有差異。

Preflight OPTIONS 請求

對於「非簡單」請求（任何 Content-Type 非 application/x-www-form-urlencoded、multipart/form-data 或 text/plain，或帶有自訂 headers 的請求），瀏覽器會先發出 OPTIONS preflight 請求。伺服器必須回應允許的 origin、methods 和 headers，瀏覽器才會發出真正的請求。

REST API CORS 設定

在 REST API 中，你要為每個 resource 啟用 CORS。Amazon API Gateway 自動建立一個由 mock integration 支撐的 OPTIONS method，回傳 CORS headers：

• Access-Control-Allow-Origin: https://app.example.com（或 *）
• Access-Control-Allow-Methods: GET, POST, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization, X-Api-Key
• Access-Control-Max-Age: 600（快取 preflight 10 分鐘）

對於 Lambda proxy integrations，你的 Lambda 在真正的回應中也必須回傳 Access-Control-Allow-Origin header——mock integration 只負責 preflight。

HTTP API CORS 設定

HTTP API 將 CORS 作為 API 層級（非 per-resource）的一等公民設定。只需設定一次允許的 origins、methods、headers 和 max age，Amazon API Gateway 就會自動處理所有 preflight 和 response header 注入，包含 Lambda proxy 回應。這是 HTTP API 相對於 REST API 最大的易用性優勢之一。

常見 CORS 錯誤模式

• "CORS preflight failed" → OPTIONS method 遺失或回傳錯誤 headers。
• 真正請求中出現 "No 'Access-Control-Allow-Origin' header" → Lambda proxy 沒有回傳該 header。
• "Credentials flag is true, but ACAO is '*'" → 傳送 cookies 時，allow-origin 必須是精確的 origin，不能使用萬用字元。

AWS WAF 整合

AWS WAF 附掛在 REST API 的 regional 和 edge-optimized 端點上（edge-optimized 透過 CloudFront）。WAF 對入站請求評估 Web ACL，其中包含受管規則群組（SQL injection、XSS、bot control）或自訂規則。符合條件的請求在抵達 Amazon API Gateway 之前被封鎖、計數或挑戰。

WAF 目前不直接支援 HTTP API。若使用 HTTP API，請在前方部署 CloudFront 並將 WAF 附掛到 CloudFront distribution。

WAF 防護範圍：

• 透過 AWS Managed Rules 防禦 OWASP Top 10 攻擊模式。
• 透過 IP sets 處理特定 IP 範圍（允許清單／封鎖清單）。
• 速率限制規則（封鎖在 5 分鐘視窗內發送超過 N 次請求的 IP——補充 usage plan throttling 的 per-IP throttle）。
• 依國家的地理限制。
• 透過 AWS Managed Rules Bot Control 處理 Bot 管理訊號。

Custom Domain Names 與 Endpoint 類型

預設的 Amazon API Gateway URL 形如 https://abcd1234.execute-api.us-east-1.amazonaws.com/prod/orders——開發用途尚可，正式環境難以接受。Custom domain names 讓你改用 https://api.example.com/orders。

Endpoint 類型

Amazon API Gateway 為 REST API 提供三種 endpoint 類型，HTTP API 提供兩種：

• Edge-Optimized（僅限 REST）— API 自動由 Amazon API Gateway 管理的 CloudFront distribution 作為前端。全球客戶端透過邊緣快取和在 CloudFront PoPs 的連線終止享有較低延遲。當客戶端分布全球時選擇。
• Regional — 客戶端直接連接到 regional Amazon API Gateway 端點。每次請求成本較低、架構更簡單，且可自行在前方部署 CloudFront。當客戶端主要集中在一個 Region，或需要自帶 CloudFront 以進行更精細控制時選擇。
• Private（僅限 REST）— API 僅可從 VPC 透過 Interface VPC Endpoint（AWS PrivateLink）存取。完全無公開存取。用於內部企業 API。

ACM 憑證——Region 至關重要

Amazon API Gateway 需要 ACM 核發的 TLS 憑證才能提供 custom domain 服務：

• Edge-optimized 端點需要憑證在 us-east-1（因為 CloudFront 一律在此運作）。
• Regional 端點需要憑證在與 API 相同的 Region。

支援匯入第三方憑證，但自動更新僅適用於 ACM 核發的憑證。

Base Path Mapping

單一 custom domain 可根據 URL path prefix 將流量路由到多個 API：api.example.com/orders → Orders API，api.example.com/users → Users API。Base path mappings 在 custom domain 下設定。

OpenAPI 匯入與匯出

Amazon API Gateway 原生支援匯入和匯出 OpenAPI 3.0（及 Swagger 2.0）定義。OpenAPI 文件完整描述你的 API：resources、methods、models、security schemes、integration types、request/response mappings 和 stage variables。搭配 AWS 專屬的 x-amazon-apigateway-* 擴充套件，OpenAPI 文件可在 Amazon API Gateway console、AWS CLI（import-rest-api），或 Infrastructure-as-Code（AWS SAM、CloudFormation、CDK、Terraform）之間雙向轉換。

DVA-C02 上常見的 OpenAPI 擴充套件：

• x-amazon-apigateway-integration — integration 設定（Lambda URI、HTTP URL、VTL templates）。
• x-amazon-apigateway-request-validator — request validation 行為。
• x-amazon-apigateway-authorizer — authorizer 設定。
• x-amazon-apigateway-api-key-source — API key 的讀取來源。
• x-amazon-apigateway-binary-media-types — 二進位處理。

將目前的 API 匯出為 OpenAPI 對於審查、客戶端 SDK 產生，以及在進行重大變更前的備份非常實用。使用 aws apigateway get-export --rest-api-id ... --stage-name prod --export-type oas30 out.json。

可觀測性——CloudWatch Metrics、Access Logs 與 X-Ray

Amazon API Gateway 依 API 和 stage 發出 CloudWatch metrics：

• Count — 請求數量。
• 4XXError / 5XXError — 客戶端 vs 伺服器端錯誤。
• Latency — 包含後端的完整往返時間。
• IntegrationLatency — 僅後端的延遲。
• CacheHitCount / CacheMissCount — 快取效益。

可在每個 stage 啟用 access logs，使用 $context 變數以自訂 JSON 格式寫入 CloudWatch Logs 或 Kinesis Data Firehose。Execution logs（每次請求的詳細診斷追蹤）是獨立的，綁定到日誌等級（INFO 或 ERROR）。

AWS X-Ray tracing 支援 REST API，自 2023 年起亦支援 HTTP API。在 stage 上啟用 active tracing 後，Amazon API Gateway 會新增一個 segment 顯示每個步驟（authorizer、integration、mapping）花費的時間。

DVA-C02 Amazon API Gateway 速查表

DVA-C02 Amazon API Gateway 十大陷阱

1. HTTP API 不支援 API keys 或 usage plans — 商業化場景選 REST API。
2. Lambda proxy vs Lambda non-proxy — proxy 傳遞所有內容，non-proxy 使用 VTL。
3. API keys 單獨使用不等於驗證 — 務必搭配 IAM、Cognito 或 Lambda authorizer。
4. Canary deployments 僅限 REST API — HTTP API 使用 auto-deploy；改用 Lambda alias 加權路由。
5. WAF 附掛在 REST API，不支援 HTTP API — HTTP API 前方部署 CloudFront + WAF。
6. Edge-optimized 憑證必須在 us-east-1 — Regional 憑證必須在 API 所在的 Region。
7. Authorizer 快取在 token 撤銷後仍存在 — TTL 最長 3600 秒，已撤銷的 token 可能繼續有效。
8. 帳戶層級 throttle 由所有 API 共享 — 一個嘈雜的 API 可能使其他 API 飢餓；使用 stage-level throttles。
9. REST API 的 VPC Link 需要 NLB — HTTP API 的 VPC Link v2 支援 ALB／NLB／Cloud Map。
10. CORS preflight 是 mock integration — Lambda proxy 在真正的回應中仍須回傳 Access-Control-Allow-Origin。

Amazon API Gateway 練習題模式

• API 類型選擇：「需要向 10,000 個已連接客戶端發送即時通知」→ WebSocket API。
• Authorizer 選擇：「來自 Okta 的第三方 JWT，需要快取授權決策」→ Lambda TOKEN authorizer 搭配 TTL。
• Integration 選擇：「透過 NLB 連接私有 VPC 內的 ECS 服務」→ REST API + VPC Link。
• 轉換：「在不更改 Lambda 程式碼的情況下，在呼叫 Lambda 前重塑 request body」→ Lambda non-proxy + VTL mapping template。
• 配額：「依客戶層級設定不同的請求限制」→ REST API + Usage Plans + API Keys。
• 安全推出：「將新版本部署到 10% 的流量，觀察後再逐步增加」→ REST API stage 上的 Canary deployment。
• 效能：「讀取密集的端點導致 Lambda 成本飆升」→ 啟用 method-level caching。
• 安全：「在邊緣封鎖 OWASP injection 嘗試」→ AWS WAF 附掛到 REST API（或 HTTP API 透過 CloudFront）。

FAQ——DVA-C02 Amazon API Gateway 高頻問題

Q1：Amazon API Gateway 中 Lambda proxy 和 Lambda non-proxy integration 有什麼差別？

Lambda proxy integration（AWS_PROXY）將整個 HTTP 請求以 JSON event 形式傳給 Lambda，並要求 Lambda 回傳特定格式的 JSON 物件（{statusCode, headers, body, isBase64Encoded}）。不涉及 VTL mapping templates。Lambda non-proxy（AWS，又稱 custom integration）在 request 和 response 兩端都使用 VTL mapping templates，讓你在邊緣重塑 payload，同時讓 Lambda 函式對 HTTP 無感知。95% 的 serverless 應用程式使用 Lambda proxy——更簡單、更快速。當公開 API 契約必須在 Lambda 簽名演進時保持穩定，或需要 per-status-code response shaping 時，才使用 Lambda non-proxy。

Q2：何時應選擇 Amazon API Gateway HTTP API 而非 REST API？

當你的工作負載是直接代理 Lambda 或 HTTP 後端、搭配 JWT 授權（通常是 Cognito 或 OIDC），且不需要 VTL mapping templates、API keys、usage plans、per-method caching、AWS WAF、private APIs 或 JSON schema 的 request validation 時，選擇 HTTP API。HTTP API 每次請求的費用比 REST API 便宜約 70%，延遲也更低，因此是新 serverless API 的正確預設選擇。一旦前述「不需要」清單中的任何需求出現，就切換到 REST API——HTTP API 無法滿足每位客戶的配額或 VTL 需求。

Q3：Amazon API Gateway 的 usage plans 和 API keys 如何執行 throttling 和 quota？

Usage plans 是 REST API 獨有的構件，綁定 throttle（穩態每秒請求數加 burst）、quota（每日／週／月請求數）和關聯的 API stages。你建立 API keys（每位客戶或每個層級一個），將每個 key 與 usage plan 關聯，並在每個 method 上強制 API Key Required。客戶端在 x-api-key header 中傳送 key。Amazon API Gateway 將 key 對應到其方案，並在超出 throttle 或 quota 時回傳 HTTP 429。記住 API keys 不是安全機制——務必搭配 IAM、Cognito 或 Lambda authorizer 進行驗證。

Q4：Amazon API Gateway Lambda authorizer 的快取實際上如何運作？

Lambda authorizers（TOKEN 和 REQUEST 兩種）都支援 TTL 為 0（停用）到 3600 秒的結果快取，預設 300 秒。Amazon API Gateway 以 identity source 為鍵快取回傳的 IAM policy——TOKEN 類型使用 token；REQUEST 類型使用開發者指定的 headers／query／stage variables 集合。快取命中時，authorizer Lambda 不被呼叫，節省延遲和成本。代價是撤銷的 token 或變更的權限在 TTL 到期前仍保持快取狀態。請依安全策略平衡 TTL：一般 API 常用 5 分鐘，敏感 API 用 1 分鐘，需要立即撤銷的場景設為 0。

Q5：Amazon API Gateway 中的 canary deployment 和 stage 有什麼差別？

Stage 是命名的部署目標（例如 dev、qa、prod），有自己的 URL、stage variables、throttle 設定、caching 和 logs。Canary 是附加到現有 stage 的第二個部署，接收可設定比例的流量，通常用於在現有正式 stage 上安全推出新版本。Canary 流量可有自己覆寫的 stage variables（例如指向新的 Lambda alias），並發出帶有 $context.canary 標籤的獨立 CloudWatch metrics。Canary 僅限 REST API；HTTP API 可改用 Lambda alias 加權路由達到類似效果。

Q6：應選擇哪種 endpoint 類型——edge-optimized、regional 還是 private？

Edge-optimized 適用於使用者分布全球的消費者 API——Amazon API Gateway 在前方部署一個受管的 CloudFront distribution，讓客戶端連接到附近的邊緣 PoP。Regional 適用於客戶端集中在一個 Region、AWS 內部的 B2B 整合，或需要自帶 CloudFront 以進行更精細控制的場景。Private 適用於 API 必須僅從 VPC 可達的情況（通常是內部企業 API）——Amazon API Gateway 透過 Interface VPC Endpoint（PrivateLink）暴露它，且沒有公開 DNS 解析。記住 edge-optimized 的 ACM 憑證必須在 us-east-1；regional 憑證在 API 所在的 Region。

Q7：Stage variables 和 mapping templates 在 Amazon API Gateway 中如何互動？

Stage variables 是綁定到 stage 的鍵值對；mapping templates 是 VTL 腳本，在 non-proxy integrations 中轉換 request 和 response。兩者可組合使用：mapping template 可引用 $stageVariables.varName 將 per-stage 值注入後端呼叫。一個常見模式是在 prod stage 設定 stage variable lambdaAlias=LIVE，在 dev stage 設定 lambdaAlias=DEV，然後讓 integration URI 引用 $stageVariables.lambdaAlias。同一個 API 定義，部署一次，根據 stage 路由到不同的 Lambda aliases。在 canary deployments 期間，canary 特定的 stage variables 可覆蓋基礎值，實現安全的漸進推出，而無需更改 API 定義。

Q8：何時應將 AWS WAF 與 Amazon API Gateway 整合？

只要 API 面向公共網際網路且處理使用者提供的資料——幾乎永遠都是——就應整合 AWS WAF。WAF 受管規則群組可封鎖 OWASP Top 10 攻擊（SQL injection、XSS）、惡意 bot、已知濫用 IP 範圍，以及地理限制的 Region。速率限制 WAF 規則與 usage plan throttling 相輔相成，透過限制 per-source-IP 請求速率來對抗暴力破解和 L7 DDoS 攻擊。WAF 直接附掛到 REST API（regional 或 edge-optimized）。HTTP API 不直接支援 WAF，因此在 HTTP API 前方部署 CloudFront 並將 WAF 附掛到 CloudFront distribution。費用為每百萬次請求數美元加上 Web ACL 的每小時費用。

延伸閱讀

• Amazon API Gateway Developer Guide（所有章節）
• AWS Serverless Application Model（SAM）文件，用於基於 CloudFormation 的 Amazon API Gateway 部署
• AWS re:Invent 講座 SVS401 和 API303，涵蓋進階 Amazon API Gateway 模式
• AWS Well-Architected Serverless Applications Lens
• AWS 白皮書：設計 Amazon API Gateway Private APIs 和 Private Integrations 的最佳實踐

掌握 Amazon API Gateway——REST vs HTTP vs WebSocket 的取捨、六種 integration types、VTL mapping templates、五種授權機制（含 Lambda authorizer 快取）、搭配 API keys 的 usage plans、stage variables 和 canary deployments、分層 throttling 模型、method-level caching、CORS preflight 處理、AWS WAF 整合、跨 edge-optimized／regional／private endpoint 類型的 custom domains，以及 OpenAPI 雙向轉換——DVA-C02 上的 Amazon API Gateway 題目就能從令人生畏的邊角知識，轉變為穩定的得分機會。AWS 推出的每一套 serverless 參考架構都以 Amazon API Gateway 作為邊緣入口，因此這些知識在考試日之後仍能持續在日常開發工作中發揮作用。DVA-C02 Amazon API Gateway 題目，加油！