413 请求实体过大 - TooBigBody

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

问题

客户端应用收到 HTTP 状态代码 413 Request Entity Too Large 和错误代码 protocol.http.TooBigBody ，以此响应 API 调用。

错误消息

客户端应用获取以下响应代码： 

HTTP/1.1 413 Request Entity Too Large

此外，您可能会看到以下错误消息： 

{
   "fault":{
      "faultstring":"Body buffer overflow",
      "detail":{
         "errorcode":"protocol.http.TooBigBody"
      }
   }
}

可能的原因

如果客户端应用作为 HTTP 请求的一部分发送到 Apigee Edge 的载荷大小大于 Apigee Edge 中允许的限制，则会发生此错误。

以下是此错误的可能原因：

原因 说明 适用的问题排查说明
请求载荷大小超出允许的限制 客户端应用作为 HTTP 请求的一部分发送到 Apigee Edge 的载荷大小超过了 Apigee Edge 中允许的限制。 Edge Public 和 Private Cloud 用户
解压缩后，请求载荷大小超出允许的限制 客户端应用作为 HTTP 请求的一部分以压缩格式发送到 Apigee Edge 的载荷大小在被 Apigee Edge 解压缩后超过了允许的限制。 Edge Public 和 Private Cloud 用户

常见诊断步骤

您可以使用以下工具/方法来诊断此错误：

API 监控

如需使用 API 监控功能诊断错误，请执行以下操作：

  1. 以具有 适当角色的用户身份 登录 Apigee Edge 界面。

  2. 切换到您要调查问题的组织

  3. 前往分析 > API 监控 > 调查页面。
  4. 选择您发现错误的具体时间范围。
  5. 您可以选择代理过滤条件来缩小故障代码的范围。
  6. 绘制故障代码与时间的对比图。

  7. 选择包含故障代码 protocol.http.TooBigBody 和状态代码 413 的单元格，如下所示：

  8. 系统会显示有关故障代码 protocol.http.TooBigBody 的信息，如下所示：

  9. 点击查看日志，然后展开失败请求对应的行。然后，在日志窗口中，记下详细信息，如下所示：

    未压缩

    场景 1：以未压缩形式发送的请求载荷

    在“日志”窗口中，记下以下详细信息：

    • 状态代码： 413
    • 故障来源： proxy
    • 故障代码： protocol.http.TooBigBody。
    • 请求长度（字节）： 15360440（约 15 MB）

    如果 Fault Source 的值为 proxy，Fault Code 的值为 protocol.http.TooBigBody，且 Request Length 大于 10 MB，则表示客户端的 HTTP 请求的请求载荷大小大于 Apigee 中允许的限制。

    已压缩

    情形 2：以压缩形式发送的请求载荷

    在日志窗口中，记下以下详细信息：

    • 状态代码： 413
    • 故障来源： proxy
    • 故障代码： protocol.http.TooBigBody。
    • 请求长度（字节）： 15264（约 15 KB）

    如果 Fault Source 的值为 proxy，Fault Code 的值为 protocol.http.TooBigBody，且 Request Length 小于 10 MB，则表示客户端的 HTTP 请求的请求载荷大小（压缩格式）小于允许的限制，但载荷大小（由 Apigee 解压缩后）大于允许的限制。

跟踪记录

