Compartir a través de

Ajuste de las configuraciones de conexión para el SDK de Java v4 de Azure Cosmos DB

  • Artículo

SE APLICA A: NoSQL

Importante

Las sugerencias de rendimiento de este artículo son solo para la versión 4 del SDK de Java de Azure Cosmos DB. Consulte las notas de la versión de la versión 4 del SDK de Java de Azure Cosmos DB, el repositorio de Maven y la guía de solución de problemas de la versión 4 del SDK de Java de Azure Cosmos DB para obtener más información. Si en la actualidad usa una versión anterior a la 4, vea la guía Migración a la versión 4 del SDK de Java de Azure Cosmos DB a fin de obtener ayuda para actualizar a la versión 4.

Azure Cosmos DB es una base de datos distribuida rápida y flexible que se escala sin problemas con una latencia y un rendimiento garantizados. No es necesario realizar cambios de arquitectura importantes ni escribir código complejo para escalar la base de datos con Azure Cosmos DB. Escalar y reducir verticalmente es tan sencillo como realizar una única llamada API o una llamada al método SDK. Sin embargo, debido a que el acceso a Azure Cosmos DB se realiza través de llamadas de red, existen configuraciones de conexión que puede ajustar para conseguir el máximo rendimiento cuando usa la versión 4 del SDK de Java de Azure Cosmos DB.

Configuración de la conexión

Nota

En la versión 4 del SDK de Java de Azure Cosmos DB, el modo directo es la mejor opción para mejorar el rendimiento de la base de datos con la mayoría de las cargas de trabajo.

Para obtener más información sobre las distintas opciones de conectividad, vea el artículo Modos de conectividad.

Modo de conexión directa

El modo de conexión predeterminado del SDK de Java es directo. Las solicitudes del modo directo de Azure Cosmos DB se realizan a través de TCP cuando se usa la versión 4 del SDK de Java de Azure Cosmos DB. Internamente, el modo directo usa una arquitectura especial para administrar dinámicamente los recursos de red y obtener el mejor rendimiento. La arquitectura del lado cliente empleada en el modo directo permite un uso predecible de la red y el acceso multiplexado a las réplicas de Azure Cosmos DB. Para obtener más información sobre la arquitectura, consulte la arquitectura de conexión en modo directo

Puede configurar el modo de conexión en el generador de cliente con los métodos directMode(), tal y como se muestra a continuación. Para configurar el modo directo con la configuración predeterminada, llame al método directMode() sin argumentos. Para personalizar la configuración de conexión del modo directo, pase DirectConnectionConfig a la API directMode().

SDK para Java V4 (Maven com.azure::azure-cosmos) API asincrónica


/* Direct mode, default settings */
CosmosAsyncClient clientDirectDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode()
        .buildAsyncClient();

/* Direct mode, custom settings */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig)
        .buildAsyncClient();

/* Gateway mode, default settings */
CosmosAsyncClient clientGatewayDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode()
        .buildAsyncClient();

/* Gateway mode, custom settings */
GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientGatewayCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode(gatewayConnectionConfig)
        .buildAsyncClient();

/* No connection mode, defaults to Direct mode with default settings */
CosmosAsyncClient clientDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .buildAsyncClient();

Personalización del modo de conexión directa

Si se desea un comportamiento del modo directo no predeterminado, cree una instancia de DirectConnectionConfig y personalice sus propiedades y, a continuación, pase la instancia de la propiedad personalizada al método directMode() en el generador de cliente de Azure Cosmos DB.

Estos valores de configuración controlan el comportamiento de la arquitectura del modo directo subyacente que se describió anteriormente.

Como primer paso, utilice las opciones de configuración recomendadas a continuación. Estas opciones de DirectConnectionConfig son opciones de configuración avanzada que pueden afectar al rendimiento del SDK de maneras inesperadas; se recomienda que los usuarios no las modifiquen a menos que comprendan perfectamente los inconvenientes y sea absolutamente necesario. Póngase en contacto con el equipo de Azure Cosmos DB si tiene problemas con este tema específico.

