Partager via

Paramétrer les configurations de connexion pour le Kit de développement logiciel (SDK) Java Azure Cosmos DB v4

  • S’applique à: ✅ NoSQL

Important

Ces conseils en matière de performances concernent uniquement le SDK Java v4 Azure Cosmos DB. Pour plus d’informations, consultez les notes de publication du Kit de développement logiciel (SDK) Java v4 Azure Cosmos DB, le référentiel Maven et le guide de résolution des problèmes du Kit de développement logiciel (SDK) Java v4 d’Azure Cosmos DB. Si vous utilisez actuellement une version antérieure à la version v4, consultez le guide Migrate to Azure Cosmos DB Java SDK v4 pour obtenir de l’aide sur la mise à niveau vers v4.

Azure Cosmos DB est une base de données distribuée rapide et flexible qui peut être mise à l’échelle en toute transparence avec une latence et un débit garantis. Vous n’avez pas à apporter de modifications d’architecture majeures ou écrire de code complexe pour mettre à l’échelle votre base de données avec Azure Cosmos DB. Augmenter et réduire l'échelle est aussi simple que d'effectuer un appel d'API ou d'effectuer un appel de méthode SDK. Toutefois, étant donné qu’Azure Cosmos DB est accessible via des appels réseau, il existe des configurations de connexion que vous pouvez paramétrer pour obtenir des performances optimales lors de l’utilisation du Kit de développement logiciel (SDK) Java Azure Cosmos DB v4.

Configuration de la connexion

Note

Dans le Kit de développement logiciel (SDK) Java v4 d’Azure Cosmos DB, le mode Direct est le meilleur choix pour améliorer les performances de la base de données avec la plupart des charges de travail.

Pour en savoir plus sur les différentes options de connectivité, consultez l’article sur les modes de connectivité.

Mode de connexion directe

Le mode de connexion par défaut du Kit de développement logiciel (SDK) Java est direct. Les requêtes Azure Cosmos DB en mode direct sont effectuées via TCP lors de l’utilisation du Kit de développement logiciel (SDK) Java Azure Cosmos DB v4. Le mode Direct en interne utilise une architecture spéciale pour gérer dynamiquement les ressources réseau et obtenir les meilleures performances. L’architecture côté client employée en mode Direct permet une utilisation prévisible du réseau et un accès multiplexé aux réplicas Azure Cosmos DB. Pour en savoir plus sur l’architecture, consultez l’architecture de connexion en mode direct

Vous pouvez configurer le mode de connexion dans le générateur client à l’aide de la méthode directMode() comme indiqué ici. Pour configurer le mode direct avec les paramètres par défaut, appelez directMode() la méthode sans arguments. Pour personnaliser les paramètres de connexion en mode direct, passez DirectConnectionConfig à l’API directMode() .

API Async du Kit de développement logiciel (SDK) Java v4 (Maven com.azure::azure-cosmos)


