如何对 API Gateway HTTP 调用错误进行故障排除？

3 分钟阅读

我想对 Amazon API Gateway 调用错误进行故障排除。

解决方法

要对您配置为记录资源和操作请求的 REST API 的 5xx 错误进行故障排除，请使用 AWSSupport-TroubleshootAPIGatewayHttpErrors 运行手册。

或者，您可以手动对 5xx 错误进行故障排除。

**注意：**如果您在运行 AWS 命令行界面 (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：**允许 Automation 代表您执行操作的 IAM 角色的 ARN。如果您未指定角色，则 Automation 将使用启动运行手册的用户的权限。
**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 错误，请参阅 Error handling patterns in Amazon API Gateway and AWS Lambda。

缺少阶段变量的权限

如果您使用阶段变量设置 API Gateway 来调用 Lambda 函数，则可能会收到内部服务器错误。要解决此问题，请参阅我使用阶段变量在 API Gateway 中定义了我的 Lambda 集成。为什么我在调用 API 方法时收到“内部服务器错误”和 500 状态代码？

HTTP 状态代码映射不正确或缺失

要解决此问题，请在 API Gateway 中设置模拟集成。

节流问题

如果大量请求限制了后端服务，则 API Gateway API 可能会返回内部服务器错误。要解决此问题，请激活指数回退和重试机制，然后重试请求。如果您仍然遇到此问题，请检查您的 API Gateway 配额。如果您超出了服务配额，则可以申请增加服务配额。

POST 的 HTTP 方法未定义

对于 Lambda 集成，您必须使用 POST 的 HTTP 方法来完成集成请求。运行以下 AWS CLI 命令 put-integration 以更新方法集成请求：

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。

然后，运行以下 AWS CLI 命令 create-deployment 以部署 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 函数的输出以及 Lambda 授权方的输出，请确保使用正确的 JSON 格式。使用以下示例 JSON 格式。

用于代理集成的 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 无法以网关或代理的身份处理响应时，您会收到 502 状态代码 Bad gateway（网关错误）。要解决此问题，请参阅如何使用 Lambda 代理集成解决来自 API Gateway REST API 的 HTTP 502 错误？

**注意：**API Gateway 在读取来自后端服务的响应时，会使用映射模板在集成响应部分中映射格式。有关详细信息，请参阅 Set up an integration response in 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 状态代码错误进行故障排除

相关信息

相关内容