View a markdown version of this page

Connexion à Amazon DocumentDB à l'aide d'un pilote Java MongoDB - Amazon DocumentDB
Configuration de votre projetCréez la chaîne de connexionÉcrivez le code de connexionGérer les exceptions de connexionExécution du codeBonnes pratiques

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Connexion à Amazon DocumentDB à l'aide d'un pilote Java MongoDB

Cette section fournit un guide étape par étape pour la connexion à Amazon DocumentDB à l'aide de pilotes Java. Cela vous permettra de commencer à intégrer DocumentDB dans vos applications Java.

Étape 1 : Configurer votre projet

  1. À l'aide de Maven, créez un projet Java :

    mvn archetype:generate -DgroupId=com.docdb.guide -DartifactId=my-docdb-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

  2. Ajoutez le pilote Java MongoDB en tant que dépendance du projet dans votre fichier « pom.xml » :

    <dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId> 
    <version>5.3.0</version> 
</dependency>

Étape 2 : Création de la chaîne de connexion

La chaîne de connexion Amazon DocumentDB est essentielle pour établir une connexion entre votre application et votre cluster DocumentDB. Cette chaîne encapsule des informations cruciales telles que le point de terminaison du cluster, le port, les détails d'authentification et les différentes options de connexion. Pour créer une chaîne de connexion DocumentDB, vous commencez généralement par le format de base :

"mongodb://username:password@cluster-endpoint:port/?[connection options]"

Vous devrez remplacer « nom d'utilisateur » et « mot de passe » par vos informations d'identification réelles. Vous pouvez trouver le point de terminaison et le numéro de port Console de gestion AWS de votre cluster dans le AWS CLI. Consultez Trouver les points de terminaison d'un cluster pour trouver le point de terminaison de votre cluster. Le port par défaut pour DocumentDB est 27017.

Exemples de chaînes de connexion

  • Établissez une connexion à DocumentDB à l'aide du chiffrement en transit et assurez-vous que les demandes de lecture sont destinées à lire les répliques et à écrire sur le serveur principal :

    "mongodb://username:password@cluster-endpoint:27017/?tls=true& 
   tlsCAFile=global-bundle.pem& 
   readPreference=secondaryPreferred&
   retryWrites=false"

  • Établissement d'une connexion à DocumentDB à l'aide de l'authentification IAM :

    "mongodb://cluster-endpoint:27017/?tls=true& 
   tlsCAFile=global-bundle.pem& 
   readPreference=secondaryPreferred&
   retryWrites=false&
   authSource=%24external&
   authMechanism=MONGODB-AWS"

Les différentes options disponibles pour la chaîne de connexion sont les suivantes :

Certificat TLS

tls=true|false— Cette option active ou désactive le protocole TLS (Transport Layer Security). Par défaut, le chiffrement en transit est activé sur le cluster Amazon DocumentDB. Par conséquent, à moins que TLS ne soit désactivé au niveau du cluster, la valeur de cette option doit être. true

Lorsque vous utilisez TLS, le code doit fournir un certificat SSL lors de la création d'une connexion à un cluster DocumentDB. Téléchargez le certificat requis pour établir la connexion sécurisée au cluster : global-bundle.pem. Il existe deux manières d'utiliser le global-bundle.pem fichier.

  • Option 1 — Extrayez tous les certificats du global-bundle.pem fichier et utilisez l'outil clé de Java pour les stocker dans un .jks fichier qui pourra être utilisé ultérieurement dans le code. Reportez-vous à l'onglet Java Connexion avec TLS activé pour accéder au script qui explique comment procéder.

  • Option 2 — Ajoutez dynamiquement le global-bundle.pem fichier dans le code, créez un keystore en mémoire et utilisez-le SSLContext pour fournir le certificat dans le cadre de la connexion.

Lire à partir de répliques lues

