如何對 API Gateway HTTP 調用錯誤進行疑難排解？

3 分的閱讀內容

我想對 Amazon API Gateway 調用錯誤進行疑難排解。

解決方法

若要對您已設定為記錄資源和作業請求之 REST API 的 5xx 錯誤進行疑難排解，請使用 AWSSupport-TroubleshootAPIGatewayHttpErrors 執行手冊。

或者，您可以手動對 5xx 錯誤進行疑難排解。

**注意：**如果您在執行 AWS Command Line Interface (AWS CLI) 命令時收到錯誤訊息，請參閱對 AWS CLI 錯誤進行疑難排解。此外，請確定您使用的是最新的 AWS CLI 版本。

使用自動化執行手冊對錯誤進行疑難排解

在 AWSSupport-TroubleshootAPIGatewayHttpErrors 執行手冊分析 Amazon CloudWatch Logs 之前，此執行手冊會驗證 API、資源、作業和階段。

授予所需權限

在執行執行手冊之前，請確認您的 AWS Identity and Access Management (IAM) 使用者或角色具有正確的權限。確認您的 IAM 使用者或角色具有存取執行手冊的權限。

此外，執行自動化的 IAM 使用者或承擔的服務角色必須具有以下權限：

apigateway:GET
logs:GetQueryResults
logs:StartQuery
ssm:DescribeAutomationExecutions
ssm:GetAutomationExecution
ssm:DescribeAutomationStepExecutions
ssm:StartAutomationExecution
ssm:DescribeDocument
ssm:GetDocument
ssm:ListDocuments

執行自動化

請完成下列步驟：

開啟 AWSSupport-TroubleshootAPIGatewayHttpErrors 執行手冊。
選擇 Execute automation (執行自動化)。
在輸入參數中，輸入下列內容：
**RestApiId:**您正在進行疑難排解之 API 的 API ID。
**StageName:**已部署階段的名稱。
**ResourcePath:**作業的資源路徑。
**HttpMethod:**設定資源路徑的方法。
**StartTime:**查詢 CloudWatch 日誌的開始日期和時間。格式必須為 yyyy-MM-ddTHH:mm:ss，時區必須為 UTC。
**EndTime:**停止查詢 CloudWatch 日誌的結束日期和時間。格式必須為 yyyy-MM-ddTHH:mm:ss，時區必須為 UTC。
**AccessLogs:**您希望執行手冊分析的存取日誌。
**ExecutionId:**發生錯誤的請求執行 ID。
**AutomationAssumeRole:**允許「自動化功能」代表您執行動作之 IAM 角色的 ARN。如果您未指定角色，則自動化會使用啟動執行手冊之使用者的權限。
**StageName:**已部署階段的名稱。
選擇 Execute (執行)。
查看 Outputs (輸出) 區段以了解詳細結果。
**注意：**即使執行手冊找不到日誌，自動化也能成功完成。

手動對 5xx 狀態碼錯誤進行疑難排解

**注意：**以下解決方法僅適用於 REST API。

開始前，請開啟 Amazon CloudWatch Logs 來對 API Gateway 錯誤進行疑難排解。若要在執行日誌中尋找 5xx 錯誤，請參閱如何在我的 CloudWatch 日誌中尋找 API Gateway REST API 錯誤？API Gateway 5XXError 指標會擷取指定時間段內的伺服器端錯誤數量。

Lambda 函數程式碼中的錯誤

有關與 AWS Lambda 整合的 API 端點 500 錯誤，請參閱 Amazon API Gateway 和 AWS Lambda 中的錯誤處理模式。

缺少階段變數的權限

如果您使用階段變數設定 API Gateway 來調用 Lambda 函數，那麼您可能會收到內部伺服器錯誤。若要解決此問題，請參閱我使用階段變數在 API Gateway 中定義了 Lambda 整合。為什麼在我調用 API 方法時，會收到「內部伺服器錯誤」和 500 狀態碼？

HTTP 狀態碼對應不正確或缺失

若要解決此問題，請在 API Gateway 中設定模擬整合。

