诊断并排查出现 Azure Cosmos DB 消息“请求标头太大”时的问题Diagnose and troubleshoot Azure Cosmos DB request header too large message

引发了“请求标头太大”消息,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 too large and is exceeding the maximum allowed size. 建议使用 SDK 的最新版本。We recommend you to use the latest version of the SDK. 请确保至少使用版本 3.x 或 2.x,因为这些版本会在异常消息中添加标头大小跟踪。Make sure to 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 and solution to the issue in each category.

1.会话标记太大1. Session token too large

原因:Cause:

400 请求错误很可能是由于会话标记太大导致的。400 bad request is most likely caused by the session token being to large. 如果以下陈述属实,则表明会话标记确实太大。If the following statements are true then it confirms that the session token is too large.

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

临时缓解:Temporary mitigation:

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

解决方案:Solution:

  1. 按照 .NET V3.NET V2 性能提示一文中的指南操作,然后对应用程序进行转换,以便使用采用 TCP 协议的直接连接模式。Follow the guidance in .NET V3 or .NET V2 performance tips article and convert the application to use direct connection mode with TCP protocol. 采用 TCP 协议的直接模式对标头大小没有限制(HTTP 协议则具有限制),因此可避免此问题。Direct mode with TCP protocol does not have the header size restriction like the HTTP protocol, so it avoids this issue. 请确保使用最新版本的 SDK,此版本针对不可使用服务互操作时进行的查询操作提供了修复。Make sure to use the latest version of SDK, which has a fix for query operations when the service interop is not available.
  2. 如果采用 TCP 协议的直接连接模式不是适用于你的工作负载的选项,请通过更改客户端一致性级别来缓解此情况。If Direct connection mode with TCP protocol is not 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 not use the session token.

2.继续标记太大2. Continuation token too large

原因:Cause:

400 错误请求发生在使用了继续标记的查询操作中。The 400 bad request is happening 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 性能提示一文中的指南操作,然后对应用程序进行转换,以便使用采用 TCP 协议的直接连接模式。Follow the guidance in .NET V3 or .NET V2 performance tips article and convert the application to use direct connection mode with TCP protocol. 采用 TCP 协议的直接模式对标头大小没有限制(HTTP 协议则具有限制),因此可避免此问题。Direct mode with TCP protocol does not have the header size restriction like the HTTP protocol, so it avoids this issue.
  2. 如果采用 TCP 协议的直接连接模式不是适用于你的工作负载的选项,则尝试设置 ResponseContinuationTokenLimitInKb 选项。If Direct connection mode with TCP protocol is not an option for your workload, then try setting the ResponseContinuationTokenLimitInKb option. 对于 v2,可以在 FeedOptions 中找到此选项;对于 v3,可以在 QueryRequestOptions 中找到此选项。You can find this option in the FeedOptions for v2 or the QueryRequestOptions in v3.

后续步骤Next steps