如需使用 Trace 工具诊断错误，请执行以下操作：

  1. 启用跟踪会话，并选择以下任一选项：
    • 等待 413 Request Entity Too Large 错误发生或
    • 如果您可以重现该问题，请进行 API 调用并重现 413 Request Entity Too Large 错误

  2. 确保已启用显示所有 FlowInfo。

  3. 选择一个失败的请求，然后检查轨迹。
  4. 前往“Request Received from Client”（收到来自客户端的请求）阶段。

    未压缩

    场景 1：以未压缩形式发送的请求载荷

    请注意以下信息：

    • Content-Encoding：不存在
    • Content-Length： 15360204

    已压缩

    情形 2：以压缩形式发送的请求载荷

    请注意以下信息：

    • Content-Encoding： gzip
    • Content-Length： 14969
    • Content-Type： application/x-gzip
  5. 浏览轨迹的不同阶段，找到发生故障的位置。

  6. 您通常会在“Request Received from Client”（收到来自客户端的请求）阶段之后的流程中发现该错误，如下所示：

  7. 记下轨迹中的错误值。上面的示例跟踪记录显示：
    • 错误： Body buffer overflow
    • error.class: com.apigee.errors.http.user.RequestTooLarge

  8. 前往发送给客户端的响应，并记下跟踪记录中的错误值。以下示例轨迹显示了：

    • 错误： 413 Request Entity Too Large
    • 错误内容： {"fault":{"faultstring":"Body buffer overflow","detail":{"errorcode":"protocol.http.TooBigBody"}}}
  9. 在轨迹中找到 AX（记录的分析数据）阶段，然后点击该阶段。

  10. 在阶段详情部分，向下滚动到读取的变量。

  11. 确定变量 client.received.content.length 的值，该变量表示：
    • 以未压缩格式发送时的实际请求载荷大小，以及
    • 当载荷以压缩格式发送时，Apigee 解压缩后的请求载荷大小。在此场景中，它将始终与允许的限额值 (10 MB) 相同。

    未压缩

    场景 1：未压缩的请求载荷

    client.received.content.length 变量：15360204

    已压缩

    情形 2：以压缩格式请求载荷

    client.received.content.length 变量：10489856

  12. 下表说明了在两种情况下，Apigee 会根据 client.received.content.length 变量的值返回 413 错误的原因：
    场景 client.received.content.length 的值 失败原因
    未压缩格式的请求载荷 ~15 MB 大小 > 允许的上限 10 MB。
    压缩格式的请求载荷 ~10 MB

    解压缩后超出大小限制

NGINX

如需使用 NGINX 访问日志诊断错误，请执行以下操作：

  1. 如果您是私有云用户，则可以使用 NGINX 访问日志来确定有关 HTTP 413 错误的关键信息。

  2. 检查 NGINX 访问日志：

    /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

  3. 搜索以查看特定时间段内（如果问题发生在过去）是否存在任何 413 错误，或者是否仍有请求失败并显示 413。
  4. 如果您发现任何 413 错误，且 X-Apigee-fault-code 与 protocol.http.TooBigBody 的值匹配，请确定 X-Apigee-fault-source 的值。

    未压缩

    场景 1：未压缩格式的请求载荷大小

    上述 NGINX 访问日志中的示例条目具有以下 X-Apigee-fault-code 和 X-Apigee-fault-source 值：

    响应标头 值
    X-Apigee-fault-code protocol.http.TooBigBody
    X-Apigee-fault-sourc policy

    请注意请求长度： 15360440（14.6 MB > 允许的限制）

    已压缩

    情形 2：压缩格式的请求载荷大小

    上述 NGINX 访问日志中的示例条目具有以下 X-Apigee-fault-code 和 X-Apigee-fault-source 值：

    响应标头 值
    X-Apigee-fault-code protocol.http.TooBigBody
    X-Apigee-fault-source policy

    请注意请求长度： 15264（14.9 K < 允许的限制）

    在这种情况下，即使请求长度低于允许的限制，Apigee Edge 仍会返回 413，因为请求可能以压缩格式发送，并且载荷的大小在 Apigee Edge 解压缩后超过了限制。

原因：请求载荷大小超出允许的限制

诊断

  1. 使用 API 监控、Trace 工具或 NGINX 访问日志确定所观测到的错误的故障代码、故障来源和请求载荷大小，如常见诊断步骤（方案 1 [未压缩]）中所述。
  2. 如果 Fault Source 的值为 policy 或 proxy，则表示客户端应用发送到 Apigee 的请求载荷大小大于 Apigee Edge 中允许的限制。
  3. 验证第 1 步中确定的请求载荷大小。
  4. 您还可以按照以下步骤检查实际请求，验证请求载荷大小是否确实超过了 10 MB 的允许限值：
    1. 如果您无法访问客户端应用发出的实际请求，请前往解决方案。
    2. 如果您有权访问客户端应用发出的实际请求，请执行以下步骤：
      1. 验证请求中传递的载荷的大小。
      2. 如果您发现载荷大小超过了 Apigee Edge 中允许的限额，则会导致此问题。

        3. 示例请求：

        curl http://<hostalias>/testtoobigbody -k -X POST -F file=@test15mbfile -v

        在上述示例中，文件 test15mbfile 的大小约为 15 MB。如果您使用的是其他客户端，请获取客户端日志，以了解发送的载荷大小。