/* 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();

Personnalisation du mode de connexion directe

Si le comportement du mode direct non défini est souhaité, créez une instance DirectConnectionConfig et personnalisez ses propriétés, puis transmettez l’instance de propriété personnalisée à la méthode directMode() dans le générateur de client Azure Cosmos DB.

Ces paramètres de configuration contrôlent le comportement de l’architecture en mode direct sous-jacente décrite précédemment.

Pour commencer, utilisez les paramètres de configuration recommandés suivants ici. Ces options DirectConnectionConfig sont des paramètres de configuration avancés, qui peuvent affecter les performances du Kit de développement logiciel (SDK) de manière inattendue ; nous recommandons aux utilisateurs d’éviter de les modifier, sauf s’ils se sentent à l’aise dans la compréhension des compromis et qu’il est nécessaire. Contactez l’équipe Azure Cosmos DB si vous rencontrez des problèmes sur ce sujet particulier.

Option de configuration Par défaut Recommended Détails
idleConnectionTimeout « PT0 » (ZÉRO) « PT0 » (ZÉRO) Cela représente la durée du délai d’expiration de la connexion inactive pour une connexion unique à un nœud de point de terminaison/back-end (représentant un réplica). Par défaut, le Kit de développement logiciel (SDK) ne ferme pas automatiquement les connexions inactives aux nœuds principaux.
idleEndpointTimeout « PT1H » « PT1H » Cela représente la durée du délai d’expiration de la connexion inactive pour le pool de connexions pour un nœud de point de terminaison/back-end (représentant un réplica). Par défaut, s’il n’existe aucune demande entrante vers un nœud de point de terminaison/back-end spécifique, le SDK ferme toutes les connexions du pool de connexions à ce nœud de point de terminaison/back-end après 1 heure pour économiser les ressources réseau et le coût des E/S. Pour un modèle de trafic clairsemé ou sporadique, nous vous recommandons de définir cette valeur sur un nombre supérieur comme 6 heures, 12 heures ou même 24 heures, afin que le SDK n'ait pas à ouvrir les connexions fréquemment. Toutefois, cela utilise les ressources réseau et aura un nombre plus élevé de connexions conservées ouvertes à tout moment. Si cette valeur est définie sur ZERO, la vérification du point de terminaison inactive est désactivée.
maxConnectionsPerEndpoint "130" "130" Cela représente la limite supérieure du pool de connexions pour un point de terminaison/back-end (représentant une réplique). Le SDK crée des connexions à un nœud de point de terminaison/back-end à la demande et en fonction des demandes simultanées entrantes. Par défaut, si nécessaire, le SDK crée 130 connexions maximales à un nœud de point de terminaison/back-end. (REMARQUE : le SDK ne crée pas ces 130 connexions initialement).
maxRequestsPerConnection 30 30 Cela représente la taille limite supérieure du nombre maximal de requêtes pouvant être mises en file d’attente sur une connexion unique pour un point de terminaison ou nœud de back-end spécifique (représentant un réplica). Le SDK met en file d’attente les demandes vers une connexion unique à un nœud de point de terminaison/back-end à la demande et en fonction des demandes simultanées entrantes. Par défaut, si nécessaire, le Kit de développement logiciel (SDK) met en file d’attente au maximum 30 requêtes vers une connexion unique pour un nœud de point de terminaison/back-end spécifique. (NOTE : Le SDK ne met pas ces 30 requêtes en file d'attente à une seule connexion dès le départ).
délai de connexion « PT5S » « ~PT1S » Cela représente la durée du délai d’expiration de l’établissement de la connexion pour une connexion unique à établir avec un nœud de point de terminaison/back-end. Par défaut, le Kit de développement logiciel (SDK) attend au maximum 5 secondes pour l’établissement de la connexion avant de lever une erreur. L’établissement de connexions TCP utilise une négociation à plusieurs étapes qui augmente la latence du temps d’établissement de la connexion. Par conséquent, les clients sont recommandés de définir cette valeur en fonction de leur bande passante réseau et de leurs paramètres d’environnement. REMARQUE : cette recommandation de ~PT1S concerne uniquement les applications déployées dans les régions colocalisées de leurs comptes Cosmos DB.
networkRequestTimeout « PT5S » « PT5S » Cela représente la durée du délai d’expiration du réseau pour une seule requête. Le Kit de développement logiciel (SDK) attend au maximum pendant cette durée pour utiliser une réponse de service une fois que la requête a été écrite dans la connexion réseau. Le SDK autorise uniquement les valeurs comprises entre 1 seconde (min) et 10 secondes (max). La définition d’une valeur trop élevée peut entraîner moins de nouvelles tentatives et réduire les chances de réussite en effectuant des nouvelles tentatives.

Mode de connexion de passerelle

Les opérations de plan de contrôle telles que la base de données et le CRUD de conteneur utilisent toujours le mode passerelle. Même lorsque l’utilisateur a configuré le mode direct pour les opérations de plan de données, le plan de contrôle et les opérations de méta-données utilisent les paramètres de mode passerelle par défaut. Cela convient à la plupart des utilisateurs. Toutefois, les utilisateurs qui souhaitent opter pour le mode direct pour les opérations de plan de données et de réglage des paramètres du mode de passerelle de plan de contrôle peuvent utiliser la substitution directMode() suivante :

API Async du Kit de développement logiciel (SDK) Java v4 (Maven com.azure::azure-cosmos)


/* 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();

Personnalisation du mode de connexion de la passerelle

Si le comportement du mode passerelle non défini est souhaité, créez une instance GatewayConnectionConfig et personnalisez ses propriétés, puis transmettez l’instance de propriété personnalisée à la méthode de remplacement directMode() ou gatewayMode() dans le générateur de client Azure Cosmos DB.

Pour commencer, utilisez les paramètres de configuration recommandés suivants ici. Ces options GatewayConnectionConfig sont des paramètres de configuration avancés, qui peuvent affecter les performances du Kit de développement logiciel (SDK) de manière inattendue ; nous recommandons aux utilisateurs d’éviter de les modifier, sauf s’ils se sentent à l’aise dans la compréhension des compromis et qu’il est nécessaire. Contactez l’équipe Azure Cosmos DB si vous rencontrez des problèmes sur ce sujet particulier.

Option de configuration Par défaut Recommended Détails
maxConnectionPoolSize "1000" "1000" Cela représente la taille limite supérieure de la taille du pool de connexions pour le client http sous-jacent, qui correspond au nombre maximal de connexions créées par le SDK pour les requêtes en mode passerelle. Le Kit de développement logiciel (SDK) réutilise ces connexions lors de l’envoi de requêtes à la passerelle.
idleConnectionTimeout « PT60S » « PT60S » Cela représente la durée d’expiration du délai d’inactivité de la connexion pour une seule connexion à la passerelle. Après cette période, la connexion est automatiquement fermée et est supprimée du pool de connexions.

Étapes suivantes

Pour en savoir plus sur les conseils de performances pour le SDK Java, consultez Conseils sur les performances pour le SDK Java v4 Azure Cosmos DB.

Pour en savoir plus sur la conception de votre application pour une mise à l’échelle et des hautes performances, consultez Partitionnement et mise à l’échelle dans Azure Cosmos DB.

Vous tentez d’effectuer une planification de la capacité pour une migration vers Azure Cosmos DB ? Vous pouvez utiliser les informations sur votre cluster de bases de données existant pour la planification de la capacité.

  • Last updated on