如何使用 API Gateway 解决 API HTTP 504 超时错误？

简短描述

如果集成请求所耗时间超出您的 API Gateway REST API 最大集成超时参数，则 API Gateway 返回 HTTP 504 状态代码。

要解决 API Gateway 中的 504 超时错误，请首先在您的 Amazon CloudWatch 事件日志中确定并验证错误的来源。然后，使用以下一种或多种方法来减少集成请求的运行时系统，直到它们不再超时。

解决方法

确定并验证 CloudWatch 日志中 504 错误的来源

完成以下步骤：

1. 对于 Rest API 和 Websocket API，为 504 错误设置 API Gateway 日志。对于 HTTP API，激活日志记录以将日志写入 CloudWatch 日志。

2. 手动尝试在 API 中重现 504 错误。

3. 激活 API 的访问日志。然后，使用以下参数占位符来诊断错误来源：

   $context.integration.status: The status code returned from an integration. For AWS Lambda proxy integrations, this is the status code that your Lambda function code returns.
   $context.integrationStatus: For Lambda proxy integration, this parameter represents the status code returned from Lambda, not from the backend Lambda function.
   $context.integrationLatency: The integration latency in ms.

   有关更多信息，请参阅数据模型、授权方、映射模板和 CloudWatch 访问日志记录的 $context 变量。

4. 使用以下 CloudWatch Log Insights 查询，从访问日志中筛选“5XX”状态码：

   fields @timestamp, @message, @logStream
   | filter status like '5'
   | sort @timestamp desc
   | display @timestamp,httpMethod,resourcePath,status,extendedRequestId,requestId

5. 在 CloudWatch 控制台中，查看 API Gateway 日志事件，了解收到错误的集成。

6. 在 CloudWatch 日志中追踪请求 ID。如果集成出现超时，则会在“转换后的端点请求正文:”行后出现“因超时而导致执行失败”错误。有关更多信息，请参阅如何在我的 CloudWatch 日志中找到 API Gateway REST API 错误？

7. 使用以下 CloudWatch Log Insights 查询，筛选错误并选择您的 API Gateway 执行日志组：

   fields @timestamp, @message
   |filter @message like "Execution failed due to a timeout error"
   |sort @timestamp desc

8. 要确定错误的来源，请查看后端日志并验证关联的集成端点是否已调用。

9. 确认集成花了多长时间才完成请求过程并响应 API Gateway。

10. 如果未调用集成，则在客户端上实施 API 重试。该错误可能是由 API Gateway 服务中的临时网络故障引起的。
    注意：确保您的应用程序是幂等的，这样在重试 API 请求时可以避免数据冲突。
    -或-
    如果已调用集成但仍返回 504 错误消息，则尝试缩短集成的运行时间。如果是 HTTP API，请尝试增加最大集成请求超时参数。有关更多信息，请参阅 Amazon API Gateway 集成超时限制增加到 29 秒以上。

**注意：**API Gateway REST API 的默认最大集成超时时间为 29 秒。对于 HTTP API，可以将超时配置为最大值 30 秒。

减少集成的运行时系统

采取以下一项或多项操作：

• 确保您的后端集成仅包含 API Gateway 向客户端发送 HTTP 响应所需的逻辑。
• 将任何非依赖逻辑或后处理逻辑移至其他服务，例如 AWS Lambda。
• 如果网络延迟导致 504 错误，则在客户端应用程序上实施重试逻辑。
• 遵循您的 AWS 产品和服务的最佳实践，以提高后端集成性能。
• 设置后端 Lambda 函数的异步调用。

相关信息

API Gateway 中 REST API 的集成

在 API Gateway 中设置 WebSocket API 集成请求

在 API Gateway 中为 HTTP API 创建集成

Amazon API Gateway 配额和重要注意事项