分辨率

前往解决方案。

原因：解压缩后，请求载荷大小超出允许的限制

如果请求载荷以压缩格式发送，并且请求标头 Content-Encoding 设置为 gzip, ，则 Apigee 会解压缩请求载荷。在解压缩过程中，如果 Apigee 发现载荷的大小大于 10 MB（即 允许的限额），则会停止进一步解压缩，并立即返回 413 Request Entity Too Large，其中包含错误代码 protocol.http.TooBigBody。

诊断

  1. 使用 API 监控、Trace 工具或 NGINX 访问日志（如常见诊断步骤中的方案 2（压缩）中所述）确定所观测到的错误的故障代码、故障来源和请求载荷大小。
  2. 如果 Fault Source 的值为 policy 或 proxy，则表示客户端应用发送到 Apigee 的请求载荷大小大于 Apigee Edge 中允许的限制。
  3. 验证根据第 1 步确定的请求载荷大小。
    • 如果载荷大小超过允许的 10 MB 限额，则会导致错误。
    • 如果载荷大小小于 10 MB 的允许限值，则可能是以压缩格式传递请求载荷。在这种情况下，请检查压缩请求载荷的未压缩大小。
  4. 您可以使用以下方法之一来验证客户端的请求是否以压缩格式发送，以及解压缩后的大小是否超过允许的限制：

    跟踪记录

    如需使用跟踪工具进行验证，请执行以下操作：

    1. 如果您已捕获失败请求的跟踪记录，请参阅跟踪记录和
        中详述的步骤
      1. 确定 client.received.content.length 变量的值
      2. 验证来自客户端的请求是否包含 Content-Encoding: gzip 标头
    2. 如果 client.received.content.length 变量的值大于 10 MB（即 允许的限制），并且请求标头为 Content-Encoding: gzip，则会导致此错误。

    实际请求

    如需使用实际请求进行验证，请执行以下操作：

    1. 如果您无法访问客户端应用发出的实际请求，请前往解决方案。
    2. 如果您有权访问客户端应用发出的实际请求，请执行以下步骤：
      1. 验证请求中传递的载荷大小以及请求中发送的 Content-Encoding 标头。

      2. 检查载荷的未压缩大小是否超过了 Apigee Edge 中允许的限制

        示例请求：

        curl https://<hostalias>/testtoobigbody -k -X POST -F file=@test15mbfile.gz -H "Content-Encoding: gzip" -v

        在上述示例中，文件 test15mbfile.gz 小于大小限制；但是，未压缩的文件 test15mbfile 的大小约为 15 MB，并且 Content-Encoding 标头为 gzip。

        如果您使用的是其他客户端，请获取客户端日志，以了解发送的载荷大小以及 Content-Encoding 标头是否设置为 gzip。

    消息处理器日志

    如需使用消息处理器日志进行验证，请执行以下操作：

    1. 如果您是私有云用户，则可以使用消息处理器日志来确定有关 HTTP 413 错误的关键信息。

    2. 检查消息处理器日志：

      /opt/apigee/var/log/edge-message-processor/logs/system.log

    3. 搜索以查看在特定时长内（如果问题发生在过去）是否存在任何 413 错误，或者是否仍有任何请求失败并显示 413。

      您可以使用以下搜索字符串：

      grep -ri "chunkCount"

      grep -ri "RequestTooLarge"
    4. 您会看到 system.log 中与以下内容类似的行（TotalRead 和 chunkCount 可能因您的具体情况而异）： 
      2021-07-06 13:29:57,544  NIOThread@1 ERROR HTTP.SERVICE -
  TrackingInputChannel.checkMessageBodyTooLarge()
  : Message is too large.  TotalRead 10489856 chunkCount 2570