限流問題

如果大量請求限制了後端服務，則 API Gateway API 可能會傳回內部伺服器錯誤。若要解決此問題，請啟用指數退避和重試機制，然後再試一次該請求。如果您仍然遇到問題，請檢查您的 API Gateway 配額。如果您超過了服務配額，那麼您可以請求增加服務配額。

POST 的 HTTP 方法未定義

對於 Lambda 整合，您必須使用 POST 的 HTTP 方法進行整合請求。執行以下 put-integration AWS CLI 命令來更新方法整合請求：

aws apigateway put-integration \
    --rest-api-id id \
   --resource-id id \
    --http-method ANY \
    --type AWS_PROXY \
    --integration-http-method POST \
    --uri arn:aws:apigateway:us-east-2:lambda:path//2015-03-31/functions/arn:aws:lambda:us-east-2:account_id:function:helloworld/invocations

**注意：**將 rest-api-id 替換為您的 REST API ID，將 resource-id 替換為您的資源 ID，並將範例 URI 替換為您的 URI。

然後，執行下列 create-deployment AWS CLI 命令來部署 REST API：

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name stage-resource

**注意：**將 rest-api-id 替換為您的 REST API ID，將 stage-resource 替換為您要建立部署資源的「階段」資源。

Lambda 權限

確定 Lambda 函數或 Lambda 授權方的資源型政策包含您 API 調用該函數的權限。

Lambda 函數輸出 JSON 格式問題

如果整合 Lambda 函數的輸出不符合 REST API 指定的 JSON 格式，您將收到錯誤。確定對來自 Lambda 函數 (用於 Proxy 整合) 和 Lambda 授權方的輸出使用正確的 JSON 格式。使用以下 JSON 格式範例。

Proxy 整合的 Lambda 函數範例：

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

Lambda 授權方範例：

{
   "principalId": "user",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      { "Action": "execute-api:Invoke",
        "Effect": "Deny",
        "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
      }
    ]
  }
}

後端承載大小超過 10 MB

後端承載大小的最大 HTTP API 配額為 10 MB。您無法增加大小，因此請確定後端後端大小不超過 10 MB 的配額。

私有端點整合

如果您使用私有 API 端點，那麼您也必須設定 API Gateway 私有整合。

內部服務失敗

如果 AWS 遇到內部服務問題，那麼您可能會收到 500 錯誤。等待問題在 AWS 或 API Gateway 服務中解決，然後使用指數退避重試請求。

502 狀態碼錯誤：錯誤的閘道

當 API Gateway 無法以網關或 Proxy 處理回應時，您會收到 502 狀態碼錯誤的閘道。若要對此問題進行疑難排解，請參閱如何使用 Lambda Proxy 整合解決 API Gateway REST API 中的 HTTP 502 錯誤？

**注意：**當 API Gateway 從後端服務讀取回應時，它會使用對應範本來對應整合回應區段中的格式。如需詳細資訊，請參閱在 API Gateway 中設定整合回應。

503 狀態碼錯誤：服務無法使用

出現 503 狀態碼錯誤是因為後端整合無法使用，所以 API Gateway API 沒有收到回應。

發生此錯誤的原因可能如下：

後端伺服器超出容量，無法處理新的用戶端請求。
後端伺服器正在完成臨時維護。

若要解決此問題，您可以為後端伺服器新增更多資源，並在用戶端上啟用指數退避和重試機制。然後，再試一次該請求。

504 狀態碼錯誤：端點請求已逾時

如果整合請求所花費的時間超過了 API Gateway REST API 最大整合逾時參數，則 API Gateway 將傳回 HTTP 504 狀態碼。若要解決此問題，請參閱如何使用 API Gateway 對 API HTTP 504 逾時錯誤進行疑難排解？

如何對 API Gateway HTTP 調用錯誤進行疑難排解？

解決方法

使用自動化執行手冊對錯誤進行疑難排解

手動對 5xx 狀態碼錯誤進行疑難排解

相關資訊

相關內容