我如何使用 Amazon API Gateway 日誌對 API 問題進行疑難排解？

簡短說明

若要對 API Gateway REST API 或 WebSocket API 進行疑難排解，請啟用執行記錄，然後使用 Amazon CloudWatch Logs 存取您的日誌。請確保已將所有必要的權限附加至 API Gateway 的 AWS Identity and Access Management (IAM) 角色。如需操作說明，請參閱如何啟用 CloudWatch Logs，以對 API Gateway REST API 或 WebSocket API 進行疑難排解？

**注意：**HTTP API 僅支援存取記錄。如需設定這些 API 的記錄詳細資訊，請參閱在 API Gateway 中設定 HTTP API 記錄。

解決方法

啟用記錄後，API Gateway 會自動建立一個名為 API-Gateway-Execution-Logs/{rest-api-id}/{stage-name} 的 CloudWatch 日誌群組。使用此群組進一步對您的問題進行疑難排解。如需更多資訊，請參閱 API Gateway 的 CloudWatch 日誌格式。

檢查授權錯誤

如果您為 API 啟用了 AWS Lambda Authorizer，日誌會顯示請求是否已獲授權，並包含 Authorizer ID 和請求 ID。

已授權日誌範例：

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

未授權日誌範例：

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

如需對此問題進行疑難排解，請參閱為什麼在建立 Lambda Authorizer 後會收到 API Gateway「401 Unauthorized」錯誤？

更新使用計畫組態

Lambda Authorizer 記錄後，API Gateway 會驗證 API 請求的使用計畫。若尚未設定使用計畫，則 API 請求不會計入限流限制。

使用計畫日誌範例：

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

若 API 設定了 API 金鑰但缺少 X-API-Key 標頭，日誌會回傳類似以下訊息的錯誤：

「API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present」

若要解決此問題，請檢查 API 組態。您必須將 API 金鑰與所需使用計畫建立關聯，並在請求中以 X-API-KEY 標頭提供正確值。

如果在標頭中新增正確的 API 金鑰，但 API Gateway 對請求進行限流，日誌會回傳類似以下訊息的錯誤：

「API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt.Limit: 5.00 Burst: 0
Method completed with status: 429」

若要解決此問題，請完成如何使用 API Gateway 對 API 的「429 Too Many Requests」或「Limit Exceeded」錯誤進行疑難排解？中的步驟

請求日誌類型

當您啟用資料追蹤以及錯誤和資訊日誌時，API Gateway 日誌會包含更多詳細資訊，以協助您進行疑難排解。若要找出 API Gateway 請求失敗的位置，請檢視以下日誌類型以取得更多資訊。

注意：對於請求日誌，您必須從 CloudWatch Logs 下拉選單中選擇 Errors and info logs (錯誤和資訊日誌)。然後，為執行日誌啟用資料追蹤。由於資料追蹤可能會記錄敏感資料，因此不建議在生產 API 上啟用資料追蹤。

方法請求日誌

方法請求日誌包含 API 請求收到的詳細資訊，包括請求路徑、查詢參數、請求標頭及請求主體。

方法請求日誌範例：

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

端點請求日誌

端點請求日誌包含 API 請求收到的詳細資訊，包括 URI、請求標頭及請求主體。

端點請求日誌範例：

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

端點請求中的資料會傳送至後端整合以進行進一步處理。

端點回應日誌

端點回應日誌包含後端整合回傳的資料，包括狀態碼、標頭、主體及整合延遲。

端點回應日誌範例：

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

方法回應日誌

方法回應日誌包含轉換後傳送給用戶端的標頭及主體。

方法回應日誌範例：

(####) Method response body after transformations: ...
(####) Method response headers: {...}

**重要：**API Gateway 會將日誌事件限制為 1024 位元組。API Gateway 會截斷大於 1024 位元組的日誌事件 (如請求和回應主體)，然後再將日誌提交至 CloudWatch Logs。

相關資訊

如何對 API Gateway REST API 遺失的 CloudWatch Logs 進行疑難排解？

在 API Gateway 中為 REST API 設定 CloudWatch 記錄

使用 Amazon CloudWatch 指標來監控 REST API 執行

使用 CloudWatch 指標來監控 WebSocket API 執行

使用增強型可觀測性變數對 Amazon API Gateway 進行疑難排解