Azure Cosmos DB SQL SDK 连接模式Azure Cosmos DB SQL SDK connectivity modes

适用于: SQL API

客户端连接到 Azure Cosmos DB 的方式对性能有重大影响,尤其是在观察到的客户端延迟方面。How a client connects to Azure Cosmos DB has important performance implications, especially for observed client-side latency. Azure Cosmos DB 提供基于 HTTPS 的简单开放式 RESTful 编程模型(称为网关模式)。Azure Cosmos DB offers a simple, open RESTful programming model over HTTPS called gateway mode. 此外,它还提供了高效的 TCP 协议,该协议在其通信模型中也是 RESTful,并使用 TLS 进行初始身份验证和加密流量(称为直接模式)。Additionally, it offers an efficient TCP protocol, which is also RESTful in its communication model and uses TLS for initial authentication and encrypting traffic, called direct mode.

可用的连接模式Available connectivity modes

两种可用的连接模式为:The two available connectivity modes are:

  • 网关模式Gateway mode

    可在任意 SDK 平台上使用网关模式。Gateway mode is supported on all SDK platforms. 如果应用程序在有严格防火墙限制的企业网络中运行,则网关模式是最佳选择,因为它使用标准 HTTPS 端口与单个 DNS 终结点。If your application runs within a corporate network with strict firewall restrictions, gateway mode is the best choice because it uses the standard HTTPS port and a single DNS endpoint. 但是,对于性能的影响是:每次在 Azure Cosmos DB 中读取或写入数据时,网关模式都涉及到额外的网络跃点。The performance tradeoff, however, is that gateway mode involves an additional network hop every time data is read from or written to Azure Cosmos DB. 在套接字连接数量有限的环境中运行应用程序时,我们也建议使用网关连接模式。We also recommend gateway connection mode when you run applications in environments that have a limited number of socket connections.

    在 Azure Functions 中使用 SDK 时,尤其是在消耗计划中使用时,请注意当前的连接限制When you use the SDK in Azure Functions, particularly in the Consumption plan, be aware of the current limits on connections.

  • 直接模式Direct mode

    直接模式支持通过 TCP 协议进行连接,由于网络跃点更少,因此性能更好。Direct mode supports connectivity through TCP protocol and offers better performance because there are fewer network hops. 应用程序直接连接到后端副本。The application connects directly to the backend replicas. 直接模式目前仅在 .NET 和 Java SDK 平台上受支持。Direct mode is currently only supported on .NET and Java SDK platforms.

    Azure Cosmos SDK 连接模式

这些连接模式实质上限制了数据平面请求(文档读取和写入)从客户端计算机到 Azure Cosmos DB 后端中的分区的路由方式。These connectivity modes essentially condition the route that data plane requests - document reads and writes - take from your client machine to partitions in the Azure Cosmos DB back-end. 直接模式是获得最佳性能的首选选项,它允许客户端直接与 Azure Cosmos DB 后端中的分区建立 TCP 连接,并且在不通过中介的情况下直接发送请求。Direct mode is the preferred option for best performance - it allows your client to open TCP connections directly to partitions in the Azure Cosmos DB back-end and send requests direct ly with no intermediary. 与之相反,在网关模式下,客户端发出的请求会路由到 Azure Cosmos DB 前端中所谓的“网关”服务器,该服务器接下来会将你的请求扇出到 Azure Cosmos DB 后端的相应分区。By contrast, in Gateway mode, requests made by your client are routed to a so-called "Gateway" server in the Azure Cosmos DB front end, which in turn fans out your requests to the appropriate partition(s) in the Azure Cosmos DB back-end.

服务端口范围Service port ranges

使用直接模式时,除了网关端口外,还需确保 10000 到 20000 这个范围的端口处于打开状态,因为 Azure Cosmos DB 使用动态 TCP 端口。When you use direct mode, in addition to the gateway ports, you need to ensure the port range between 10000 and 20000 is open because Azure Cosmos DB uses dynamic TCP ports. 当在专用终结点上使用直接模式时,应打开从 0 到 65535 的整个 TCP 端口范围。When using direct mode on private endpoints, the full range of TCP ports - from 0 to 65535 should be open. 如果这些端口未处于打开状态,你可能会在尝试使用 TCP 协议时收到“503 服务不可用”错误。If these ports aren't open and you try to use the TCP protocol, you might receive a 503 Service Unavailable error.

下表显示了可用于各种 API 的连接模式以及用于每个 API 的服务端口的摘要:The following table shows a summary of the connectivity modes available for various APIs and the service ports used for each API:

连接模式Connection mode 支持的协议Supported protocol 支持的 SDKSupported SDKs API/服务端口API/Service port
网关Gateway HTTPSHTTPS 所有 SDKAll SDKs SQL (443)、MongoDB(10250、10255、10256)、表 (443)、Cassandra (10350)、Graph (443)SQL (443), MongoDB (10250, 10255, 10256), Table (443), Cassandra (10350), Graph (443)
端口 10250 映射到没有异地复制功能的默认 Azure Cosmos DB API for MongoDB 实例。The port 10250 maps to a default Azure Cosmos DB API for MongoDB instance without geo-replication. 而端口 10255 和 10256 映射到具有异地复制功能的实例。Whereas the ports 10255 and 10256 map to the instance that has geo-replication.
直接Direct TCPTCP .NET SDK.NET SDK 使用公共/服务终结点时:端口介于 10000 到 20000 之间When using public/service endpoints: ports in the 10000 through 20000 range
使用专用终结点时:端口介于 0 到 65535 之间When using private endpoints: ports in the 0 through 65535 range

后续步骤Next steps

对于特定 SDK 平台性能优化:For specific SDK platform performance optimizations: