Connexion à Amazon DocumentDB à l'aide d'un pilote Java MongoDB - Amazon DocumentDB
Configuration de votre projetCréation de la chaîne de connexionÉcrire 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 step-by-step guide de 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 de votre cluster dans le AWS Management Console et via 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

  • Établir une connexion à DocumentDB en utilisant le chiffrement en transit et en s'assurant 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"

  • Etablissement 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 le protocole TLS ne soit désactivé au niveau du cluster, la valeur de cette option doit être. true

Lorsque vous utilisez le protocole 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. Le global-bundle.pem fichier peut être utilisé de deux manières.

  • 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 le script qui montre 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 lors de l'établissement de la connexion.

Lecture à 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 de 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 une visibilité sur les configurations de nœuds actuelles lorsque des instances sont ajoutées ou supprimées. Le fait de ne pas fournir ces options ou de ne pas les spécifier readPreference=primary envoie toutes les lectures et écritures à l'instance principale. Pour plus d'options pourreadPreference, voirOptions de préférence de lecture.

Rédiger ses préoccupations et tenir un journal

Le souci 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 pour régler les problèmes d'écriture et les fichiers journaux. Amazon DocumentDB ne s'attend pas à ce que vous définissiez un souci d'écriture et un journal, et ignore les valeurs envoyées pour w et j (et)writeConcern. journal 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 cet attribut doit donc 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 AWS Identity and Access Management de. L'authentification IAM n'est actuellement disponible que dans la version 5.0 du cluster basé sur une instance. 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, il 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 dans le pool à tout moment. 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 a atteint sa taille maximale. Si aucune connexion n'est disponible dans ce délai, une exception est déclenchée. La valeur par défaut des pilotes Java MongoDB est de 120 000 millisecondes (2 minutes).

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

Le délai d'attente est un mécanisme permettant de limiter 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 temps d'attente indéfinis et gérer l'allocation des ressources :

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

  • socketTimeoutMS— Spécifie le temps pendant lequel le pilote attendra une réponse du serveur pour une opération autre que l'écriture. La valeur par défaut est 0 (aucun délai d'attente ou infini).

  • serverSelectionTimeoutMS— Spécifie le temps que le pilote attendra 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 élue 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 travaillez avec DocumentDB dans des applications Java, la gestion des exceptions de connexion est essentielle 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 aussi de garantir que votre application peut gérer avec élégance 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— Il s'agit d'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 traitée après toutes les autres exceptions spécifiques, car il s'agit d'une exception MongoDB « catch all » générale.

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

  • MongoSocketException— Émis 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, connexion avec des informations d'identification incorrectes.

  • MongoConfigurationException— Publié 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);
    }
}

Bonnes 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 le vôtre MongoClientlorsque vous n'avez plus besoin du client pour libérer des ressources.

  • Gérez les exceptions de manière appropriée et mettez en œuvre 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.