replicaSet=rs0&readPreference=secondaryPreferred— La spécification de ces deux options achemine toutes les demandes de lecture vers les répliques de lecture et les demandes d'écriture vers l'instance principale. L'utilisation replicaSet=rs0 dans la chaîne de connexion permet au pilote MongoDB de conserver une vue automatiquement mise à jour de la topologie du cluster, ce qui permet aux applications de conserver la visibilité des configurations de nœuds actuelles au fur et à mesure que des instances sont ajoutées ou supprimées. Le fait de ne pas fournir ces options ou de les spécifier readPreference=primary envoie toutes les lectures et écritures à l'instance principale. Pour plus d'optionsreadPreference, consultezOptions de préférence de lecture.

Rédiger ses préoccupations et tenir un journal

Le problème d'écriture détermine le niveau d'accusé de réception demandé à la base de données pour les opérations d'écriture. Les pilotes MongoDB fournissent une option permettant de régler les problèmes d'écriture et les fichiers journaux. Amazon DocumentDB ne s'attend pas à ce que vous définissiez Write Concern et journal, et ignore les valeurs envoyées pour w et j (writeConcernetjournal). DocumentDB écrit toujours les données avec writeConcern : majority et journal : true afin que les écritures soient enregistrées de manière durable sur la majorité des nœuds avant d'envoyer un accusé de réception au client.

RetryWrites

retryWrites=false— DocumentDB ne prend pas en charge les écritures réessayables et, par conséquent, cet attribut doit toujours être défini sur. false

Authentification IAM

authSource=%24externalet authMechanism=MONGODB-AWS — Ces deux paramètres sont utilisés pour s'authentifier à l'aide Gestion des identités et des accès AWS de. L'authentification IAM n'est actuellement disponible que dans le cluster basé sur les instances version 5.0. Pour de plus amples informations, veuillez consulter Authentification à l'aide de l'identité IAM.

Pool de connexions

Les options suivantes sont disponibles pour le regroupement de connexions :

  • maxPoolSize— Définit le nombre maximum de connexions pouvant être créées dans le pool. Lorsque toutes les connexions sont utilisées et qu'une nouvelle demande arrive, elle attend qu'une connexion soit disponible. La valeur par défaut pour les pilotes Java MongoDB est 100.

  • minPoolSize— Indique le nombre minimum de connexions qui doivent être maintenues à tout moment dans le pool. La valeur par défaut pour les pilotes Java MongoDB est 0.

  • maxIdleTimeMS— Détermine la durée pendant laquelle une connexion peut rester inactive dans le pool avant d'être fermée et supprimée. La valeur par défaut pour les pilotes Java MongoDB est de 100 millisecondes.

  • waitQueueTimeoutMS— Configure la durée pendant laquelle un thread doit attendre pour qu'une connexion soit disponible lorsque le pool atteint sa taille maximale. Si aucune connexion n'est disponible dans ce délai, une exception est levée. La valeur par défaut pour les pilotes Java MongoDB est de 120 000 millisecondes (2 minutes).

Paramètres de délai d'expiration de connexion

Le timeout est un mécanisme qui limite le temps qu'une opération ou une tentative de connexion peut prendre avant qu'elle ne soit considérée comme un échec. Les paramètres de délai d'attente suivants sont disponibles pour éviter les attentes indéfinies et gérer l'allocation des ressources :

  • connectTimeoutMS— Configure la durée d'attente du pilote pour établir une connexion avec le cluster. La valeur par défaut est de 10 000 millisecondes (10 secondes).

  • socketTimeoutMS— Spécifie la durée pendant laquelle le pilote attendra une réponse du serveur pour une opération de non-écriture. La valeur par défaut est 0 (aucun délai d'attente ou infini).

  • serverSelectionTimeoutMS— Indique combien de temps le pilote devra attendre pour trouver un serveur disponible dans le cluster. La valeur par défaut de ce paramètre est de 30 secondes et est suffisante pour qu'une nouvelle instance principale soit sélectionnée lors du basculement.

Étape 3 : Écrire le code de connexion

L'exemple de code suivant montre comment établir une connexion TLS à Amazon DocumentDB :

public static MongoClient makeDbConnection(String dbName, String DbUserName, String DbPassword,
    String DbClusterEndPoint, String keyStorePass) throws Exception {
    MongoClient connectedClient;
    String connectionOptions = "?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false";
    String connectionUrl = "mongodb://" + DbUserName + ":" + DbPassword + "@" + DbClusterEndPoint + ":27017/" +
        dbName + connectionOptions;

    try {
        KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
        try (FileInputStream fis = new FileInputStream("src/main/resources/certs/truststore.jks")) {
            trustStore.load(fis, keyStorePass.toCharArray());
            TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
            tmf.init(trustStore);

            SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
            sslContext.init(null, tmf.getTrustManagers(), new SecureRandom());
            ConnectionString connectionString = new ConnectionString(connectionUrl);
            MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(connectionString)
                .applyToSslSettings(builder - > {
                    builder.enabled(true);
                    builder.context(sslContext);
                })
                .build();
            connectedClient = MongoClients.create(settings);
        }
        return connectedClient;
    } catch (MongoException e5) {
        throw new RuntimeException(e5);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

Étape 4 : Gérer les exceptions de connexion

Lorsque vous utilisez DocumentDB dans des applications Java, la gestion des exceptions de connexion est cruciale pour maintenir des opérations de base de données robustes et fiables. Bien gérées, ces exceptions permettent non seulement de diagnostiquer rapidement les problèmes, mais également de garantir que votre application peut gérer correctement les interruptions temporaires du réseau ou l'indisponibilité des serveurs, ce qui améliore la stabilité et l'expérience utilisateur. Certaines des exceptions critiques liées à l'établissement de la connexion incluent :

  • MongoException— Une exception générale qui pourrait être émise dans divers scénarios non couverts par des exceptions plus spécifiques. Assurez-vous que cette exception est gérée après toutes les autres exceptions spécifiques car il s'agit d'une exception MongoDB générale.

  • MongoTimeoutException— Émis lorsqu'une opération expire. Par exemple, interroger un point de terminaison de cluster inexistant.

  • MongoSocketException— Publié pour des problèmes liés au réseau. Par exemple, une déconnexion soudaine du réseau pendant une opération.

  • MongoSecurityException— Émis en cas d'échec de l'authentification. Par exemple, se connecter avec des informations d'identification incorrectes.

  • MongoConfigurationException— Émis en cas d'erreur dans la configuration du client. Par exemple, en utilisant une chaîne de connexion non valide.

Étape 5 : Exécution du code

L'exemple de code suivant crée une connexion Amazon DocumentDB et imprime toutes les bases de données :

public static void TestConnection() {
    try (MongoClient mongoClient = makeDbConnection(DATABASE_NAME, DB_USER_NAME, DB_PASSWORD, DB_CLUSTER_ENDPOINT, KEYSTORE_PASSWORD)) {
        List < String > databases = mongoClient.listDatabaseNames().into(new ArrayList < > ());
        System.out.println("Databases: " + databases);
    } catch (MongoException e) {
        System.err.println("MongoDB error: " + e.getMessage());
        throw new RuntimeException(e);
    }
}

Meilleures pratiques en matière de connexion

Les meilleures pratiques à prendre en compte lors de la connexion à Amazon DocumentDB à l'aide d'un pilote Java MongoDB sont les suivantes :

  • Fermez toujours votre MongoClient compte lorsque vous n'avez plus besoin du client pour libérer des ressources.

  • Gérez les exceptions de manière appropriée et implémentez une journalisation des erreurs appropriée.

  • Utilisez des variables d'environnement ou stockez AWS Secrets Manager des informations sensibles telles que les noms d'utilisateur et les mots de passe.