Opción de configuración Valor predeterminado Recomendado Detalles
idleConnectionTimeout "PT0" (ZERO) "PT0" (ZERO) Esto representa la duración del tiempo de espera de conexión inactiva para una única conexión a un nodo de punto de conexión o back-end (que representa una réplica). El SDK no cierra automáticamente las conexiones inactivas a los nodos de back-end de manera predeterminada.
idleEndpointTimeout "PT1H" "PT1H" Esto representa la duración del tiempo de espera de conexión inactiva para el grupo de conexiones de un nodo de punto de conexión o back-end (que representa una réplica). Si no existen solicitudes entrantes a un punto de conexión o nodo de back-end específico, el SDK cerrará todas las conexiones del grupo de conexiones a ese nodo de punto de conexión o back-end después de 1 hora para ahorrar recursos de red y costos de E/S de manera predeterminada. En el caso del patrón de tráfico disperso o esporádico, se recomienda establecer este valor en un número mayor, como 6, 12 o incluso 24 horas, para que el SDK no tenga que abrir las conexiones con frecuencia. Sin embargo, esto usará los recursos de red y tendrá un mayor número de conexiones abiertas en un momento dado. Si se establece en CERO, se deshabilitará la comprobación del punto de conexión inactivo.
maxConnectionsPerEndpoint "130" "130" Representa el tamaño del límite superior del grupo de conexiones para un nodo de punto de conexión o back-end (que representa una réplica). EL SDK crea conexiones a un nodo de punto de conexión o back-end a petición y en función de las solicitudes simultáneas entrantes. Si es necesario, el SDK creará un máximo de 130 conexiones a un nodo de punto de conexión o back-end de manera predeterminada. (NOTA: eL SDK no crea estas 130 conexiones por adelantado).
maxRequestsPerConnection "30" "30" De esta manera se representa el tamaño del límite superior del número máximo de solicitudes que se pueden poner en cola en una única conexión para un punto de conexión o nodo de back-end específico (que representa una réplica). El SDK pone en cola las solicitudes a una única conexión a un nodo de punto de conexión o back-end a petición y en función de las solicitudes simultáneas entrantes. Si es necesario, el SDK pondrá en cola un máximo de 30 solicitudes a una única conexión para un punto de conexión o nodo back-end específico de manera predeterminada. (NOTA: eL SDK no pone en cola estas 30 solicitudes a una sola conexión por adelantado).
connectTimeout "PT5S" "~PT1S" De esta manera se representa la duración del tiempo de espera del establecimiento de la conexión para establecer una única conexión con un nodo de punto de conexión o back-end. El SDK esperará un máximo de 5 segundos para el establecimiento de la conexión antes de producir un error de manera predeterminada. El establecimiento de conexiones TCP usa el protocolo de enlace de varios pasos, lo que aumenta la latencia del tiempo de establecimiento de la conexión, por lo que se recomienda a los clientes que establezcan este valor según el ancho de banda de la red y la configuración del entorno. NOTA: esta recomendación de ~PT1S es solo para las aplicaciones que se implementan en regiones de las cuentas de Cosmos DB.
networkRequestTimeout "PT5S" "PT5S" Representa la duración del tiempo de espera de la red para una única solicitud. El SDK esperará como máximo esta duración para consumir una respuesta de servicio después de que la solicitud se haya escrito en la conexión de red. EL SDK solo permite valores de entre 1 segundo (mínimo) y 10 segundos (máximo). El establecimiento de un valor demasiado alto puede dar lugar a menos reintentos y reducir las posibilidades de éxito por reintentos.

Modo de conexión de puerta de enlace

Las operaciones del plano de control, como CRUD de base de datos y contenedor siempre usan el modo de puerta de enlace. Incluso cuando el usuario ha configurado el modo directo para las operaciones del plano de datos, las operaciones del plano de control y los metadatos usan la configuración predeterminada del modo de puerta de enlace. Esto se adapta a la mayoría de los usuarios. Sin embargo, los usuarios que quieren usar el modo directo para las operaciones del plano de datos, así como la capacidad de ajuste de los parámetros del modo Puerta de enlace del plano de control, pueden usar el reemplazo directMode() siguiente:

SDK para Java V4 (Maven com.azure::azure-cosmos) API asincrónica


/* Independent customization of Direct mode data plane and Gateway mode control plane */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig,gatewayConnectionConfig)
        .buildAsyncClient();

Personalización del modo de conexión de puerta de enlace

Si quiere un comportamiento del modo de puerta de enlace no predeterminado, cree una instancia de GatewayConnectionConfig y personalice sus propiedades, a continuación, pase la instancia de la propiedad personalizada al método de invalidación directMode() anterior o al método gatewayMode() en el generador de cliente de Azure Cosmos DB.

Como primer paso, utilice las opciones de configuración recomendadas a continuación. Estas opciones de GatewayConnectionConfig son opciones de configuración avanzada que pueden afectar al rendimiento del SDK de manera inesperadas; se recomienda que los usuarios no las modifiquen a menos que comprendan perfectamente los inconvenientes y sea absolutamente necesario. Póngase en contacto con el equipo de Azure Cosmos DB si tiene problemas con este tema específico.

Opción de configuración Valor predeterminado Recomendado Detalles
maxConnectionPoolSize "1000" "1000" Representa el tamaño límite superior del tamaño del grupo de conexiones para el cliente http subyacente, que es el número máximo de conexiones que creará el SDK para las solicitudes que vayan al modo de puerta de enlace. El SDK reutiliza estas conexiones al enviar solicitudes a la puerta de enlace.
idleConnectionTimeout "PT60S" "PT60S" De esta manera se representa la duración del tiempo de espera de conexión inactiva para una única conexión a la puerta de enlace. Pasado este tiempo, la conexión se cerrará automáticamente y se quitará del grupo de conexiones.

Pasos siguientes

Para más información sobre las sugerencias de rendimiento para el SDK de Java, consulte Sugerencias de rendimiento para el SDK de Java v4 de Azure Cosmos DB.

Para más información sobre cómo diseñar la aplicación para escalarla y obtener un alto rendimiento, consulte Partición y escalado en Azure Cosmos DB.

¿Intenta planear la capacidad de una migración a Azure Cosmos DB? Para ello, puede usar información sobre el clúster de bases de datos existente.