诊断 Azure Cosmos DB“请求标头太大”消息并对其进行故障排除Diagnose and troubleshoot Azure Cosmos DB "Request header too large" message

适用于: SQL API

引发了“请求标头太大”消息,并显示 HTTP 错误代码 400。The "Request header too large" message is thrown with an HTTP error code 400. 如果请求标头的大小变得太大以致超过了允许的最大值,则会发生此错误。This error occurs if the size of the request header has grown so large that it exceeds the maximum-allowed size. 建议使用 SDK 的最新版本。We recommend that you use the latest version of the SDK. 至少使用版本 3.x 或 2.x,因为这些版本会在异常消息中添加标头大小跟踪。Use at least version 3.x or 2.x, because these versions add header size tracing to the exception message.

疑难解答步骤Troubleshooting steps

如果会话令牌或延续令牌太大,则会出现“请求标头太大”消息。The "Request header too large" message occurs if the session or the continuation token is too large. 以下各部分介绍了每个类别中的问题原因及其解决方案。The following sections describe the cause of the issue and its solution in each category.

会话令牌太大Session token is too large

原因:Cause:

由于会话令牌太大,可能会出现 400 错误请求。A 400 bad request most likely occurs because the session token is too large. 如果以下表述为真,则会话令牌太大:If the following statements are true, the session token is too large:

  • 此错误发生在其中没有延续令牌的点操作(例如创建、读取、更新等)上。The error occurs on point operations like create, read, and update where there isn't a continuation token.
  • 异常启动时没有对应用程序进行任何更改。The exception started without making any changes to the application. 会话令牌随着容器中分区数量的增加而增加。The session token grows as the number of partitions increases in the container. 分区数量随着数据量的增加或吞吐量的增加而增加。The number of partitions increases as the amount of data increases or if the throughput is increased.

临时缓解:Temporary mitigation:

重启你的客户端应用程序以重置所有会话标记。Restart your client application to reset all the session tokens. 最终,会话令牌将恢复为导致该问题的先前大小。Eventually, the session token will grow back to the previous size that caused the issue. 若要完全避免此问题,请使用下一部分中的解决方案。To avoid this issue completely, use the solution in the next section.

解决方案:Solution:

  1. 请按照 .NET v3.NET v2 性能提示文章中的指南进行操作。Follow the guidance in the .NET v3 or .NET v2 performance tips articles. 将应用程序转换为使用具有传输控制协议 (TCP) 的直接连接模式。Convert the application to use the direct connection mode with the Transmission Control Protocol (TCP). 采用 TCP 协议的直接连接模式对标头大小没有限制(HTTP 协议则有限制),因此可以避免此问题。The direct connection mode with the TCP protocol doesn't have the header size restriction like the HTTP protocol, so it avoids this issue. 请确保使用最新版本的 SDK,此版本针对不可使用服务互操作时进行的查询操作提供了修复。Make sure to use the latest version of the SDK, which has a fix for query operations when the service interop isn't available.
  2. 如果采用 TCP 协议的直接连接模式不是适用于你的工作负载的选项,请通过更改客户端一致性级别来缓解此情况。If the direct connection mode with the TCP protocol isn't an option for your workload, mitigate it by changing the client consistency level. 会话标记仅用于实现会话一致性(这是 Azure Cosmos DB 的默认一致性级别)。The session token is only used for session consistency, which is the default consistency level for Azure Cosmos DB. 其他一致性级别不使用会话令牌。Other consistency levels don't use the session token.

延续令牌太大Continuation token is too large

原因:Cause:

如果延续令牌变得太大或不同的查询具有不同的延续令牌大小,则会在使用延续令牌的查询操作上发生 400 错误请求。The 400 bad request occurs on query operations where the continuation token is used if the continuation token has grown too large or if different queries have different continuation token sizes.

解决方案:Solution:

  1. 请按照 .NET v3.NET v2 性能提示文章中的指南进行操作。Follow the guidance in the .NET v3 or .NET v2 performance tips articles. 将应用程序转换为使用具有 TCP 协议的直接连接模式。Convert the application to use the direct connection mode with the TCP protocol. 采用 TCP 协议的直接连接模式对标头大小没有限制(HTTP 协议则有限制),因此可以避免此问题。The direct connection mode with the TCP protocol doesn't have the header size restriction like the HTTP protocol, so it avoids this issue.
  2. 如果采用 TCP 协议的直接连接模式不是适用于你的工作负载的选项,请设置 ResponseContinuationTokenLimitInKb 选项。If the direct connection mode with the TCP protocol isn't an option for your workload, set the ResponseContinuationTokenLimitInKb option. 可以在 v2 的 FeedOptions 或 v3 的 QueryRequestOptions 中找到此选项。You can find this option in FeedOptions in v2 or QueryRequestOptions in v3.

后续步骤Next steps