2021-07-06 13:29:57,545  NIOThread@1 INFO  HTTP.SERVICE -
  ExceptionHandler.handleException()
  : Exception trace: com.apigee.errors.http.user.RequestTooLarge
  : Body buffer overflow
    5. 在解压缩过程中，一旦消息处理器确定总读取字节数大于 10 MB，就会停止并输出以下行： 
      Message is too large.  TotalRead 10489856 chunkCount 2570

      这意味着请求载荷大小超过 10 MB，当大小开始超出 10 MB 的限制时，Apigee 会抛出错误 RequestTooLarge，并将故障代码设置为 protocol.http.TooBigBody

分辨率

修正尺寸

选项 1 [推荐]：修复客户端应用，使其发送的载荷大小不超过允许的限制

  1. 分析特定客户端发送的请求 / 载荷大小超出限制中定义的允许限制的原因。

  2. 如果不希望出现这种情况，请修改客户端应用，使其发送的请求 / 载荷大小小于允许的限制。

    在上述示例中，您可以通过传递较小的文件（例如 test5mbfile，大小为 5 MB）载荷来解决此问题，如下所示： 

    curl https://<host>/testtoobigbody -k -X POST -F file=@test5mbfile -v
  3. 如果您希望发送的请求/载荷超过允许的限值，请继续查看后续选项。

签名网址格式

选项 2 [推荐]：在 Apigee JavaCallout 中使用签名网址格式

对于大于 10 MB 的载荷，Apigee 建议使用 Apigee JavaCallout 中的签名网址格式，如 GitHub 上的 Edge Callout：签名网址生成器示例所示。

流式

方案 3：使用流式传输

如果您的 API 代理需要处理非常大的请求和/或响应，您可以在 Apigee 中启用流式传输。

CwC

选项 4：使用 CwC 属性来提高缓冲区限制

仅当您无法使用任何推荐选项时，才应使用此选项，因为如果增加默认大小，可能会出现性能问题。

Apigee 提供了一个 CwC 属性，可用于提高请求和响应载荷大小限制。如需了解详情，请参阅 在路由器或消息处理器上设置消息大小限制

限制

Apigee 希望客户端应用和后端服务器不要发送大于 Apigee Edge 限制中针对 Request/response size 记录的允许限制的载荷大小。

  1. 如果您是公有云用户，则请求和响应载荷大小的上限与 Apigee Edge 限制中针对 Request/response size 记录的上限相同。
  2. 如果您是私有云用户 ，则可能修改了请求和响应载荷大小的默认限制（即使不建议这样做）。 您可以按照如何查看当前限制中的说明确定请求载荷大小上限。

如何查看当前限额？

本部分介绍了如何验证消息处理器上的属性 HTTPRequest.body.buffer.limit 是否已更新为新值。

  1. 在消息处理器机器上，在 /opt/apigee/edge-message- processor/conf 目录中搜索属性 HTTPRequest.body.buffer.limit，然后使用以下命令检查已设置的值： 
    grep -ri "HTTPRequest.body.buffer.limit" /opt/apigee/edge-message-processor/conf
  2. 上述命令的示例结果如下所示： 
    /opt/apigee/edge-message-processor/conf/http.properties:HTTPRequest.body.buffer.limit=10m

  3. 在上面的示例输出中，请注意，属性 HTTPRequest.body.buffer.limit 已在 http.properties 中设置为值 10m。

    这表示 Apigee for Private Cloud 中配置的请求载荷大小上限为 10 MB。

如果您仍然需要 Apigee 支持团队提供任何帮助，请参阅必须收集诊断信息。

必须收集的诊断信息

收集以下诊断信息，然后与 Apigee Edge 支持团队联系：

如果您是公共云用户，请提供以下信息：

  • 组织名称
  • 环境名称
  • API 代理名称
  • 用于重现 413 错误的完整 curl 命令
  • API 请求的轨迹文件

如果您是私有云用户，请提供以下信息：

  • 失败请求的完整错误消息
  • 组织名称
  • 环境名称
  • API 代理软件包
  • 失败的 API 请求的轨迹文件
  • 用于重现 413 错误的完整 curl 命令

  • NGINX 访问日志 /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

    其中： ORG、ENV 和 PORT# 会替换为实际值。

  • 消息处理器系统日志 /opt/apigee/var/log/edge-message-processor/logs/system.log