As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Conexão com o Amazon DocumentDB com um driver de Java do MongoDB
Esta seção fornece um step-by-step guia para se conectar ao Amazon DocumentDB usando drivers Java. Isso fará com que você comece a integrar o DocumentDB às suas aplicações de Java.
**Topics**
+ [Etapa 1: configurar o projeto do](#step1-set-up)
+ [Etapa 2: criação da string de conexão](#step2-create-connection-string)
+ [Etapa 3: escrita do código de conexão](#step3-write-connect-code)
+ [Etapa 4: tratamento de exceções de conexão](#step4-handle-connect-exceptions)
+ [Etapa 5: execução do código](#step5-running-code)
+ [Práticas recomendadas de conexão](#java-connect-best-practices)
## Etapa 1: configurar o projeto do
1. Usando o Maven, crie um projeto de java:
```
mvn archetype:generate -DgroupId=com.docdb.guide -DartifactId=my-docdb-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
1. Adicione o driver de Java do MongoDB como uma dependência para o projeto em seu arquivo 'pom.xml':
```
org.mongodb
mongodb-driver-sync
5.3.0
```
## Etapa 2: criação da string de conexão
A string de conexão do Amazon DocumentDB é essencial para estabelecer uma conexão entre sua aplicação e seu cluster do DocumentDB. Essa string encapsula informações cruciais, como o endpoint do cluster, a porta, os detalhes de autenticação e várias opções de conexão. Para criar uma string do DocumentDB, você normalmente começa com o formato básico:
```
"mongodb://{{username}}:{{password}}@cluster-endpoint:port/?[connection options]"
```
Você precisará substituir “nome de usuário” e “senha” por suas credenciais reais. Você pode encontrar o endpoint e o número da porta do seu cluster no Console de gerenciamento da AWS e por meio do AWS CLI. Consulte [Localizar os endpoints de um cluster](db-cluster-endpoints-find.md) para encontrar o endpoint de cluster para o seu cluster. A porta 27017 é a porta padrão para o DocumentDB.
**Exemplos de cadeias de conexão**
+ Estabelecimento de uma conexão com o DocumentDB usando criptografia em trânsito com garantia de que as solicitações de leitura sejam enviadas para réplicas de leitura e gravem no primário:
```
"mongodb://username:password@cluster-endpoint:27017/?tls=true&
tlsCAFile=global-bundle.pem&
readPreference=secondaryPreferred&
retryWrites=false"
```
+ Estabelecimento de uma conexão com o DocumentDB usando a autenticação do IAM:
```
"mongodb://cluster-endpoint:27017/?tls=true&
tlsCAFile=global-bundle.pem&
readPreference=secondaryPreferred&
retryWrites=false&
authSource=%24external&
authMechanism=MONGODB-AWS"
```
As diferentes opções disponíveis para a string de conexão são as seguintes:
+ [Certificado TLS](#connection-string-tls)
+ [Leitura de réplicas de leitura](#connection-string-read-rep)
+ [Preocupação com a gravação e diário](#connection-string-write-journal)
+ [RetryWrites](#connection-string-retry-writes)
+ [Autenticação do IAM](#connection-string-iam-auth)
+ [Grupo de conexões](#connection-string-pool)
+ [Parâmetros de tempo limite da conexão](#connection-string-timeout)
### Certificado TLS
**`tls=true|false`**: esta opção habilita ou desabilita o Transport Layer Security (TLS). Por padrão, a criptografia em trânsito está habilitada no cluster do Amazon DocumentDB e, portanto, a menos que o TLS esteja desabilitado no nível do cluster, o valor dessa opção deve ser `true`.
Ao usar o TLS, o código precisa fornecer um certificado SSL ao criar uma conexão com um cluster do DocumentDB. Baixe o certificado necessário para fazer a conexão segura com o cluster: [https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem). Há duas formas de usar o arquivo `global-bundle.pem`.
+ **Opção 1**: extraia todos os certificados do arquivo `global-bundle.pem` e use a ferramenta de chave do Java para armazená-los em um arquivo `.jks` que possa ser usado posteriormente no código. Consulte a guia Java em [Conectar-se com o TLS habilitado](connect_programmatically.md#connect_programmatically-tls_enabled) para ver o script que mostra como fazer isso.
+ **Opção 2**: adicione dinamicamente o arquivo `global-bundle.pem` no código, crie um armazenamento de chaves na memória e use `SSLContext` para fornecer o certificado como parte da conexão.
### Leitura de réplicas de leitura
**`replicaSet=rs0&readPreference=secondaryPreferred`**: a especificação dessas duas opções encaminha todas as solicitações de leitura para as réplicas de leitura e as solicitações de gravação para a instância primária. O uso de `replicaSet=rs0` na string de conexão permite que o driver do MongoDB mantenha uma visão atualizada automaticamente da topologia do cluster, permitindo que as aplicações mantenham a visibilidade das configurações atuais dos nós à medida que as instâncias são adicionadas ou removidas. Não fornecer essas opções ou especificar `readPreference=primary` envia todas as leituras e gravações para a instância primária. Para obter mais opções para `readPreference`, consulte [Opções de preferência de leitura](how-it-works.md#durability-consistency-isolation).
### Preocupação com a gravação e diário
A preocupação com a gravação determina o nível de reconhecimento solicitado do banco de dados para operações de gravação. Os drivers do MongoDB oferecem uma opção para ajustar os arquivos de preocupação com a gravação e de diário. O Amazon DocumentDB não espera que você defina a preocupação com a gravação e o diário e ignora os valores enviados para `w` e `j` (`writeConcern` e `journal`). O DocumentDB sempre grava dados com `writeConcern`: `majority` e `journal`: `true` para que as gravações sejam realizadas de forma durável na maioria dos nós antes de enviar uma confirmação para o cliente.
### RetryWrites
**`retryWrites=false`**: o DocumentDB não oferece suporte a gravações que possam ser repetidas e, portanto, esse atributo sempre deve ser definido como `false`.
### Autenticação do IAM
**`authSource=%24external`e `authMechanism=MONGODB-AWS`** — Esses dois parâmetros são usados para autenticar usando AWS Identity and Access Management. A autenticação do IAM está disponível no momento somente na versão 5.0 do cluster baseado em instâncias. Para obter mais informações, consulte [Autenticação usando identidade do IAM](iam-identity-auth.md).
### Grupo de conexões
Essas opções estão disponíveis para agrupamento de conexões:
+ **`maxPoolSize`**: define o número máximo de conexões que podem ser criadas no grupo. Quando todas as conexões estão em uso e uma nova solicitação é recebida, ela espera que uma conexão fique disponível. O padrão para drivers de Java do MongoDB é 100.
+ **`minPoolSize`**: indica o número mínimo de conexões que devem ser mantidas no grupo o tempo todo. O padrão para drivers de Java do MongoDB é 0.
+ **`maxIdleTimeMS`**: determina por quanto tempo uma conexão pode permanecer inativa no grupo antes de ser fechada e removida. O padrão para drivers de Java do MongoDB é de 100 milissegundos.
+ **`waitQueueTimeoutMS`**: configura o tempo de espera de um thread para que uma conexão fique disponível quando o grupo estiver em seu tamanho máximo. Se uma conexão não ficar disponível dentro desse período, será lançada uma exceção. O valor padrão para drivers de Java do MongoDB é de 120.000 milissegundos (2 minutos).
### Parâmetros de tempo limite da conexão
O tempo limite é um mecanismo para limitar a quantidade de tempo que uma operação ou tentativa de conexão pode levar até que seja considerada falha. Os parâmetros de tempo limite a seguir estão disponíveis para evitar esperas indefinidas e gerenciar a alocação de recursos:
+ **`connectTimeoutMS`**: configura o tempo de espera do driver para estabelecer uma conexão com o cluster. O padrão é 10.000 milissegundos (10 segundos).
+ **`socketTimeoutMS`**: especifica quanto tempo o driver aguardará por uma resposta do servidor para uma operação de não gravação. O padrão é de 0 (sem tempo limite ou infinito).
+ **`serverSelectionTimeoutMS`**: especifica quanto tempo o driver esperará para encontrar um servidor disponível no cluster. O valor padrão dessa configuração é de 30 segundos e é suficiente para que uma nova instância primária seja eleita durante o failover.
## Etapa 3: escrita do código de conexão
O exemplo de código a seguir mostra como fazer uma conexão de TLS com o Amazon DocumentDB:
+ Ele cria os objetos de Java [https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html) e [`SSLContext`>](https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html).
+ Ele também cria o objeto [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html) ao passá-lo para o objeto [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html). Para fazer a conexão de TLS, você deve usar o objeto `MongoClientSettings` para vincular a `connectionstring` e o `sslcontext`.
+ O uso de [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html) obtém um objeto [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html).
```
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);
}
}
```
## Etapa 4: tratamento de exceções de conexão
Ao trabalhar com o DocumentDB em aplicações de Java, tratar exceções de conexão é crucial para manter operações de banco de dados robustas e confiáveis. Gerenciando adequadamente, essas exceções não apenas ajudam a diagnosticar problemas rapidamente, mas também garantem que sua aplicação possa tratar interrupções temporárias na rede ou indisponibilidade do servidor, melhorando a estabilidade e a experiência do usuário. Algumas das exceções críticas relacionadas ao estabelecimento de conexão incluem:
+ **`MongoException`**: uma exceção geral, pode ser emitida em vários cenários não cobertos por exceções mais específicas. Certifique-se de que essa exceção seja tratada após todas as outras exceções específicas, pois essa é uma exceção geral do MongoDB que captura tudo.
+ **`MongoTimeoutException`**: emitida quando uma operação expira. Por exemplo, ao consultar um endpoint de cluster inexistente.
+ **`MongoSocketException`**: emitida para problemas relacionados à rede. Por exemplo, em uma desconexão repentina da rede durante uma operação.
+ **`MongoSecurityException`**: emitida quando a autenticação falha. Por exemplo, ao conectar-se com credenciais incorretas.
+ **`MongoConfigurationException`**: emitida quando há um erro na configuração do cliente. Por exemplo, com o uso de uma string de conexão inválida.
## Etapa 5: execução do código
O exemplo de código a seguir cria uma conexão do Amazon DocumentDB e imprime todos os bancos de dados:
```
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);
}
}
```
## Práticas recomendadas de conexão
A seguir estão as práticas recomendadas a serem consideradas ao se conectar ao Amazon DocumentDB com um driver de Java do MongoDB:
+ Sempre feche o seu [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html) quando não precisar mais que o cliente libere recursos.
+ Trate as exceções de forma adequada e implemente o log de erros adequado.
+ Use variáveis de ambiente ou AWS Secrets Manager para armazenar informações confidenciais, como nomes de usuário e senhas.