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á.
# Desenvolver com o Amazon DocumentDB
Essas seções abrangem o desenvolvimento com o uso do Amazon DocumentDB.
**Topics**
+ [Conecte-se ao DocumentDB](connect-docdb.md)
+ [Programação com o DocumentDB](program-docdb.md)
# Conecte-se ao Amazon DocumentDB
O Amazon DocumentDB fornece várias opções de conexão, incluindo conexões programáticas usando drivers de MongoDB, conexão de fora de uma VPC por meio de tunelamento SSH ou AWS VPN e ferramentas populares como Studio 3T e DataGrip. O serviço oferece suporte a conexões de conjuntos de réplicas para alta disponibilidade. Para análises e relatórios, é possível se conectar usando drivers de JDBC ou ODBC. Instâncias do EC2 na mesma VPC podem se conectar diretamente aos clusters do DocumentDB. Todas as conexões exigem TLS e credenciais/autenticação da AWS adequadas.
**Topics**
+ [Conexão programática](connect_programmatically.md)
+ [Conectar-se de fora de uma Amazon VPC](connect-from-outside-a-vpc.md)
+ [Conectar-se como um conjunto de réplicas](connect-to-replica-set.md)
+ [Conectar usando o Studio 3T](studio3t.md)
+ [Conectar-se usando o DataGrip](data-grip-connect.md)
+ [Conecte usando o Amazon EC2](connect-ec2.md)
+ [Conecte-se usando o driver JDBC](connect-jdbc.md)
+ [Conecte-se usando o driver ODBC](connect-odbc.md)
# Conectar-se de forma programática ao Amazon DocumentDB
Esta seção contém exemplos de código que demonstram como se conectar ao Amazon DocumentDB (compativel com MongoDB) usando diversas linguagens diferentes. Os exemplos são separados em duas seções com base na conexão com um cluster que tenha o Transport Layer Security (TLS) ativado ou desativado. Por padrão, o TLS fica ativado em clusters do Amazon DocumentDB. No entanto, se quiser, é possível desativar o TLS. Para obter mais informações, consulte [Criptografia de dados em trânsito](security.encryption.ssl.md).
Se você estiver tentando se conectar ao seu Amazon DocumentDB de fora da VPC em que seu cluster reside, consulte [Conectar-se a um cluster do Amazon DocumentDB de fora de uma Amazon VPC](connect-from-outside-a-vpc.md).
Antes de se conectar ao cluster, é necessário saber se o TLS está ativado no cluster. A próxima seção mostra como determinar o valor do parâmetro `tls` do seu cluster usando o Console de gerenciamento da AWS ou a AWS CLI. Depois disso, é possível continuar localizando e aplicando o exemplo de código apropriado.
**Topics**
+ [
## Determinar o valor do parâmetro `tls`
](#connect_programmatically-determine_tls_value)
+ [
## Conectar-se com o TLS habilitado
](#connect_programmatically-tls_enabled)
+ [
## Conectar-se com o TLS desabilitado
](#connect_programmatically-tls_disabled)
## Determinar o valor do parâmetro `tls`
Determinar se o seu cluster tem o TLS ativado é um processo de duas etapas que é possível executar usando o Console de gerenciamento da AWS ou a AWS CLI.
1. **Descubra qual grupo de parâmetros está regendo de seu cluster.**
------
#### [ Using the Console de gerenciamento da AWS ]
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon DocumentDB em [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. No painel de navegação à esquerda, escolha **Clusters**.
1. Na lista de clusters, selecione o nome do cluster.
1. A página resultante exibe os detalhes do cluster selecionado. Selecione a guia **Configuration** (Configuração). Na seção **Configurações e status**, localize o nome do grupo de parâmetros abaixo do **grupo de parâmetros do cluster**.
------
#### [ Using the AWS CLI ]
O código de AWS CLI a seguir determina qual parâmetro está regendo o cluster. Não se esqueça de substituir *`sample-cluster`* pelo nome do cluster.
```
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].[DBClusterIdentifier,DBClusterParameterGroup]'
```
A saída dessa operação é semelhante à seguinte:
```
[
[
"sample-cluster",
"sample-parameter-group"
]
]
```
------
1. **Descubra o valor do parâmetro `tls` no grupo de parâmetros de seu cluster.**
------
#### [ Using the Console de gerenciamento da AWS ]
1. No painel de navegação, escolha **Grupos de parâmetros**.
1. Na janela **Grupos de parâmetros do cluster**, selecione o nome do seu grupo de parâmetros do cluster da Etapa 1d.
1. A página resultante mostra os parâmetros do grupo de parâmetros do cluster. É possível ver o valor do parâmetro `tls` aqui. Para obter informações sobre como modificar esse parâmetro, consulte [Modificando grupos de parâmetros de cluster do Amazon DocumentDB](cluster_parameter_groups-modify.md).
------
#### [ Using the AWS CLI ]
É possível usar o comando da `describe-db-cluster-parameters` AWS CLI para exibir os detalhes dos parâmetros no grupo de parâmetros do cluster.
+ **`--describe-db-cluster-parameters`** — para listar todos os parâmetros em um grupo de parâmetros e seus valores.
+ **`--db-cluster-parameter-group name`** — obrigatório. O nome do grupo de parâmetros de cluster.
Nos exemplos a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
aws docdb describe-db-cluster-parameters \
--db-cluster-parameter-group-name sample-parameter-group
```
A saída dessa operação é semelhante à seguinte:
```
{
"Parameters": [
{
"ParameterName": "profiler_threshold_ms",
"ParameterValue": "100",
"Description": "Operations longer than profiler_threshold_ms will be logged",
"Source": "system",
"ApplyType": "dynamic",
"DataType": "integer",
"AllowedValues": "50-2147483646",
"IsModifiable": true,
"ApplyMethod": "pending-reboot"
},
{
"ParameterName": "tls",
"ParameterValue": "disabled",
"Description": "Config to enable/disable TLS",
"Source": "user",
"ApplyType": "static",
"DataType": "string",
"AllowedValues": "disabled,enabled,fips-140-3",
"IsModifiable": true,
"ApplyMethod": "pending-reboot"
}
]
}
```
**nota**
O Amazon DocumentDB oferece suporte a endpoints FIPS 140-3 a partir dos clusters do Amazon DocumentDB 5.0 (versão do mecanismo 3.0.3727) nas seguintes regiões: ca-central-1, us-west-2, us-east-1, us-east-2, us -gov-east-1, us-gov-west-1.
------
Depois de descobrir o valor do parâmetro `tls`, continue a conexão ao cluster usando um dos exemplos de código nas seções a seguir.
+ [Conectar-se com o TLS habilitado](#connect_programmatically-tls_enabled)
+ [Conectar-se com o TLS desabilitado](#connect_programmatically-tls_disabled)
## Conectar-se com o TLS habilitado
Para ver um exemplo de código para se conectar de forma programática a um cluster do Amazon DocumentDB com o TLS ativado, escolha a guia apropriada para a linguagem que você deseja usar.
Para criptografar dados em trânsito, faça o download da chave pública para Amazon DocumentDB nomeada `global-bundle.pem` usando a operação a seguir.
```
wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
```
Se sua aplicação estiver no Microsoft Windows e exigir um arquivo PKCS7, é possível fazer o download de certificados PKCS7. Esse pacote contém os certificados intermediário e raiz em [https://truststore.pki.rds.amazonaws.com/global/global-bundle.p7b](https://truststore.pki.rds.amazonaws.com/global/global-bundle.p7b).
------
#### [ Python ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Python quando o TLS está ativado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
import pymongo
import sys
##Create a MongoDB client, open a connection to Amazon DocumentDB as a replica set and specify the read preference as secondary preferred
client = pymongo.MongoClient('mongodb://sample-user:password@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
##Specify the database to be used
db = client.sample_database
##Specify the collection to be used
col = db.sample_collection
##Insert a single document
col.insert_one({'hello':'Amazon DocumentDB'})
##Find the document that was previously written
x = col.find_one({'hello':'Amazon DocumentDB'})
##Print the result to the screen
print(x)
##Close the connection
client.close()
```
------
#### [ Node.js ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Node.js quando o TLS está ativado.
**Importante**
Há uma limitação conhecida com os drivers de NodeJS de versão anterior a 6.13.1, que atualmente não têm mais suporte para autenticação de identidades do IAM para o Amazon DocumentDB. Os drivers e ferramentas do Node.js que usam o driver Node.js (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou mais recente do driver de Node.js.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
var MongoClient = require('mongodb').MongoClient
//Create a MongoDB client, open a connection to DocDB; as a replica set,
// and specify the read preference as secondary preferred
var client = MongoClient.connect(
'mongodb://sample-user:password@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/sample-database?tls=true&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false',
{
tlsCAFile: `global-bundle.pem` //Specify the DocDB; cert
},
function(err, client) {
if(err)
throw err;
//Specify the database to be used
db = client.db('sample-database');
//Specify the collection to be used
col = db.collection('sample-collection');
//Insert a single document
col.insertOne({'hello':'Amazon DocumentDB'}, function(err, result){
//Find the document that was previously written
col.findOne({'hello':'Amazon DocumentDB'}, function(err, result){
//Print the result to the screen
console.log(result);
//Close the connection
client.close()
});
});
});
```
------
#### [ PHP ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando PHP quando o TLS está ativado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
"true", "tlsCAFile" => $TLS_DIR ]);
//Specify the database and collection to be used
$col = $client->sampledatabase->samplecollection;
//Insert a single document
$result = $col->insertOne( [ 'hello' => 'Amazon DocumentDB'] );
//Find the document that was previously written
$result = $col->findOne(array('hello' => 'Amazon DocumentDB'));
//Print the result to the screen
print_r($result);
?>
```
------
#### [ Go ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Go quando o TLS está ativado.
**nota**
Desde a versão 1.2.1, o MongoDB Go Driver usará apenas o primeiro certificado de servidor CA encontrado em `sslcertificateauthorityfile`. O código de exemplo abaixo aborda essa limitação anexando manualmente todos os certificados de servidor encontrados em `sslcertificateauthorityfile` a uma configuração TLS personalizada usada durante a criação do cliente.
Nos exemplos a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
package main
import (
"context"
"fmt"
"log"
"time"
"go.mongodb.org/mongo-driver/bson"
"go.mongodb.org/mongo-driver/mongo"
"go.mongodb.org/mongo-driver/mongo/options"
"io/ioutil"
"crypto/tls"
"crypto/x509"
"errors"
)
const (
// Path to the AWS CA file
caFilePath = "global-bundle.pem"
// Timeout operations after N seconds
connectTimeout = 5
queryTimeout = 30
username = "sample-user"
password = "password"
clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017"
// Which instances to read from
readPreference = "secondaryPreferred"
connectionStringTemplate = "mongodb://%s:%s@%s/sample-database?tls=true&replicaSet=rs0&readpreference=%s"
)
func main() {
connectionURI := fmt.Sprintf(connectionStringTemplate, username, password, clusterEndpoint, readPreference)
tlsConfig, err := getCustomTLSConfig(caFilePath)
if err != nil {
log.Fatalf("Failed getting TLS configuration: %v", err)
}
client, err := mongo.NewClient(options.Client().ApplyURI(connectionURI).SetTLSConfig(tlsConfig))
if err != nil {
log.Fatalf("Failed to create client: %v", err)
}
ctx, cancel := context.WithTimeout(context.Background(), connectTimeout*time.Second)
defer cancel()
err = client.Connect(ctx)
if err != nil {
log.Fatalf("Failed to connect to cluster: %v", err)
}
// Force a connection to verify our connection string
err = client.Ping(ctx, nil)
if err != nil {
log.Fatalf("Failed to ping cluster: %v", err)
}
fmt.Println("Connected to DocumentDB!")
collection := client.Database("sample-database").Collection("sample-collection")
ctx, cancel = context.WithTimeout(context.Background(), queryTimeout*time.Second)
defer cancel()
res, err := collection.InsertOne(ctx, bson.M{"name": "pi", "value": 3.14159})
if err != nil {
log.Fatalf("Failed to insert document: %v", err)
}
id := res.InsertedID
log.Printf("Inserted document ID: %s", id)
ctx, cancel = context.WithTimeout(context.Background(), queryTimeout*time.Second)
defer cancel()
cur, err := collection.Find(ctx, bson.D{})
if err != nil {
log.Fatalf("Failed to run find query: %v", err)
}
defer cur.Close(ctx)
for cur.Next(ctx) {
var result bson.M
err := cur.Decode(&result)
log.Printf("Returned: %v", result)
if err != nil {
log.Fatal(err)
}
}
if err := cur.Err(); err != nil {
log.Fatal(err)
}
}
func getCustomTLSConfig(caFile string) (*tls.Config, error) {
tlsConfig := new(tls.Config)
certs, err := ioutil.ReadFile(caFile)
if err != nil {
return tlsConfig, err
}
tlsConfig.RootCAs = x509.NewCertPool()
ok := tlsConfig.RootCAs.AppendCertsFromPEM(certs)
if !ok {
return tlsConfig, errors.New("Failed parsing pem file")
}
return tlsConfig, nil
```
------
#### [ Java ]
Ao se conectar a um cluster do Amazon DocumentDB com o TLS habilitado em uma aplicação Java, o programa deve usar o arquivo da autoridade de certificação fornecido pela AWS para validar a conexão. Para usar o certificado da Amazon RDS CA, faça o seguinte:
1. Faça o download do arquivo da Amazon RDS CA do [https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem) .
1. Crie um armazenamento confiável com o certificado da CA contido no arquivo executando os seguintes comandos. Certifique-se de alterar *truststore-password* para algo diferente. Se estiver acessando um armazenamento confiável que contenha o certificado da CA antigo (`rds-ca-2015-root.pem`) e o novo (`rds-ca-2019-root.pem`), é possível importar o pacote de certificados para o armazenamento confiável.
Veja a seguir um exemplo de script shell que importa o pacote de certificados para um armazenamento confiável em um sistema operacional Linux. Nos exemplos a seguir, substitua cada *espaço reservado ao usuário* por suas próprias informações. Mais notavelmente, sempre que o diretório de exemplo "*mydir*" estiver localizado no script, substitua-o por um diretório que você criou para essa tarefa.
```
mydir=/tmp/certs
truststore=${mydir}/rds-truststore.jks
storepassword=truststore-password
curl -sS "https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem" > ${mydir}/global-bundle.pem
awk 'split_after == 1 {n++;split_after=0} /-----END CERTIFICATE-----/ {split_after=1}{print > "rds-ca-" n ".pem"}' < ${mydir}/global-bundle.pem
for CERT in rds-ca-*; do
alias=$(openssl x509 -noout -text -in $CERT | perl -ne 'next unless /Subject:/; s/.*(CN=|CN = )//; print')
echo "Importing $alias"
keytool -import -file ${CERT} -alias "${alias}" -storepass ${storepassword} -keystore ${truststore} -noprompt
rm $CERT
done
rm ${mydir}/global-bundle.pem
echo "Trust store content is: "
keytool -list -v -keystore "$truststore" -storepass ${storepassword} | grep Alias | cut -d " " -f3- | while read alias
do
expiry=`keytool -list -v -keystore "$truststore" -storepass ${storepassword} -alias "${alias}" | grep Valid | perl -ne 'if(/until: (.*?)\n/) { print "$1\n"; }'`
echo " Certificate ${alias} expires in '$expiry'"
done
```
Veja a seguir um exemplo de script do shell que importa o pacote de certificados em um armazenamento de confiança no macOS.
```
mydir=/tmp/certs
truststore=${mydir}/rds-truststore.jks
storepassword=truststore-password
curl -sS "https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem" > ${mydir}/global-bundle.pem
split -p "-----BEGIN CERTIFICATE-----" ${mydir}/global-bundle.pem rds-ca-
for CERT in rds-ca-*; do
alias=$(openssl x509 -noout -text -in $CERT | perl -ne 'next unless /Subject:/; s/.*(CN=|CN = )//; print')
echo "Importing $alias"
keytool -import -file ${CERT} -alias "${alias}" -storepass ${storepassword} -keystore ${truststore} -noprompt
rm $CERT
done
rm ${mydir}/global-bundle.pem
echo "Trust store content is: "
keytool -list -v -keystore "$truststore" -storepass ${storepassword} | grep Alias | cut -d " " -f3- | while read alias
do
expiry=`keytool -list -v -keystore "$truststore" -storepass ${storepassword} -alias "${alias}" | grep Valid | perl -ne 'if(/until: (.*?)\n/) { print "$1\n"; }'`
echo " Certificate ${alias} expires in '$expiry'"
done
```
1. Use o `keystore` no seu programa definindo as seguintes propriedades do sistema na aplicação antes de estabelecer uma conexão com o cluster do Amazon DocumentDB.
```
javax.net.ssl.trustStore: truststore
javax.net.ssl.trustStorePassword: truststore-password;
```
1. O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Java quando o TLS está ativado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
package com.example.documentdb;
import com.mongodb.client.*;
import org.bson.Document;
public final class Test {
private Test() {
}
public static void main(String[] args) {
String template = "mongodb://%s:%s@%s/sample-database?ssl=true&replicaSet=rs0&readpreference=%s";
String username = "sample-user";
String password = "password";
String clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017";
String readPreference = "secondaryPreferred";
String connectionString = String.format(template, username, password, clusterEndpoint, readPreference);
String truststore = "truststore";
String truststorePassword = "truststore-password";
System.setProperty("javax.net.ssl.trustStore", truststore);
System.setProperty("javax.net.ssl.trustStorePassword", truststorePassword);
MongoClient mongoClient = MongoClients.create(connectionString);
MongoDatabase testDB = mongoClient.getDatabase("sample-database");
MongoCollection numbersCollection = testDB.getCollection("sample-collection");
Document doc = new Document("name", "pi").append("value", 3.14159);
numbersCollection.insertOne(doc);
MongoCursor cursor = numbersCollection.find().iterator();
try {
while (cursor.hasNext()) {
System.out.println(cursor.next().toJson());
}
} finally {
cursor.close();
}
}
}
```
------
#### [ C\$1 / .NET ]
O código a seguir demonstra como conectar-se ao Amazon DocumentDB usando C\$1 / .NET quando o TLS está habilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
using System;
using System.Text;
using System.Linq;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Net.Security;
using MongoDB.Driver;
using MongoDB.Bson;
namespace DocDB
{
class Program
{
static void Main(string[] args)
{
string template = "mongodb://{0}:{1}@{2}/sampledatabase?tls=true&replicaSet=rs0&readpreference={3}";
string username = "sample-user";
string password = "password";
string readPreference = "secondaryPreferred";
string clusterEndpoint="sample-cluster.node.us-east-1.docdb.amazonaws.com:27017";
string connectionString = String.Format(template, username, password, clusterEndpoint, readPreference);
string pathToCAFile = "";
// ADD CA certificate to local trust store
// DO this once - Maybe when your service starts
X509Store localTrustStore = new X509Store(StoreName.Root);
X509Certificate2Collection certificateCollection = new X509Certificate2Collection();
certificateCollection.Import(pathToCAFile);
try
{
localTrustStore.Open(OpenFlags.ReadWrite);
localTrustStore.AddRange(certificateCollection);
}
catch (Exception ex)
{
Console.WriteLine("Root certificate import failed: " + ex.Message);
throw;
}
finally
{
localTrustStore.Close();
}
var settings = MongoClientSettings.FromUrl(new MongoUrl(connectionString));
var client = new MongoClient(settings);
var database = client.GetDatabase("sampledatabase");
var collection = database.GetCollection("samplecollection");
var docToInsert = new BsonDocument { { "pi", 3.14159 } };
collection.InsertOne(docToInsert);
}
}
}
```
------
#### [ MongoDB Shell ]
O código a seguir demonstra como se conectar e consultar o Amazon DocumentDB usando a versão mais recente, mongosh, ou a versão anterior do shell do mongo, quando o TLS está habilitado.
**Conecte-se ao Amazon DocumentDB com o mongosh**.
**Importante**
Há uma limitação conhecida com os drivers de NodeJS de versão anterior a 6.13.1, que atualmente não têm mais suporte para autenticação de identidades do IAM para o Amazon DocumentDB. Os drivers e ferramentas do Node.js que usam o driver Node.js (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou mais recente do driver de Node.js.
Nos exemplos a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
mongosh --tls --host cluster-end-point:27017 --tlsCAFile global-bundle.pem --username sample-user --password password --retryWrites false
```
**Conecte-se ao Amazon DocumentDB com a versão anterior do shell do mongo**
Se você usa o IAM, deve usar uma versão anterior do shell mongo. Insira uma das opções de comando a seguir:
```
mongo --ssl --host cluster-end-point:27017 --sslCAFile global-bundle.pem --username sample-user --password password
```
Se você estiver usando uma versão igual ou superior a 4.2, use o código a seguir para conectar. Não há suporte para gravações com novas tentativas no Amazon DocumentDB. Se você estiver usando o shell mongo (não mongosh), não inclua o comando `retryWrites=false` em nenhuma string de código. Por padrão, as gravações que podem ser repetidas estão desabilitadas. A inclusão de `retryWrites=false` pode causar falha nos comandos de leitura normais.
```
mongo --tls --host cluster-end-point:27017 --tlsCAFile global-bundle.pem --username sample-user --password password
```
**Teste a conexão**
1. Insira um único documento.
```
db.myTestCollection.insertOne({'hello':'Amazon DocumentDB'})
```
1. Encontre o documento inserido anteriormente.
```
db.myTestCollection.find({'hello':'Amazon DocumentDB'})
```
------
#### [ R ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB com R usando o mongolite ([https://jeroen.github.io/mongolite/](https://jeroen.github.io/mongolite/)) quando o TLS está habilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
#Include the mongolite library.
library(mongolite)
mongourl <- paste("mongodb://sample-user:password@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/test2?ssl=true&",
"readPreference=secondaryPreferred&replicaSet=rs0", sep="")
#Create a MongoDB client, open a connection to Amazon DocumentDB as a replica
# set and specify the read preference as secondary preferred
client <- mongo(url = mongourl, options = ssl_options(weak_cert_validation = F, ca =""))
#Insert a single document
str <- c('{"hello" : "Amazon DocumentDB"}')
client$insert(str)
#Find the document that was previously written
client$find()
```
------
#### [ Ruby ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB com o Ruby quando o TLS está habilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
require 'mongo'
require 'neatjson'
require 'json'
client_host = 'mongodb://sample-cluster.node.us-east-1.docdb.amazonaws.com:27017'
client_options = {
database: 'test',
replica_set: 'rs0',
read: {:secondary_preferred => 1},
user: 'sample-user',
password: 'password',
ssl: true,
ssl_verify: true,
ssl_ca_cert: 'PATH/global-bundle.pem',
retry_writes: false
}
begin
##Create a MongoDB client, open a connection to Amazon DocumentDB as a
## replica set and specify the read preference as secondary preferred
client = Mongo::Client.new(client_host, client_options)
##Insert a single document
x = client[:test].insert_one({"hello":"Amazon DocumentDB"})
##Find the document that was previously written
result = client[:test].find()
#Print the document
result.each do |document|
puts JSON.neat_generate(document)
end
end
#Close the connection
client.close
```
------
## Conectar-se com o TLS desabilitado
Para ver um exemplo de código para se conectar de forma programática a um cluster do Amazon DocumentDB com o TLS desativado, escolha a guia para a linguagem que você deseja usar.
------
#### [ Python ]
O código a seguir demonstra como conectar-se ao Amazon DocumentDB usando Python quando o TLS está desabilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
## Create a MongoDB client, open a connection to Amazon DocumentDB as a replica set and specify the read preference as secondary preferred
import pymongo
import sys
client = pymongo.MongoClient('mongodb://sample-user:password@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
##Specify the database to be used
db = client.sample_database
##Specify the collection to be used
col = db.sample_collection
##Insert a single document
col.insert_one({'hello':'Amazon DocumentDB'})
##Find the document that was previously written
x = col.find_one({'hello':'Amazon DocumentDB'})
##Print the result to the screen
print(x)
##Close the connection
client.close()
```
------
#### [ Node.js ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Node.js quando o TLS está desabilitado.
**Importante**
Há uma limitação conhecida com os drivers de NodeJS de versão anterior a 6.13.1, que atualmente não têm mais suporte para autenticação de identidades do IAM para o Amazon DocumentDB. Os drivers e ferramentas do Node.js que usam o driver Node.js (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou mais recente do driver de Node.js.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
var MongoClient = require('mongodb').MongoClient;
//Create a MongoDB client, open a connection to Amazon DocumentDB as a replica set,
// and specify the read preference as secondary preferred
var client = MongoClient.connect(
'mongodb://sample-user:password@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/sample-database?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false',
{
useNewUrlParser: true
},
function(err, client) {
if(err)
throw err;
//Specify the database to be used
db = client.db('sample-database');
//Specify the collection to be used
col = db.collection('sample-collection');
//Insert a single document
col.insertOne({'hello':'Amazon DocumentDB'}, function(err, result){
//Find the document that was previously written
col.findOne({'hello':'Amazon DocumentDB'}, function(err, result){
//Print the result to the screen
console.log(result);
//Close the connection
client.close()
});
});
});
```
------
#### [ PHP ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando PHP quando o TLS está desabilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
sampledatabase->samplecollection;
//Insert a single document
$result = $col->insertOne( [ 'hello' => 'Amazon DocumentDB'] );
//Find the document that was previously written
$result = $col->findOne(array('hello' => 'Amazon DocumentDB'));
//Print the result to the screen
print_r($result);
?>
```
------
#### [ Go ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Go quando o TLS está desabilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
package main
import (
"context"
"fmt"
"log"
"time"
"go.mongodb.org/mongo-driver/bson"
"go.mongodb.org/mongo-driver/mongo"
"go.mongodb.org/mongo-driver/mongo/options"
)
const (
// Timeout operations after N seconds
connectTimeout = 5
queryTimeout = 30
username = "sample-user"
password = "password"
clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017"
// Which instances to read from
readPreference = "secondaryPreferred"
connectionStringTemplate = "mongodb://%s:%s@%s/sample-database?replicaSet=rs0&readpreference=%s"
)
func main() {
connectionURI := fmt.Sprintf(connectionStringTemplate, username, password, clusterEndpoint, readPreference)
client, err := mongo.NewClient(options.Client().ApplyURI(connectionURI))
if err != nil {
log.Fatalf("Failed to create client: %v", err)
}
ctx, cancel := context.WithTimeout(context.Background(), connectTimeout*time.Second)
defer cancel()
err = client.Connect(ctx)
if err != nil {
log.Fatalf("Failed to connect to cluster: %v", err)
}
// Force a connection to verify our connection string
err = client.Ping(ctx, nil)
if err != nil {
log.Fatalf("Failed to ping cluster: %v", err)
}
fmt.Println("Connected to DocumentDB!")
collection := client.Database("sample-database").Collection("sample-collection")
ctx, cancel = context.WithTimeout(context.Background(), queryTimeout*time.Second)
defer cancel()
res, err := collection.InsertOne(ctx, bson.M{"name": "pi", "value": 3.14159})
if err != nil {
log.Fatalf("Failed to insert document: %v", err)
}
id := res.InsertedID
log.Printf("Inserted document ID: %s", id)
ctx, cancel = context.WithTimeout(context.Background(), queryTimeout*time.Second)
defer cancel()
cur, err := collection.Find(ctx, bson.D{})
if err != nil {
log.Fatalf("Failed to run find query: %v", err)
}
defer cur.Close(ctx)
for cur.Next(ctx) {
var result bson.M
err := cur.Decode(&result)
log.Printf("Returned: %v", result)
if err != nil {
log.Fatal(err)
}
}
if err := cur.Err(); err != nil {
log.Fatal(err)
}
}
```
------
#### [ Java ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando Java quando o TLS está desabilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
package com.example.documentdb;
import com.mongodb.MongoClient;
import com.mongodb.MongoClientURI;
import com.mongodb.ServerAddress;
import com.mongodb.MongoException;
import com.mongodb.client.MongoCursor;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.MongoCollection;
import org.bson.Document;
public final class Main {
private Main() {
}
public static void main(String[] args) {
String template = "mongodb://%s:%s@%s/sample-database?replicaSet=rs0&readpreference=%s";
String username = "sample-user";
String password = "password";
String clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017";
String readPreference = "secondaryPreferred";
String connectionString = String.format(template, username, password, clusterEndpoint, readPreference);
MongoClientURI clientURI = new MongoClientURI(connectionString);
MongoClient mongoClient = new MongoClient(clientURI);
MongoDatabase testDB = mongoClient.getDatabase("sample-database");
MongoCollection numbersCollection = testDB.getCollection("sample-collection");
Document doc = new Document("name", "pi").append("value", 3.14159);
numbersCollection.insertOne(doc);
MongoCursor cursor = numbersCollection.find().iterator();
try {
while (cursor.hasNext()) {
System.out.println(cursor.next().toJson());
}
} finally {
cursor.close();
}
}
}
```
------
#### [ C\$1 / .NET ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB usando C\$1/.NET quando o TLS está desabilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
using System;
using System.Text;
using System.Linq;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Net.Security;
using MongoDB.Driver;
using MongoDB.Bson;
namespace CSharpSample
{
class Program
{
static void Main(string[] args)
{
string template = "mongodb://{0}:{1}@{2}/sampledatabase?replicaSet=rs0&readpreference={3}";
string username = "sample-user";
string password = "password";
string clusterEndpoint = "sample-cluster.node.us-east-1.docdb.amazonaws.com:27017";
string readPreference = "secondaryPreferred";
string connectionString = String.Format(template, username, password, clusterEndpoint, readPreference);
var settings = MongoClientSettings.FromUrl(new MongoUrl(connectionString));
var client = new MongoClient(settings);
var database = client.GetDatabase("sampledatabase");
var collection = database.GetCollection("samplecollection");
var docToInsert = new BsonDocument { { "pi", 3.14159 } };
collection.InsertOne(docToInsert);
}
}
}
```
------
#### [ MongoDB Shell ]
O código a seguir demonstra como se conectar e consultar o Amazon DocumentDB usando a versão mais recente, mongosh, ou a versão anterior do shell do mongo, quando o TLS está desabilitado.
**Conecte-se ao Amazon DocumentDB com o mongosh**.
**Importante**
Há uma limitação conhecida com os drivers de NodeJS de versão anterior a 6.13.1, que atualmente não têm mais suporte para autenticação de identidades do IAM para o Amazon DocumentDB. Os drivers e ferramentas do Node.js que usam o driver Node.js (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou mais recente do driver de Node.js.
Nos exemplos a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
mongosh --host cluster-end-point:27017 --username sample-user --password password --retryWrites false
```
**Conecte-se ao Amazon DocumentDB com a versão anterior do shell do mongo**
Se você usa o IAM, deve usar uma versão anterior do shell mongo. Insira uma das opções de comando a seguir:
```
mongo --host cluster-end-point:27017 --username sample-user --password password
```
Se você estiver usando uma versão igual ou superior a 4.2, use o código a seguir para conectar. Não há suporte para gravações com novas tentativas no Amazon DocumentDB. Se você estiver usando o shell mongo (não mongosh), não inclua o comando `retryWrites=false` em nenhuma string de código. Por padrão, as gravações que podem ser repetidas estão desabilitadas. A inclusão de `retryWrites=false` pode causar falha nos comandos de leitura normais.
```
mongo --host cluster-end-point:27017 --username sample-user --password password
```
**Teste a conexão**
1. Insira um único documento.
```
db.myTestCollection.insertOne({'hello':'Amazon DocumentDB'})
```
1. Encontre o documento inserido anteriormente.
```
db.myTestCollection.find({'hello':'Amazon DocumentDB'})
```
------
#### [ R ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB com R usando o mongolite ([https://jeroen.github.io/mongolite/](https://jeroen.github.io/mongolite/)) quando o TLS está desabilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
#Include the mongolite library.
library(mongolite)
#Create a MongoDB client, open a connection to Amazon DocumentDB as a replica
# set and specify the read preference as secondary preferred
client <- mongo(url = "mongodb://sample-user:password@sample-cluster.node.us-east-1.docdb.amazonaws.com:27017/sample-database?readPreference=secondaryPreferred&replicaSet=rs0")
##Insert a single document
str <- c('{"hello" : "Amazon DocumentDB"}')
client$insert(str)
##Find the document that was previously written
client$find()
```
------
#### [ Ruby ]
O código a seguir demonstra como se conectar ao Amazon DocumentDB com o Ruby quando o TLS está desabilitado.
No exemplo a seguir, substitua cada *espaço reservado ao usuário* pelas informações do seu cluster.
```
require 'mongo'
require 'neatjson'
require 'json'
client_host = 'mongodb://sample-cluster.node.us-east-1.docdb.amazonaws.com:27017'
client_options = {
database: 'test',
replica_set: 'rs0',
read: {:secondary_preferred => 1},
user: 'sample-user',
password: 'password',
retry_writes: false
}
begin
##Create a MongoDB client, open a connection to Amazon DocumentDB as a
## replica set and specify the read preference as secondary preferred
client = Mongo::Client.new(client_host, client_options)
##Insert a single document
x = client[:test].insert_one({"hello":"Amazon DocumentDB"})
##Find the document that was previously written
result = client[:test].find()
#Print the document
result.each do |document|
puts JSON.neat_generate(document)
end
end
#Close the connection
client.close
```
------
# Conectar-se a um cluster do Amazon DocumentDB de fora de uma Amazon VPC
Os clusters do Amazon DocumentDB (compatível com MongoDB) são implantados dentro de uma Amazon Virtual Private Cloud (Amazon VPC). Eles podem ser acessados diretamente por instâncias do Amazon EC2 ou outros serviços AWS que são implantados no mesmo Amazon VPC. Além disso, o Amazon DocumentDB pode ser acessado por instâncias do EC2 ou outros serviços AWS em VPCs diferentes na mesma Região da AWS ou em outras regiões da por meio do emparelhamento de VPC.
No entanto, suponha que seu caso de uso exija que você (ou sua aplicação) acesse seus recursos do Amazon DocumentDB de fora da VPC do cluster. Nesse caso, é possível usar o tunelamento SSH (também conhecido como *encaminhamento de porta*) para acessar seus recursos do Amazon DocumentDB.
Não faz parte da finalidade deste tópico abordar detalhadamente o tunelamento SSH. Para obter mais informações sobre o tunelamento SSH, consulte o seguinte:
+ [Túnel de SSH](https://www.ssh.com/ssh/tunneling/)
+ [Exemplo de encaminhamento de porta SSH](https://www.ssh.com/ssh/tunneling/example), especificamente a seção [Encaminhamento local](https://www.ssh.com/ssh/tunneling/example#sec-Local-Forwarding)
Para criar um túnel SSH, você precisa de uma instância do Amazon EC2 em execução na mesma Amazon VPC que seu cluster do Amazon DocumentDB. É possível usar uma instância do EC2 existente na mesma VPC que seu cluster ou criar uma instância. Para obter mais informações, consulte o tópico apropriado para seu sistema operacional:
+ [ Como iniciar com instâncias do Linux do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html)
+ [ Como iniciar com instâncias do Windows do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EC2_GetStarted.html)
Normalmente, é possível se conectar a uma instância do EC2 com o seguinte comando.
```
ssh -i "ec2Access.pem" ubuntu@ec2-34-229-221-164.compute-1.amazonaws.com
```
Se esse for o caso, será possível configurar um túnel SSH para o cluster do Amazon DocumentDB `sample-cluster.node.us-east-1.docdb.amazonaws.com` executando o comando a seguir no seu computador local. O sinalizador `-L` é usado para encaminhar uma porta local. Ao usar um túnel SSH, recomendamos que você se conecte ao cluster usando o endpoint do cluster e não tente se conectar no modo de conjunto de réplicas (ou seja, especificando `replicaSet=rs0` em sua string de conexão), pois isso resultará em um erro.
```
ssh -i "ec2Access.pem" -L 27017:sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 ubuntu@ec2-34-229-221-164.compute-1.amazonaws.com -N
```
Depois que o túnel SSH for criado, todos os comandos que você emitir para `localhost:27017` serão encaminhados para o cluster do Amazon DocumentDB `sample-cluster` em execução na Amazon VPC. Se o Transport Layer Security (TLS) estiver ativado no cluster do Amazon DocumentDB, será necessário fazer o download da chave pública para o Amazon DocumentDB em [https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem) . A operação a seguir faz download deste arquivo:
```
wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
```
**nota**
O TLS está habilitado por padrão para todos os novos clusters do Amazon DocumentDB. No entanto, você poderá desabilitá-lo. Para obter mais informações, consulte [Gerenciar configurações de TLS de cluster do Amazon DocumentDB](security.encryption.ssl.md#security.encryption.ssl.managing).
Para conectar-se ao seu cluster do Amazon DocumentDB de fora do Amazon VPC, use o comando a seguir.
```
mongo --sslAllowInvalidHostnames --ssl --sslCAFile global-bundle.pem --username --password
```
# Conectar-se ao Amazon DocumentDB como um conjunto de réplicas
Ao desenvolver no Amazon DocumentDB (compatível com MongoDB), recomendamos que você se conecte ao cluster como um conjunto de réplicas e distribua leituras para instâncias de réplica usando os recursos integrados de preferência de leitura do seu driver. Esta seção detalha o que isso significa e descreve como é possível se conectar ao seu cluster do Amazon DocumentDB como um conjunto de réplicas usando o SDK for Python como exemplo.
O Amazon DocumentDB tem três endpoints que podem ser usados para se conectar ao cluster:
+ Endpoint do cluster
+ Endpoint de leitor
+ Endpoints da instância
Na maioria dos casos, quando você se conecta ao Amazon DocumentDB, recomendamos o uso do endpoint do cluster. Isso é um CNAME que aponta para a instância principal no cluster, conforme mostrado no diagrama a seguir.
Ao usar um túnel SSH, recomendamos que você se conecte ao cluster usando o endpoint do cluster e não tente se conectar no modo de conjunto de réplicas (ou seja, especificando `replicaSet=rs0` em sua string de conexão), pois isso resultará em um erro.
**nota**
Para obter mais informações sobre endpoints do Amazon DocumentDB, consulte [Endpoints do Amazon DocumentDB](how-it-works.md#how-it-works.endpoints).
![\[Diagrama mostrando endpoints do Amazon DocumentDB, incluindo os endpoints do cluster, de leitor e da instância.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/docdb-endpoint-types.png)
Ao usar o endpoint do cluster, é possível se conectar ao cluster no modo de conjunto de réplicas. Depois, você poderá usar os recursos integrados do driver de preferência de leitura. No exemplo a seguir, especificar `/?replicaSet=rs0` significa para o SDK que você deseja se conectar como um conjunto de réplicas. Se você omitir `/?replicaSet=rs0'`, o cliente roteará todas as solicitações para o endpoint do cluster, ou seja, sua instância principal.
```
## Create a MongoDB client, open a connection to Amazon DocumentDB as a
## replica set and specify the read preference as secondary preferred
client = pymongo.MongoClient('mongodb://:@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0')
```
A vantagem de se conectar como um conjunto de réplicas é que isso permite que o SDK descubra a topografia do cluster automaticamente, incluindo quando as instâncias são adicionadas ou removidas do cluster. Você poderá usar seu cluster de forma mais eficiente roteando solicitações de leitura para suas instâncias de réplica.
Ao se conectar como um conjunto de réplicas, é possível especificar a `readPreference` para a conexão. Se você especificar uma preferência de leitura de `secondaryPreferred`, o cliente roteará as consultas de leitura para suas réplicas e as consultas de gravação para sua instância principal (como no diagrama a seguir). Esse é um uso melhor dos recursos do cluster. Para obter mais informações, consulte [Opções de preferência de leitura](how-it-works.md#durability-consistency-isolation).
```
## Create a MongoDB client, open a connection to Amazon DocumentDB as a
## replica set and specify the read preference as secondary preferred
client = pymongo.MongoClient('mongodb://:@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=secondaryPreferred')
```
![\[Diagrama mostrando o readPreference do Amazon DocumentDB: secondaryPreferred.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/docdb-readPreference-secondaryPreferred.png)
As leituras de réplicas do Amazon DocumentDB são eventualmente consistentes. Elas retornam os dados na mesma ordem em que foram gravados na instância principal, e geralmente há menos de 50 ms de tempo de atraso de replicação. É possível monitorar o tempo de atraso da réplica do cluster usando as métricas Amazon CloudWatch `DBInstanceReplicaLag` e `DBClusterReplicaLagMaximum`. Para obter mais informações, consulte [Monitorando o Amazon DocumentDB com CloudWatch](cloud_watch.md).
Diferentemente da arquitetura de banco de dados monolítica tradicional, o Amazon DocumentDB separa o armazenamento e a computação. Considerando essa arquitetura moderna, recomendamos que você faça a escalabilidade de leitura nas instâncias de réplica. As leituras nas instâncias de réplica não bloqueiam as gravações que são replicadas a partir da instância principal. É possível adicionar até 15 instâncias de réplica de leitura em um cluster e expandir para milhões de leituras por segundo.
O principal benefício de se conectar como um conjunto de réplicas e distribuir leituras para réplicas é que ele aumenta os recursos gerais em seu cluster que estão disponíveis para trabalhar em sua aplicação. Como uma melhor prática, recomendamos conectar-se como um conjunto de réplicas. Além disso, recomendamos que isso seja feito mais comumente nos seguintes cenários:
+ Você está usando quase 100% de CPU na principal.
+ A proporção de acertos do cache em buffer é próxima de zero.
+ Você atinge os limites de conexão ou de cursor para uma instância individual.
Expandir o tamanho de uma instância de cluster é uma opção e, em alguns casos, essa pode ser a melhor maneira de escalar o cluster. Mas você também deve considerar como usar melhor as réplicas que já tem em seu cluster. Isso permite aumentar a escala sem o aumento do custo de usar um tipo de instância maior. Recomendamos também que você monitore e alerte sobre esses limites (ou seja `CPUUtilization`, `DatabaseConnections`, e `BufferCacheHitRatio`) usando alarmes do CloudWatch para que saiba quando um recurso está sendo usado intensamente.
Para obter mais informações, consulte os tópicos a seguir.
+ [Práticas recomendadas do Amazon DocumentDB](best_practices.md)
+ [Cotas e limites do Amazon DocumentDB](limits.md)
## Usar conexões de cluster
Considere o cenário de uso de todas as conexões em seu cluster. Por exemplo, uma instância `r5.2xlarge` tem um limite de 4.500 conexões (e 450 cursores abertos). Se você criar um cluster do Amazon DocumentDB de três instâncias e se conectar somente à instância principal usando o endpoint do cluster, os limites do cluster para conexões abertas e cursores serão 4.500 e 450, respectivamente. Talvez você atinja esses limites se estiver criando aplicações que usem muitos operadores que sejam configurados em contêineres. Os contêineres abrem várias conexões de uma só vez e saturam o cluster.
Em vez disso, é possível se conectar ao cluster do Amazon DocumentDB como um conjunto de réplicas e distribuir suas leituras para as instâncias de réplica. Depois, é possível efetivamente triplicar o número de conexões e cursores disponíveis no cluster para 13.500 e 1.350, respectivamente. Adicionar mais instâncias ao cluster só aumentará o número de conexões e cursores para workloads de leitura. Se for necessário aumentar o número de conexões para gravações em seu cluster, recomendamos aumentar o tamanho da instância.
**nota**
O número de conexões para instâncias `large`, `xlarge` e `2xlarge` aumenta com o tamanho da instância, chegando até 4.500. O número máximo de conexões por instância para instâncias `4xlarge` ou maiores é 4.500. Para obter mais informações sobre limites por tipos de instância, consulte [Limites de instâncias](limits.md#limits.instance).
Normalmente, não recomendamos que você se conecte ao cluster usando a preferência de leitura de `secondary`. Isso ocorre porque, se não houver instâncias de réplica no cluster, haverá falha nas leituras. Por exemplo, suponha que você tenha um cluster do Amazon DocumentDB de duas instâncias com uma principal e uma de réplica. Se a instância de réplica tiver um problema, haverá falha nas solicitações de leitura de um grupo de conexão que esteja definido como `secondary`. A vantagem de `secondaryPreferred` é que, se o cliente não conseguir encontrar uma instância de réplica adequada à qual se conectar, ele voltará para a principal para leituras.
## Vários grupos de conexões
Em alguns cenários, as leituras em uma aplicação devem ter consistência de leitura após gravação, que pode ser atendida somente a partir da instância principal no Amazon DocumentDB. Nesses cenários, você pode criar dois grupos de conexão de cliente: um para gravações e outro para leituras que precisam de consistência de leitura após gravação. Para fazer isso, seu código deve ser semelhante ao seguinte:
```
## Create a MongoDB client,
## open a connection to Amazon DocumentDB as a replica set and specify the readPreference as primary
clientPrimary = pymongo.MongoClient('mongodb://:@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=primary')
## Create a MongoDB client,
## open a connection to Amazon DocumentDB as a replica set and specify the readPreference as secondaryPreferred
secondaryPreferred = pymongo.MongoClient('mongodb://:@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=secondaryPreferred')
```
Outra opção é criar um único grupo de conexões e substituir a preferência de leitura para uma determinada coleção.
```
##Specify the collection and set the read preference level for that collection
col = db.review.with_options(read_preference=ReadPreference.SECONDARY_PREFERRED)
```
## Resumo
Para usar melhor os recursos em seu cluster, recomendamos que você se conecte ao cluster usando o modo de conjunto de réplicas. Se for adequado para sua aplicação, você poderá fazer a escalabilidade de leitura de sua aplicação distribuindo suas leituras para as instâncias de réplica.
# Conectar a um cluster Amazon DocumentDB a partir do Studio 3T
O [Studio 3T](https://studio3t.com/) é uma GUI e IDE popular para desenvolvedores e engenheiros de dados que trabalham com o MongoDB. Ele oferece vários recursos poderosos: visualizações em árvore, tabela e JSON de seus dados, fáceis import/export em CSV, JSON, SQL e BSON/MongoDump, opção de consulta flexível, uma drag-and-drop interface visual, um shell mongo integrado com preenchimento automático, um editor de pipeline de agregação e suporte a consultas SQL.
## Pré-requisitos
+ Se você ainda não tem um cluster Amazon DocumentDB usando o Amazon EC2 como bastion/jump host, siga as instruções sobre como [se conectar ao Amazon](https://docs.aws.amazon.com/documentdb/latest/developerguide/connect-ec2.html) EC2.
+ Se você não tem o Studio 3T, [faça o download e instale](https://studio3t.com/download).
## Conectar com o Studio 3T
1. Escolha **Conectar** no canto superior esquerdo da barra de ferramentas.
![\[Interface do Studio 3T mostrando a tela de boas-vindas e a opção Conectar-se destacada no canto superior esquerdo.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-connect.png)
1. Escolha **Nova conexão** no canto superior esquerdo da barra de ferramentas.
![\[Interface do Gerenciador de conexões com a opção Nova conexão destacada no canto superior esquerdo.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-newconn.png)
1. Na guia **Servidor**, no campo **Servidor**, digite as informações do endpoint do cluster.
![\[Guia Servidor na interface Nova conexão com o campo de entrada Servidor destacado.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-endpoint.png)
**nota**
Não consegue encontrar seu endpoint de cluster? Basta seguir as etapas [aqui](https://docs.aws.amazon.com/documentdb/latest/developerguide/db-instance-endpoint-find.html).
1. Escolha a guia **Autenticação** e selecione **Legado** no menu suspenso do **Modo de Autenticação**.
![\[Guia Autenticação na interface Nova conexão com o modo de autenticação legado selecionado e informações de nome de usuário, senha e banco de dados de autenticação fornecidas.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-auth.png)
1. Insira seu nome de usuário e credenciais nos campos **Nome de usuário** e **Senha**.
1. Escolha a guia **SSL** e marque a caixa **Usar protocolo SSL para conectar**.
![\[Guia SSL na interface Nova conexão com a opção Usar protocolo SSL para se conectar selecionada.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-ssl.png)
1. Escolha **Usar arquivo CA raiz próprio**. Em seguida, adicione o certificado Amazon DocumentDB (você pode pular essa etapa se o SSL estiver desabilitado no seu cluster do DocumentDB). Marque a caixa para permitir **nomes de host inválidos**.
![\[Guia SSL na interface Nova conexão com o arquivo CA raiz inserido e permitir nomes de host inválidos selecionado.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-ssl.png)
**nota**
Não tem o certificado? É possível baixar com o seguinte comando:
`wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem `
1. Se estiver se conectando a partir de uma máquina externa à Amazon VPC, você precisará criar um túnel SSH. Você fará isso na guia **SSH**.
1. Marque a caixa **Usar túnel SSH** e insira o endereço SSH no campo **Endereço SSH.** Esta é a sua instância Public DNS (IPV4). É possível obter essa URL no [Console Amazon EC2 Management](https://console.aws.amazon.com/ec2).
1. Insira seu nome de usuário. Este é o nome de usuário da instância do Amazon EC2
1. Para o **Modo de Autenticação SSH**, selecione **Chave privada**. No campo **Chave privada**, escolha o ícone do localizador de arquivos para localizar e selecionar a chave privada da sua instância do Amazon EC2. Esse é o arquivo .pem (par de chave) que você salvou ao criar sua instância no console do Amazon EC2.
1. Se você estiver na máquina Linux/macOS cliente, talvez seja necessário alterar as permissões da sua chave privada usando o seguinte comando:
`chmod 400 /fullPathToYourPemFile/.pem`
![\[Guia SSH na interface Nova conexão com as credenciais de túnel de SSH inseridas.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-ssh.png)
**nota**
Essa instância do Amazon EC2 deve estar na mesma Amazon VPC e grupo de segurança que o cluster do DocumentDB. É possível obter o endereço SSH, o nome de usuário e a chave privada no [Console de Gerenciamento do Amazon EC2](https://console.aws.amazon.com/ec2).
1. Agora teste sua configuração escolhendo o botão **Testar conexão**.
![\[Interface Nova conexão com o botão Testar conexão destacado no canto inferior esquerdo.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-testbutton.png)
1. Uma janela de diagnóstico deve carregar uma barra verde para indicar que o teste foi bem-sucedido. Agora escolha **OK** para fechar a janela de diagnóstico.
![\[Janela de diagnóstico que aparece após um teste de conexão com êxito.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-testconn.png)
1. Escolha **Salavar** para salvar a conexão para uso futuro.
![\[Interface Nova conexão com o botão Salvar destacado.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-save.png)
1. Agora selecione seu cluster e escolha **Conectar**.
![\[Interface Gerenciador de conexões com o botão Conextar-se destacado.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/studio3t/studio3t-finalconnect.png)
Parabéns\$1 Agora você está conectado ao seu cluster Amazon DocumentDB por meio do Studio 3T.
# Conectar-se ao Amazon DocumentDB usando o DataGrip
O [DataGrip](https://www.jetbrains.com/help/datagrip/documentdb.html) é um poderoso ambiente de desenvolvimento integrado (IDE), que oferece suporte a vários sistemas de banco de dados incluindo o Amazon DocumentDB. Esta seção mostra as etapas para você se conectar ao seu cluster do Amazon DocumentDB usando o DataGrip, de maneira a permitir que você gerencie e consulte facilmente seus dados usando uma interface gráfica.
## Pré-requisitos
+ IDE DataGrip instalado em sua máquina. É possível fazer seu download pelo [JetBrains](https://www.jetbrains.com/datagrip/download/#section=windows).
+ Uma instância do Amazon EC2 em execução na mesma VPC que o seu cluster do Amazon DocumentDB. Você usará essa instância para estabelecer um túnel seguro da sua máquina local para o Amazon DocumentDBCluster. Siga estas instruções para saber como [Conecte usando o Amazon EC2](connect-ec2.md).
+ Alternativa a uma instância do Amazon EC2, uma conexão VPN, ou se já estiver acessando sua infraestrutura AWS usando uma VPN segura. Se você preferir essa opção, siga as instruções para [acessar com segurança o Amazon DocumentDB usando AWS Client VPN](https://aws.amazon.com/blogs/database/securely-access-amazon-documentdb-with-mongodb-compatibility-locally-using-aws-client-vpn/).
## Conectar-se usando o DataGrip
1. Inicie o DataGrip no seu computador e crie um **Novo projeto**.
![\[Tela de boas-vindas do DataGrip com a opção Novo projeto destacada.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/welcome.png)
1. Adicione uma nova fonte de dados usando uma das seguintes maneiras:
1. No menu principal, navegue até **Arquivo — Novo — Fonte de dados** e selecione **DocumentDB**
1. No **Database Explorer**, clique no ícone novo (**\$1**) na barra de ferramentas. Navegue até **Fonte de dados** e selecione **DocumentDB**.
![\[A lista suspensa para + mostra o submenu Fonte de dados. O DocumentDB é selecionado nesse submenu.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/explorer.png)
1. Na página **Fontes de dados** na guia **Geral**, verifique se há um link para **Fazer o download dos arquivos de driver ausentes** na parte inferior da área de configurações da conexão. Clique neste link para fazer o download dos drivers necessários para interagir com um banco de dados. Para obter um link direto para fazer o download, consulte os [drivers JDBC da JetBrains](https://www.jetbrains.com/datagrip/jdbc-drivers/).
![\[Interface de fontes de dados e drivers com o link Baixar arquivos de driver ausentes destacado.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/missing-driver.png)
1. Na guia **Geral**, especifique os detalhes da conexão:
1. No campo **Host**, especifique o endpoint do cluster Amazon DocumentDB.
1. A **porta** já está definida como 27017. Altere-a se seu cluster foi implantado em uma porta diferente.
1. Em **Método de autenticação**, escolha **Nome e senha do usuário**.
1. Insira as informações de nome de usuário e senha.
1. O campo **Banco de dados** é opcional. É possível especificar o banco de dados ao qual deseja conectar-se.
1. O campo **URL** é preenchido automaticamente à medida que você adiciona os detalhes acima.
![\[Campos de host, porta, autenticação, banco de dados e URL na guia Geral na interface Fontes de dados e drivers.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/connection.png)
1. Na guia **SSH/SSL**, habilite **Usar túnel SSH** e então, clique no ícone para abrir a caixa de diálogo **Configuração SSH**. Insira as seguintes informações:
1. No campo **Host**, insira o nome do host da sua instância do Amazon EC2.
1. Insira o nome de usuário e senha da sua instância do Amazon EC2.
1. Em **Tipo de autenticação**, escolha **Par de chave**.
1. Insira o **arquivo de chave privada**.
**nota**
Se você estiver usando a opção VPN, não há necessidade de configurar o túnel SSH.
![\[A guia SSH/SSL na interface Fontes de dados e drivers com a opção Usar túnel SSH selecionada e o ícone de configuração de SSH destacado. O ícone abre a interface Configurações de SSH exibida.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ssh-tunnel.png)
1. Na guia **SSH/SSL**, habilite **Usar SSL**. No campo **Arquivo CA**, insira o local do arquivo `global-bundle.pem` no seu computador. Em **Modo**, deixe a opção **Exigir** como está.
**nota**
É possível fazer o download do certificado a partir deste local ou com este comando: wget [https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem)
**nota**
Se você estiver tentando conectar-se ao cluster elástico Amazon DocumentDB, não precisará especificar o arquivo CA. Deixe a opção **Usar SSL**, bem como todas as outras opções, marcada em seus valores padrão.
![\[Guia SSH/SSL na interface Fontes de dados e drivers com as configurações de SSL habilitadas.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/use-ssl.png)
1. Na guia **Esquemas**, escolha **Todos os bancos de dados** ou insira o filtro “\$1: \$1” no campo **Padrão do esquema**. Clique no link **Testar conexão** para testar a conexão.
![\[A guia Esquemas na interface Fontes de dados e drivers com a opção Todos os bancos de dados selecionada. Uma mensagem de êxito aparece acima do link Testar conexão.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/schemas.png)
1. Depois que a conexão for testada com sucesso, clique em **OK** para salvar a configuração da fonte de dados.
## Atributos do DataGrip
O DataGrip fornece vários atributos para ajudar a trabalhar com o Amazon DocumentDB de forma eficiente:
+ **Editor SQL** — Escreva e execute consultas semelhantes a SQL em suas coleções do DocumentDB usando o editor SQL no DataGrip.
+ **Visual Query Builder** — Use o Visual Query Builder para criar consultas graficamente sem gravar código SQL.
+ **Gerenciamento de esquemas** — Gerencie facilmente seu esquema de banco de dados, inclusive a criação, alteração e eliminação de coleções.
+ **Visualização de dados** — Visualize e analise seus dados usando várias ferramentas de visualização disponíveis no DataGrip.
+ **Exportar e importar dados** — Transfira dados entre o Amazon DocumentDB e outros bancos de dados usando os atributos de exportação e importação do DataGrip.
Consulte a [documentação oficial do DataGrip](https://www.jetbrains.com/datagrip/features/) para obter mais atributos avançados, dicas sobre como trabalhar com o Amazon DocumentDB e outros sistemas de banco de dados.
# Conecte usando o Amazon EC2
Esta seção descreve como configurar a conectividade entre um cluster do Amazon DocumentDB e o Amazon EC2 e acessar o cluster do Amazon DocumentDB a partir da instância do Amazon EC2.
Há duas opções para configurar a conexão do EC2:
+ [Conectar automaticamente a instância do EC2 a um banco de dados do Amazon DocumentDB](connect-ec2-auto.md) — use o recurso de conexão automática no console do EC2 para configurar automaticamente a conexão entre a instância do EC2 e um banco de dados do Amazon DocumentDB novo ou existente. Essa conexão permite que haja tráfego entre a instância do EC2 e o banco de dados do Amazon DocumentDB. Essa opção geralmente é usada para testar e criar novos grupos de segurança.
+ [Conectar manualmente a instância do EC2 ao banco de dados do Amazon DocumentDB](connect-ec2-manual.md) — configure a conexão entre a instância do EC2 e o banco de dados do Amazon DocumentDB configurando e atribuindo manualmente os grupos de segurança para reproduzir a configuração criada pelo recurso de conexão automática. Essa opção geralmente é usada para alterar configurações mais avançadas e usar grupos de segurança existentes.
## Pré-requisitos
Independentemente da opção e antes de criar o primeiro cluster do Amazon DocumentDB, você deve fazer o seguinte:
**Crie uma conta (AWS) da Amazon Web Services**
Antes de começar a usar o Amazon DocumentDB, você deve ter uma conta da Amazon Web Services (AWS). A AWS conta é gratuita. Você paga apenas pelos serviços e recursos usados.
Se você não tiver um Conta da AWS, conclua as etapas a seguir para criar um.
**Para se inscrever em um Conta da AWS**
1. Abra a [https://portal.aws.amazon.com/billing/inscrição.](https://portal.aws.amazon.com/billing/signup)
1. Siga as instruções online.
Parte do procedimento de inscrição envolve receber uma chamada telefônica ou uma mensagem de texto e inserir um código de verificação pelo teclado do telefone.
Quando você se inscreve em um Conta da AWS, um *Usuário raiz da conta da AWS*é criado. O usuário-raiz tem acesso a todos os Serviços da AWS e recursos na conta. Como prática recomendada de segurança, atribua o acesso administrativo a um usuário e use somente o usuário-raiz para executar [tarefas que exigem acesso de usuário-raiz](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).
**Opcionalmente, configure as permissões necessárias AWS Identity and Access Management (IAM).**
O acesso para gerenciar recursos do Amazon DocumentDB, como clusters, instâncias e grupos de parâmetros de cluster, requer credenciais que AWS possam ser usadas para autenticar suas solicitações. Para obter mais informações, consulte [Gerenciamento de identidade e Gerenciamento de acesso para o Amazon DocumentDB](security-iam.md).
1. Na barra de pesquisa do Console de gerenciamento da AWS, digite IAM e selecione **IAM** no menu suspenso exibido.
1. Depois de chegar ao console do IAM, selecione **Usuários** no painel de navegação.
1. Selecione o nome de usuário.
1. Clique no botão **Adicionar permissões**.
1. Selecione **Attach existing policies directly (Anexar políticas existentes diretamente)**.
1. Digite `AmazonDocDBFullAccess` na barra de pesquisa e selecione-a quando ela aparecer nos resultados da pesquisa.
1. Clique no botão azul na parte inferior que diz **Avançar: Revisão**.
1. Clique no botão azul na parte inferior que diz **Adicionar permissões**.
**Como criar uma Amazon Virtual Private Cloud (Amazon VPC)**
Dependendo de onde Região da AWS você estiver, você pode ou não ter uma VPC padrão já criada. Se você não tiver uma VPC padrão, conclua a etapa 1 de [Conceitos básicos da Amazon VPC no Guia do usuário da Amazon *VPC*](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html). Isso levará menos de cinco minutos.
# Conectar o Amazon EC2 automaticamente
**Topics**
+ [
## Conectar automaticamente uma instância do EC2 a um novo banco de dados do Amazon DocumentDB
](#auto-connect-ec2.process)
+ [
## Conectar automaticamente uma instância do EC2 a um banco de dados do Amazon DocumentDB existente
](#auto-connect-ec2-existing-cluster)
+ [
## Visão geral da conectividade automática com uma instância do EC2
](#auto-connect-ec2.overview)
+ [
## Visualizar recursos computacionais conectados
](#auto-connect-ec2.compute)
Antes de configurar uma conexão entre uma instância do EC2 e um novo banco de dados do Amazon DocumentDB, verifique se você atende aos requisitos descritos em [Visão geral da conectividade automática com uma instância do EC2](#auto-connect-ec2.overview). Se você alterar esses grupos de segurança depois de configurar a conectividade, as alterações poderão afetar a conexão entre a instância do EC2 e o banco de dados do Amazon DocumentDB.
**nota**
Você só pode configurar automaticamente uma conexão entre uma instância do EC2 e um banco de dados do Amazon DocumentDB utilizando o Console de gerenciamento da AWS. Você não pode configurar uma conexão automaticamente com a API AWS CLI ou com a Amazon DocumentDB.
## Conectar automaticamente uma instância do EC2 a um novo banco de dados do Amazon DocumentDB
O processo a seguir pressupõe que você concluiu as etapas do tópico [Pré-requisitos](connect-ec2.md#connect-ec2-prerequisites).
**Topics**
+ [
### Etapa 1: criar uma instância do Amazon EC2
](#auto-connect-ec2.launch-ec2-instance)
+ [
### Etapa 2: criar um cluster do Amazon DocumentDB
](#auto-connect-ec2.launch-cluster)
+ [
### Etapa 3: conectar-se à instância do Amazon EC2
](#manual-connect-ec2.connect)
+ [
### Etapa 4: instalação do shell do MongoDB
](#auto-connect-ec2.install-mongo-shell)
+ [
### Etapa 5: gerenciar o Amazon DocumentDB TLS
](#auto-connect-ec2.tls)
+ [
### Etapa 6: conectar-se ao cluster do Amazon DocumentDB
](#auto-connect-ec2.connect-use)
+ [
### Etapa 7: inserir e consultar dados
](#auto-cloud9-insert-query)
+ [
### Etapa 8: explorar
](#auto-connect-ec2.explore)
### Etapa 1: criar uma instância do Amazon EC2
Nesta etapa, você criará uma instância do Amazon EC2 na mesma região e na Amazon VPC que você usará posteriormente para provisionar seu cluster Amazon DocumentDB.
1. No console do Amazon EC2, selecione **Iniciar instância**.
![\[A seção Iniciar instância no console do Amazon EC2\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/launch-instance.png)
1. Insira um nome ou identificador no campo **Nome**, localizado na seção **Nome e tags**.
1. Na lista suspensa **Imagem de máquina da Amazon (AMI)**, localize a **AMI do Amazon Linux 2** e escolha-a.
![\[A interface de imagens da aplicação e do sistema operacional com a opção Amazon Linux 2 AMI selecionada na seção Início rápido.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/linux2-ami.png)
1. Localize e escolha **t3.micro** na lista suspensa **Tipo de instância**.
1. Na seção **Par de chaves (login)** insira o identificador de um par de chaves existente ou selecione **Criar um novo par de chaves**.
![\[A interface do par de chaves mostrando o campo de nome do par de chaves e a opção Criar novo par de chaves.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/key-pair.png)
É necessário fornecer um par de chaves do Amazon EC2.
+ Se você tiver um par de chaves do Amazon EC2:
1. Selecione um par de chaves, escolha seu par de chaves na lista.
1. Você já deve ter o arquivo de chave privada (arquivo .pem ou .ppk) disponível para fazer login na instância do Amazon EC2.
+ Se você não tiver um par de chaves do Amazon EC2:
1. Ao escolher **Criar novo par de chaves**, a caixa de diálogo **Criar par de chaves** é exibida.
1. Insira um nome no campo **Nome do par de chaves**.
1. Escolha o **Tipo de par de chaves** e o **Formato de arquivo de chave privada**.
1. Escolha **Create key pair (Criar par de chaves)**.
![\[A interface Criar par de chaves com campos para nome, tipo e formato de arquivo do par de chaves. O botão Criar par de chaves está localizado no canto inferior direito.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/create-key-pair.png)
**nota**
Para fins de segurança, é altamente recomendável usar um par de chaves para conectividade de SSH e de internet com sua instância do EC2.
1. **Opcional:** na **seção Configurações de rede**, em **Firewall (grupos de segurança)**, escolha **Criar grupo de segurança**.
![\[A interface de configurações de rede mostrando opções para a criação de um grupo de segurança.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/firewall.png)
Escolha **Criar grupo de segurança** (verifique todas as regras de permissão de tráfego que se apliquem à sua conectividade do EC2).
**nota**
Se você quiser usar um grupo de segurança existente, siga as instruções em [Conectar o Amazon EC2 manualmente](connect-ec2-manual.md).
1. Na seção **Resumo**, revise sua configuração do EC2 e escolha **Iniciar instância**, se tudo estiver correto.
### Etapa 2: criar um cluster do Amazon DocumentDB
Enquanto a instância do Amazon EC2 estiver sendo provisionada, crie seu cluster do Amazon DocumentDB.
1. Navegue até o console do Amazon DocumentDB e escolha **Clusters** no painel de navegação.
1. Escolha **Criar**.
1. Deixe a configuração **Tipo de cluster** com o valor padrão, **Cluster baseado em instância**.
1. Em **Configuração do cluster**, em **Identificador do cluster**, insira um nome exclusivo. Observe que o console mudará todos os nomes de cluster para minúsculas, independentemente de como eles sejam inseridos.
Deixe a **Versão do mecanismo** com o valor padrão de **5.0.0**.
1. Em **Configuração de armazenamento em cluster**, deixe a configuração padrão **Amazon DocumentDB Padrão**.
1. Em **Configuração da instância**:
+ Em **Classe de instância de banco de dados**, escolha **Classes otimizadas para memória (incluir classes r)** (esse é o padrão).
A outra opção de instância são **classes NVMe apoiadas por -.** Para saber mais, consulte [Instâncias baseadas em NVMe](db-instance-nvme.md).
+ Em **Classe de instância**, escolha o tipo de instância que atende às suas necessidades. Para obter uma explicação mais detalhada das classes de instância, consulte [Especificações de classe de instância](db-instance-classes.md#db-instance-class-specs).
+ Em **número de casos**, escolha um número que melhor reflita suas necessidades. Lembre-se de que quanto menor o número, menor o custo e menor o read/write volume que pode ser gerenciado pelo cluster.
![\[Interface de configuração com valores padrão para identificador de cluster, versão do mecanismo e classe de instância, com o número de instâncias definido como uma.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/create-cluster/instance-config.png)
1. Em **Conectividade**, escolha **Conectar-se a um recurso de computação do EC2**. Esta é a instância do EC2 criada na etapa 1.
![\[Interface de conectividade com a opção Conectar-se a um recurso de computação do EC2 selecionada.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2-connect.png)
**nota**
Conectar-se a um recurso computacional do EC2 cria automaticamente um grupo de segurança para a conexão de recursos computacionais do EC2 com seu cluster do Amazon DocumentDB. Quando você tiver concluído a criação do seu cluster e quiser ver o grupo de segurança recém-criado, navegue até a lista de clusters e escolha o identificador respectivo. Na guia **Conectividade e segurança**, acesse **Grupos de segurança** e encontre seu grupo em **Nome do grupo de segurança (ID)**. Ele conterá o nome do seu cluster e terá uma aparência semelhante a esta: `docdb-ec2-docdb-2023-12-11-21-33-41:i-0e4bb09985d2bbc4c (sg-0238e0b0bf0f73877)`.
1. Na seção **Autenticação**, insira um nome de usuário para o usuário principal e escolha **Autogerenciado**. Insira uma senha e confirme-a.
Se, em vez disso, você escolher **Gerenciado em AWS Secrets Manager**, consulte [Gerenciamento de senhas com o Amazon DocumentDB e AWS Secrets Manager](docdb-secrets-manager.md) para obter mais informações.
1. Selecione **Criar cluster**.
### Etapa 3: conectar-se à instância do Amazon EC2
Para instalar o shell do Mongo, você deve primeiro se conectar à sua instância do Amazon EC2. A instalação do shell do Mongo permite que você se conecte e consulte seu cluster do Amazon DocumentDB. Execute as etapas a seguir:
1. No console do Amazon EC2, navegue até suas instâncias e veja se a instância que você acabou de criar está em execução. Se for o caso, selecione a instância clicando no respectivo ID.
![\[Tabela Instâncias listando duas instâncias no console do Amazon EC2.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/ec2-instance-table.png)
1. Selecione **Conectar**.
![\[Resumo da instância para uma instância do Amazon EC2. O botão Conectar está localizado no canto superior direito.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/ec2-instance-summary.png)
1. Você verá quatro guias de opções para seu método de conexão: Amazon EC2 Instance Connect, Session Manager, cliente SSH ou Console de Série do EC2. É necessário escolher um e seguir suas instruções. Ao concluir, escolha **Conectar**.
![\[Interface mostrando as opções de configuração do método de conexão do EC2 Instance Connect.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/connect-options.png)
**nota**
Se seu endereço IP mudou depois que você iniciou essa demonstração ou se você estiver voltando ao seu ambiente posteriormente, atualize a regra de entrada do grupo de segurança `demoEC2` para ativar o tráfego de entrada do seu novo endereço de API.
### Etapa 4: instalação do shell do MongoDB
Agora o shell do MongoDB pode ser instalado. Ele é um utilitário de linha de comando que você usa para se conectar e consultar seu cluster do Amazon DocumentDB. Atualmente, existem duas versões do shell do MongoDB: a versão mais recente, mongosh, e a versão anterior, mongo shell.
**Importante**
Há uma limitação conhecida com os drivers de NodeJS de versão anterior a 6.13.1, que atualmente não têm mais suporte para autenticação de identidades do IAM para o Amazon DocumentDB. Os drivers e ferramentas do Node.js que usam o driver Node.js (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou mais recente do driver de Node.js.
Siga as instruções abaixo para instalar o shell do MongoDB em seu sistema operacional.
------
#### [ On Amazon Linux ]
**Para instalar o shell do MongoDB no Amazon Linux**
Se você *não* estiver usando a autenticação do IAM e quiser usar o shell mais recente do MongoDB (mongosh) para se conectar ao seu cluster do Amazon DocumentDB, siga estas etapas:
1. Crie o arquivo do repositório. Na linha de comando da instância do EC2 que você criou, digite o comando a seguir:
```
echo -e "[mongodb-org-5.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2023/mongodb-org/5.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://pgp.mongodb.com/server-5.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-5.0.repo
```
1. Quando estiver concluído, instale o mongosh com uma das duas opções de comando a seguir no prompt de comando:
**Opção 1**: se você escolheu o Amazon Linux 2023 padrão durante a configuração do Amazon EC2, insira este comando:
```
sudo yum install -y mongodb-mongosh-shared-openssl3
```
**Opção 2**: se você escolheu o Amazon Linux 2 durante a configuração do Amazon EC2, insira este comando:
```
sudo yum install -y mongodb-mongosh
```
Se você estiver usando a autenticação do IAM, você deve usar a versão anterior do shell do MongoDB (5.0) para se conectar ao seu cluster do Amazon DocumentDB. Siga estas etapas:
1. Crie o arquivo do repositório. Na linha de comando da instância do EC2 que você criou, digite o comando a seguir:
```
echo -e "[mongodb-org-5.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2023/mongodb-org/5.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://pgp.mongodb.com/server-5.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-5.0.repo
```
1. Quando estiver concluído, instale o shell do mongodb 5.0 com a opção de comando a seguir no prompt de comando:
```
sudo yum install -y mongodb-org-shell
```
------
#### [ On Ubuntu ]
**Para instalar o mongosh no Ubuntu**
1. Importe a chave pública que será usada pelo sistema de gerenciamento de pacotes.
```
curl -fsSL https://pgp.mongodb.com/server-5.0.asc | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-5.0.gpg
```
1. Crie o arquivo de lista `mongodb-org-5.0.list` para o MongoDB usando o comando apropriado para a versão do Ubuntu.
```
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-5.0.gpg ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
```
1. Importe e atualize o banco de dados de pacotes local usando o comando a seguir:
```
sudo apt-get update
```
1. Instale o mongosh.
```
sudo apt-get install -y mongodb-mongosh
```
Para obter informações sobre como instalar versões anteriores do MongoDB no sistema do Ubuntu, consulte [Instalar o MongoDB Community Edition no Ubuntu](https://docs.mongodb.com/v3.6/tutorial/install-mongodb-on-ubuntu/).
------
#### [ On other operating systems ]
Para instalar o shell do Mongo em outros sistemas operacionais, consulte [Instalar o MongoDB Community Edition](https://www.mongodb.com/docs/manual/administration/install-community/) na documentação do MongoDB.
------
### Etapa 5: gerenciar o Amazon DocumentDB TLS
Faça o download do certificado CA para o Amazon DocumentDB com o seguinte código: `wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem`
**nota**
O Transport Layer Security (TLS) está habilitado por padrão para qualquer novo cluster do Amazon DocumentDB. Para obter mais informações, consulte [Gerenciamento de configurações de TLS do cluster do Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/security.encryption.ssl.html).
### Etapa 6: conectar-se ao cluster do Amazon DocumentDB
1. No console do Amazon DocumentDB, em **Clusters**, localize seu cluster. Escolha o cluster que você criou clicando no **identificador do cluster** desse cluster.
1. Na guia **Conectividade e segurança**, localize **Conectar a este cluster com o shell mongo** na caixa **Conectar**:
![\[Configurações de conexão do cluster com a string de conexão do MongoDB destacada para se conectar a um cluster do Amazon DocumentDB usando o shell do mongo.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/connect-mongosh.png)
Copie a string de conexão fornecida e cole-a no terminal.
Faça as seguintes alterações:
1. Certifique-se de que o nome de usuário correto está na string.
1. Omita `` para que você seja solicitado a fornecer a senha pelo shell mongo ao se conectar.
1. Opcional: se você estiver usando a autenticação do IAM ou a versão anterior do shell do MongoDB, modifique sua string de conexão da forma a seguir:
`mongo --ssl --host mydocdbcluster.cluster-cozt4xr9xv9b.us-east-1.docdb.amazonaws.com:27017 --sslCAFile global-bundle.pem --username SampleUser1 --password`
Substitua `mydocdbcluster.cluster-cozt4xr9xv9b.us-east-1` pelas mesmas informações do seu cluster.
1. Pressione inserir no seu terminal. Agora você deverá fornecer sua senha. Insira a senha.
1. Ao inserir sua senha e ver o prompt `rs0 [direct: primary] >`, você se conecta com êxito ao seu cluster do Amazon DocumentDB.
Está tendo problemas para se conectar? Consulte [Solução de problemas do Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/troubleshooting.html).
### Etapa 7: inserir e consultar dados
Agora que você está conectado ao seu cluster, pode executar algumas consultas para se familiarizar com o uso de um banco de dados de documentos.
1. Para inserir um único documento, digite o seguinte:
```
db.collection.insertOne({"hello":"DocumentDB"})
```
Você obterá o seguinte resultado:
```
{
acknowledged: true,
insertedId: ObjectId('673657216bdf6258466b128c')
}
```
1. É possível ler o documento que escreveu com o comando `findOne()` (porque ele retorna apenas um único documento). Insira o seguinte:
```
db.collection.findOne()
```
Você obterá o seguinte resultado:
```
{ "_id" : ObjectId("5e401fe56056fda7321fbd67"), "hello" : "DocumentDB" }
```
1. Para realizar mais algumas consultas, considere um caso de uso de perfis de jogos. Primeiro, insira algumas entradas em uma coleção intitulada `profiles`. Insira o seguinte:
```
db.profiles.insertMany([{ _id: 1, name: 'Matt', status: 'active', level: 12, score: 202 },
{ _id: 2, name: 'Frank', status: 'inactive', level: 2, score: 9 },
{ _id: 3, name: 'Karen', status: 'active', level: 7, score: 87 },
{ _id: 4, name: 'Katie', status: 'active', level: 3, score: 27 }
])
```
Você obterá o seguinte resultado:
```
{ acknowledged: true, insertedIds: { '0': 1, '1': 2, '2': 3, '3': 4 } }
```
1. Use o `find()` comando para retornar todos os documentos na coleção de perfis. Insira o seguinte:
```
db.profiles.find()
```
Você obterá uma saída que corresponderá aos dados digitados na Etapa 3.
1. Use uma consulta para um único documento por meio de um filtro. Insira o seguinte:
```
db.profiles.find({name: "Katie"})
```
Você obterá o seguinte resultado:
```
{ "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27}
```
1. Agora vamos tentar encontrar um perfil e modificá-lo usando o comando `findAndModify`. Atribuiremos ao usuário Matt mais 10z pontos com o código a seguir:
```
db.profiles.findAndModify({
query: { name: "Matt", status: "active"},
update: { $inc: { score: 10 } }
})
```
Você obtém o seguinte resultado (observe que a pontuação dele ainda não aumentou):
```
{
[{_id : 1, name : 'Matt', status: 'active', level: 12, score: 202}]
```
1. É possível verificar se a pontuação dele mudou com a seguinte consulta:
`db.profiles.find({name: "Matt"})`
Você obterá a seguinte saída:
```
{ "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" : 212 }
```
### Etapa 8: explorar
Parabéns\$1 Você concluiu com êxito o Guia de início rápido do Amazon DocumentDB.
E depois? Saiba como aproveitar totalmente esse poderoso banco de dados com alguns de seus atributos populares:
+ [Gerenciar o Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/managing-documentdb.html)
+ [Escalabilidade](https://docs.aws.amazon.com/documentdb/latest/developerguide/operational_tasks.html)
+ [Fazer backup e restaurar](https://docs.aws.amazon.com/documentdb/latest/developerguide/backup_restore.html)
**nota**
Para economizar, é possível interromper seu cluster Amazon DocumentDB para reduzir custos ou excluir o cluster. Por padrão, após 30 minutos de inatividade, seu AWS Cloud9 ambiente interromperá a instância subjacente do Amazon EC2.
## Conectar automaticamente uma instância do EC2 a um banco de dados do Amazon DocumentDB existente
Para o procedimento a seguir, pressupõe-se que você tenha um cluster do Amazon DocumentDB existente e uma instância do Amazon EC2 existente.
**Acessar seu cluster do Amazon DocumentDB e configure a conexão do Amazon EC2**
1. Acesse o cluster do Amazon DocumentDB.
1. [Faça login no e abra Console de gerenciamento da AWS o console do Amazon DocumentDB em https://console.aws.amazon.com /docdb.](https://console.aws.amazon.com/docdb)
1. No painel de navegação, escolha **Clusters**.
**dica**
Caso não visualize o painel de navegação à esquerda da tela, selecione o ícone do menu (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/docdb-menu-icon.png)) no canto superior esquerdo da página.
1. Especifique o cluster que você quer escolhendo o botão à esquerda do nome do cluster.
1. Configure a conexão do Amazon EC2.
1. Escolha **Ações** e **Configurar conexão do EC2**.
![\[A lista suspensa Ações com a opção Configurar conexão do EC2 selecionada.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/setup-ec2-connect.png)
A caixa de diálogo **Configurar conexão do EC2** é exibida.
1. No campo **Instância do EC2**, escolha a instância do EC2 que você quer conectar ao cluster.
![\[A interface Configurar conexão do EC2 com a lista suspensa de instâncias do EC2 em destaque.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/setup-ec2-connect-dialog.png)
1. Escolha **Continuar**.
A caixa de diálogo **Revisar e confirmar** é exibida.
1. Verifique se as alterações estão corretas. Em seguida, escolha **Configurar conexão**.
![\[A interface Revisar e confirmar mostrando o resumo das alterações. O botão Configurar conexão está localizado no canto inferior direito.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/setup-ec2-review-confirm.png)
Se for bem-sucedida, a seguinte verificação será exibida:
![\[Mensagem de confirmação de uma configuração de conexão com êxito entre o banco de dados do Amazon DocumentDB e a instância do EC2.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/setup-ec2-connect-success.png)
## Visão geral da conectividade automática com uma instância do EC2
Quando você configura uma conexão entre uma instância do EC2 e um banco de dados do Amazon DocumentDB, o Amazon DocumentDB automaticamente configura o grupo de segurança VPC para sua instância do EC2 e para seu banco de dados do Amazon DocumentDB.
Confira a seguir os requisitos para a conexão de uma instância do EC2 com um banco de dados do Amazon DocumentDB:
+ A instância do EC2 deve existir na mesma VPC do banco de dados do Amazon DocumentDB.
Se não houver nenhuma instância do EC2 na mesma VPC, o console fornecerá um link para que você crie uma.
+ O usuário que configura a conectividade deve ter permissões para realizar as seguintes operações do Amazon EC2:
+ `ec2:AuthorizeSecurityGroupEgress`
+ `ec2:AuthorizeSecurityGroupIngress`
+ `ec2:CreateSecurityGroup`
+ `ec2:DescribeInstances`
+ `ec2:DescribeNetworkInterfaces`
+ `ec2:DescribeSecurityGroups`
+ `ec2:ModifyNetworkInterfaceAttribute`
+ `ec2:RevokeSecurityGroupEgress`
Se a instância de banco de dados e a instância do EC2 estiverem em zonas de disponibilidade diferentes, sua conta poderá incorrer em custos entre as zonas.
Quando você configura uma conexão com uma instância do EC2, o Amazon DocumentDB atua de acordo com a configuração atual dos grupos de segurança associados ao banco de dados do Amazon DocumentDB e à instância do EC2, conforme descrito na tabela a seguir:
| Configuração atual do grupo de segurança do Amazon DocumentDB | Configuração atual do grupo de segurança do EC2 | Ação do Amazon DocumentDB |
| --- | --- | --- |
| Há um ou mais grupos de segurança associados ao banco de dados do Amazon DocumentDB com um nome correspondente ao padrão DocumentDB-ec2-n. Um grupo de segurança que corresponde ao padrão não foi modificado. Esse grupo de segurança tem apenas uma regra de saída com o grupo de segurança da VPC da instância do EC2 como origem. | Há um ou mais grupos de segurança associados à instância do EC2 com um nome correspondente ao padrão DocumentDB-ec2-n (em que n é um número). Um grupo de segurança que corresponde ao padrão não foi modificado. Esse grupo de segurança tem apenas uma regra de saída com o grupo de segurança da VPC do banco de dados do Amazon DocumentDB como origem. | O Amazon DocumentDB não realiza nenhuma ação. Uma conexão já foi configurada automaticamente entre a instância do EC2 e o banco de dados do Amazon DocumentDB. Como já existe uma conexão entre a instância do EC2 e o banco de dados do Amazon DocumentDB, os grupos de segurança não são modificados. |
| Qualquer uma das seguintes condições se aplica: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/connect-ec2-auto.html) | Qualquer uma das seguintes condições se aplica: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/connect-ec2-auto.html) | Ação do Amazon DocumentDB: criar novos grupos de segurança |
| Há um ou mais grupos de segurança associados ao banco de dados do Amazon DocumentDB com um nome correspondente ao padrão DocumentDB-ec2-n. Um grupo de segurança que corresponde ao padrão não foi modificado. Esse grupo de segurança tem apenas uma regra de saída com o grupo de segurança da VPC da instância do EC2 como origem. | Há um ou mais grupos de segurança associados à instância do EC2 com um nome que corresponde ao padrão ec2-DocumentDB-n. No entanto, o Amazon DocumentDB não pode usar nenhum desses grupos de segurança para a conexão com o banco de dados do Amazon DocumentDB. O Amazon DocumentDB não pode usar um grupo de segurança que não tenha uma regra de saída com o grupo de segurança da VPC do banco de dados do Amazon DocumentDB como origem. O Amazon DocumentDB também não pode usar um grupo de segurança que tenha sido modificado. | Ação do Amazon DocumentDB: criar novos grupos de segurança |
| Há um ou mais grupos de segurança associados ao banco de dados do Amazon DocumentDB com um nome correspondente ao padrão DocumentDB-ec2-n. Um grupo de segurança que corresponde ao padrão não foi modificado. Esse grupo de segurança tem apenas uma regra de saída com o grupo de segurança da VPC da instância do EC2 como origem. | Existe um grupo de segurança do EC2 válido para a conexão, mas ele não está associado à instância do EC2. Esse grupo de segurança tem um nome que corresponde ao padrão DocumentDB-ec2-n. Não foi modificado. Ele tem apenas uma regra de saída com o grupo de segurança da VPC do banco de dados do Amazon DocumentDB como origem. | Ação do Amazon DocumentDB: associar o grupo de segurança do EC2 |
| Qualquer uma das seguintes condições se aplica: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/connect-ec2-auto.html) | Há um ou mais grupos de segurança associados à instância do EC2 com um nome que corresponde ao padrão DocumentDB-ec2-n. Um grupo de segurança que corresponde ao padrão não foi modificado. Esse grupo de segurança tem apenas uma regra de saída com o grupo de segurança da VPC do banco de dados do Amazon DocumentDB como origem. | Ação do Amazon DocumentDB: criar novos grupos de segurança |
**Ação do Amazon DocumentDB: criar novos grupos de segurança**
O Amazon DocumentDB realiza as seguintes ações:
+ Cria um grupo de segurança que corresponde ao padrão `DocumentDB-ec2-n`. Esse grupo de segurança tem uma regra de entrada com o grupo de segurança da VPC da instância do EC2 como origem. Esse grupo de segurança está associado ao banco de dados do Amazon DocumentDB e permite que a instância do EC2 acesse o banco de dados do Amazon DocumentDB.
+ Cria um grupo de segurança que corresponde ao padrão `ec2-DocumentDB-n`. Esse grupo de segurança tem uma regra de saída com o grupo de segurança da VPC do banco de dados do Amazon DocumentDB como origem. Esse grupo de segurança está associado à instância do EC2 e permite que ela envie tráfego ao banco de dados do Amazon DocumentDB.
**Ação do Amazon DocumentDB: associar o grupo de segurança do EC2**
O Amazon DocumentDB associa o grupo de segurança do EC2 existente e válido à instância do EC2. Esse grupo de segurança permite que a instância do EC2 envie tráfego ao banco de dados do Amazon DocumentDB.
## Visualizar recursos computacionais conectados
Você pode usar o Console de gerenciamento da AWS para visualizar os recursos computacionais conectados a um banco de dados Amazon DocumentDB. Os recursos mostrados incluem conexões de recursos computacionais que foram configuradas automaticamente. É possível configurar a conectividade com recursos computacionais automaticamente das seguintes maneiras:
+ É possível selecionar o recurso computacional ao criar o banco de dados. Para obter mais informações, consulte [Criar um cluster do Amazon DocumentDB](db-cluster-create.md) e Criar um cluster de banco de dados multi-AZ.
+ É possível configurar a conectividade entre um banco de dados existente e um recurso computacional. Para obter mais informações, consulte [Conectar o Amazon EC2 automaticamente](#connect-ec2-auto).
Os recursos computacionais listados não incluem aqueles que foram conectados manualmente ao banco de dados. Por exemplo, você pode permitir que um recurso computacional acesse um banco de dados manualmente adicionando uma regra ao grupo de segurança da VPC associado ao banco de dados.
Para que um recurso computacional seja listado, as seguintes condições devem ser atendidas:
+ O nome do grupo de segurança associado ao recurso computacional correspondente ao padrão `ec2-DocumentDB-n` (em que n é um número).
+ O grupo de segurança associado ao recurso computacional tem uma regra de saída com o intervalo de portas definido como a porta usada pelo banco de dados do Amazon DocumentDB.
+ O grupo de segurança associado ao recurso computacional tem uma regra de saída com a fonte definida como um grupo de segurança associado ao banco de dados do Amazon DocumentDB.
+ O nome do grupo de segurança associado ao banco de dados do Amazon DocumentDB corresponde ao padrão `DocumentDB-ec2-n` (em que n é um número).
+ O grupo de segurança associado ao banco de dados do Amazon DocumentDB dtem uma regra de entrada com o intervalo de portas definido como a porta usada pelo banco de dados do Amazon DocumentDB.
+ O grupo de segurança associado ao banco de dados do Amazon DocumentDB tem uma regra de entrada com a fonte definida como um grupo de segurança associado ao recurso computacional.
**Para visualizar recursos computacionais conectados a um banco de dados do Amazon DocumentDB**
1. [Faça login no e abra Console de gerenciamento da AWS o console do Amazon DocumentDB em https://console.aws.amazon.com /docdb.](https://console.aws.amazon.com/docdb)
1. No painel de navegação, escolha **Bancos de dados** e depois escolha o nome do banco de dados do Amazon DocumentDB.
1. Na guia **Conectividade e segurança**, veja os recursos computacionais na seção **Recursos computacionais conectados**.
# Conectar o Amazon EC2 manualmente
**Topics**
+ [
## Etapa 1: criar uma instância do Amazon EC2
](#manual-connect-ec2.launch-ec2-instance)
+ [
## Etapa 2: criar um grupo de segurança
](#manual-connect-ec2.security-group)
+ [
## Etapa 3: criar um cluster do Amazon DocumentDB
](#manual-connect-ec2.launch-cluster)
+ [
## Etapa 4: conectar a sua instância do Amazon EC2
](#manual-connect-ec2.connect)
+ [
## Etapa 5: instalação do shell do MongoDB
](#manual-connect-ec2.install-mongo-shell)
+ [
## Etapa 6: gerenciar o Amazon DocumentDB TLS
](#manual-connect-ec2.tls)
+ [
## Etapa 7: conectar ao cluster do Amazon DocumentDB
](#manual-connect-ec2.connect-use)
+ [
## Etapa 8: inserir e consultar dados
](#manual-cloud9-insert-query)
+ [
## Etapa 9: explorar
](#manual-connect-ec2.explore)
As etapas a seguir pressupõem que você concluiu as etapas do tópico [Pré-requisitos](connect-ec2.md#connect-ec2-prerequisites).
## Etapa 1: criar uma instância do Amazon EC2
Nesta etapa, você criará uma instância do Amazon EC2 na mesma região e na Amazon VPC que você usará posteriormente para provisionar seu cluster Amazon DocumentDB.
1. No console do Amazon EC2, selecione **Iniciar instância**.
![\[A seção Iniciar instância no console do Amazon EC2\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/launch-instance.png)
1. Insira um nome ou identificador no campo **Nome**, localizado na seção **Nome e tags**.
1. Na lista suspensa **Imagem de máquina da Amazon (AMI)**, localize a **AMI do Amazon Linux 2** e escolha-a.
![\[A interface de imagens da aplicação e do sistema operacional com a opção Amazon Linux 2 AMI selecionada na seção Início rápido.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/linux2-ami.png)
1. Localize e escolha **t3.micro** na lista suspensa **Tipo de instância**.
1. Na seção **Par de chaves (login)** insira o identificador de um par de chaves existente ou selecione **Criar um novo par de chaves**.
![\[A interface do par de chaves mostrando o campo de nome do par de chaves e a opção Criar novo par de chaves.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/key-pair.png)
É necessário fornecer um par de chaves do Amazon EC2.
+ Se você tiver um par de chaves do Amazon EC2:
1. Selecione um par de chaves, escolha seu par de chaves na lista.
1. Você já deve ter o arquivo de chave privada (arquivo .pem ou .ppk) disponível para fazer login na instância do Amazon EC2.
+ Se você não tiver um par de chaves do Amazon EC2:
1. Ao escolher **Criar novo par de chaves**, a caixa de diálogo **Criar par de chaves** é exibida.
1. Insira um nome no campo **Nome do par de chaves**.
1. Escolha o **Tipo de par de chaves** e o **Formato de arquivo de chave privada**.
1. Escolha **Create key pair (Criar par de chaves)**.
![\[A interface Criar par de chaves com campos para nome, tipo e formato de arquivo do par de chaves. O botão Criar par de chaves está localizado no canto inferior direito.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/create-key-pair.png)
**nota**
Para fins de segurança, é altamente recomendável usar um par de chaves para conectividade de SSH e de internet com sua instância do EC2.
1. Na **seção Configurações de rede**, em **Firewall (grupos de segurança)**, escolha **Criar grupo de segurança** ou **Selecionar grupo de segurança existente**.
![\[A interface de configurações de rede mostrando opções para a criação de um grupo de segurança.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/firewall.png)
Se você optar por selecionar um grupo de segurança existente, selecione um na lista suspensa **Grupos de segurança comuns**.
Se você optar por criar um novo grupo de segurança, faça o seguinte:
1. Verifique todas as regras de permissão de tráfego que se aplicam à sua conectividade do EC2.
1. No campo IP, escolha **Meu IP** ou selecione **Personalizado** para escolher em uma lista de blocos CIDR, listas de prefixos ou grupos de segurança. Não recomendamos **Qualquer lugar** como opção, a menos que sua instância do EC2 esteja em uma rede isolada, pois ela permite que qualquer endereço IP acesse sua instância do EC2.
![\[O menu suspenso Meu IP.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/ip-field.png)
1. Na seção **Resumo**, revise sua configuração do EC2 e escolha **Iniciar instância**, se tudo estiver correto.
## Etapa 2: criar um grupo de segurança
Agora você criará um novo grupo de segurança em sua Amazon VPC padrão. O grupo de segurança `demoDocDB` permite que você se conecte ao seu cluster Amazon DocumentDB na porta 27017 (a porta padrão para o Amazon DocumentDB) a partir da sua instância do Amazon EC2.
1. No [console de gerenciamento do Amazon EC2](https://console.aws.amazon.com/ec2), em **Rede e segurança**, escolha **Grupos de segurança**.
![\[Painel de navegação do console do Amazon DocumentDB com a opção Grupos de segurança selecionada no menu suspenso Rede e Segurança.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/nav-security-groups.png)
1. Escolha **Criar grupo de segurança**.
![\[O botão Criar grupo de segurança.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/create-sg-btn-2.png)
1. Na seção **Detalhes básicos**:
1. Em **Nome do grupo de segurança**, insira `demoDocDB`.
1. Em **Descrição**, insira uma descrição.
1. Para **VPC**, aceite o uso da sua VPC padrão.
1. Na seção **Regras de entrada**, escolha **Adicionar regra**.
1. Em **Tipo**, selecione **Regra TCP personalizada** (padrão).
1. Em **Intervalo de portas**, insira `27017`.
1. Em **Source**, escolha **Custom**. No campo ao lado, procure o grupo de segurança que você acabou de criar na etapa 1. Talvez seja necessário atualizar seu navegador para que o console do Amazon EC2 preencha automaticamente o nome da fonte.
![\[Seção de regras de entrada mostrando campos para tipo, protocolo, intervalo de portas, origem e descrição. O botão Adicionar regra está localizado no canto inferior esquerdo.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/inbound-rules.png)
1. Aceite todos os outros padrões e escolha **Criar grupo de segurança**.
![\[O botão Criar grupo de segurança.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/create-sg-btn-2.png)
## Etapa 3: criar um cluster do Amazon DocumentDB
Enquanto a instância do Amazon EC2 estiver sendo provisionada, você criará seu cluster Amazon DocumentDB.
1. Navegue até o console do Amazon DocumentDB e escolha **Clusters** no painel de navegação.
1. Escolha **Criar**.
1. Deixe a configuração **Tipo de cluster** com o valor padrão, **Cluster baseado em instância**.
1. Em **Configuração do cluster**, em **Identificador do cluster**, insira um nome exclusivo. Observe que o console mudará todos os nomes de cluster para minúsculas, independentemente de como eles sejam inseridos.
Deixe a **Versão do mecanismo** com o valor padrão de **5.0.0**.
1. Em **Configuração de armazenamento em cluster**, deixe a configuração padrão **Amazon DocumentDB Padrão**.
1. Em **Configuração da instância**:
+ Em **Classe de instância de banco de dados**, escolha **Classes otimizadas para memória (incluir classes r)** (esse é o padrão).
A outra opção de instância são **classes NVMe apoiadas por -.** Para saber mais, consulte [Instâncias baseadas em NVMe](db-instance-nvme.md).
+ Em **Classe de instância**, escolha o tipo de instância que atende às suas necessidades. Para obter uma explicação mais detalhada das classes de instância, consulte [Especificações de classe de instância](db-instance-classes.md#db-instance-class-specs).
+ Em **número de casos**, escolha um número que melhor reflita suas necessidades. Lembre-se de que quanto menor o número, menor o custo e menor o read/write volume que pode ser gerenciado pelo cluster.
![\[Interface de configuração com valores padrão para identificador de cluster, versão do mecanismo e classe de instância, com o número de instâncias definido como uma.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/create-cluster/instance-config.png)
1. Em **Conectividade**, mantenha a configuração padrão **Não se conectar a um recurso computacional do EC2**.
**nota**
A conexão com um recurso computacional do EC2 cria automaticamente grupos de segurança para a conexão com seu cluster. Como você criou manualmente esses grupos de segurança na etapa anterior, deverá selecionar **Não se conectar a um recurso computacional do EC2** para não criar um segundo conjunto de grupos de segurança.
1. Na seção **Autenticação**, insira um nome de usuário para o usuário principal e escolha **Autogerenciado**. Insira uma senha e confirme-a.
Se, em vez disso, você escolher **Gerenciado em AWS Secrets Manager**, consulte [Gerenciamento de senhas com o Amazon DocumentDB e AWS Secrets Manager](docdb-secrets-manager.md) para obter mais informações.
1. Selecione **Criar cluster**.
## Etapa 4: conectar a sua instância do Amazon EC2
Para instalar o shell do MongoDB, você deve primeiro se conectar à sua instância do Amazon EC2. A instalação do shell do Mongo permite que você se conecte e consulte seu cluster do Amazon DocumentDB. Execute as etapas a seguir:
1. No console do Amazon EC2, navegue até suas instâncias e veja se a instância que você acabou de criar está em execução. Se for o caso, selecione a instância clicando no respectivo ID.
![\[Tabela Instâncias listando duas instâncias no console do Amazon EC2.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/ec2-instance-table.png)
1. Selecione **Conectar**.
![\[Resumo da instância para uma instância do Amazon EC2. O botão Conectar está localizado no canto superior direito.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/ec2-instance-summary.png)
1. Você verá quatro guias de opções para seu método de conexão: Amazon EC2 Instance Connect, Session Manager, cliente SSH ou Console de Série do EC2. É necessário escolher um e seguir suas instruções. Ao concluir, escolha **Conectar**.
![\[Interface mostrando as opções de configuração do método de conexão do EC2 Instance Connect.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/ec2/connect-options.png)
**nota**
Se seu endereço IP mudou depois que você iniciou essa demonstração ou se você estiver voltando ao seu ambiente posteriormente, atualize a regra de entrada do grupo de segurança `demoEC2` para ativar o tráfego de entrada do seu novo endereço de API.
## Etapa 5: instalação do shell do MongoDB
Agora o shell do MongoDB pode ser instalado. Ele é um utilitário de linha de comando que você usa para se conectar e consultar seu cluster do Amazon DocumentDB. Atualmente, existem duas versões do shell do MongoDB: a versão mais recente, mongosh, e a versão anterior, mongo shell.
**Importante**
Há uma limitação conhecida com os drivers de NodeJS de versão anterior a 6.13.1, que atualmente não têm mais suporte para autenticação de identidades do IAM para o Amazon DocumentDB. Os drivers e ferramentas do Node.js que usam o driver Node.js (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou mais recente do driver de Node.js.
Siga as instruções abaixo para instalar o shell do MongoDB em seu sistema operacional.
------
#### [ On Amazon Linux ]
**Para instalar o shell do MongoDB no Amazon Linux**
Se você *não* estiver usando o IAM e quiser usar o shell mais recente do MongoDB (mongosh) para se conectar ao seu cluster do Amazon DocumentDB, siga estas etapas:
1. Crie o arquivo do repositório. Na linha de comando da instância do EC2 que você criou, digite o comando a seguir:
```
echo -e "[mongodb-org-5.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2023/mongodb-org/5.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://pgp.mongodb.com/server-5.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-5.0.repo
```
1. Quando estiver concluído, instale o mongosh com uma das duas opções de comando a seguir no prompt de comando:
**Opção 1**: se você escolheu o Amazon Linux 2023 padrão durante a configuração do Amazon EC2, insira este comando:
```
sudo yum install -y mongodb-mongosh-shared-openssl3
```
**Opção 2**: se você escolheu o Amazon Linux 2 durante a configuração do Amazon EC2, insira este comando:
```
sudo yum install -y mongodb-mongosh
```
Se você estiver usando o IAM, você deve usar a versão anterior do shell do MongoDB (5.0) para se conectar ao seu cluster do Amazon DocumentDB. Siga estas etapas:
1. Crie o arquivo do repositório. Na linha de comando da instância do EC2 que você criou, digite o comando a seguir:
```
echo -e "[mongodb-org-5.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2023/mongodb-org/5.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://pgp.mongodb.com/server-5.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-5.0.repo
```
1. Quando estiver concluído, instale o shell do mongodb 5.0 com a opção de comando a seguir no prompt de comando:
```
sudo yum install -y mongodb-org-shell
```
------
#### [ On Ubuntu ]
**Para instalar o mongosh no Ubuntu**
1. Importe a chave pública que será usada pelo sistema de gerenciamento de pacotes.
```
curl -fsSL https://pgp.mongodb.com/server-5.0.asc | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-5.0.gpg
```
1. Crie o arquivo de lista `mongodb-org-5.0.list` para o MongoDB usando o comando apropriado para a versão do Ubuntu.
```
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-5.0.gpg ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
```
1. Importe e atualize o banco de dados de pacotes local usando o comando a seguir:
```
sudo apt-get update
```
1. Instale o mongosh.
```
sudo apt-get install -y mongodb-mongosh
```
Para obter informações sobre como instalar versões anteriores do MongoDB no sistema do Ubuntu, consulte [Instalar o MongoDB Community Edition no Ubuntu](https://docs.mongodb.com/v3.6/tutorial/install-mongodb-on-ubuntu/).
------
#### [ On other operating systems ]
Para instalar o shell do Mongo em outros sistemas operacionais, consulte [Instalar o MongoDB Community Edition](https://www.mongodb.com/docs/manual/administration/install-community/) na documentação do MongoDB.
------
## Etapa 6: gerenciar o Amazon DocumentDB TLS
Faça o download do certificado CA para o Amazon DocumentDB com o seguinte código: `wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem`
**nota**
O Transport Layer Security (TLS) está habilitado por padrão para qualquer novo cluster do Amazon DocumentDB. Para obter mais informações, consulte [Gerenciamento de configurações de TLS do cluster do Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/security.encryption.ssl.html).
## Etapa 7: conectar ao cluster do Amazon DocumentDB
1. No console do Amazon DocumentDB, em **Clusters**, localize seu cluster. Escolha o cluster que você criou clicando no **identificador do cluster** desse cluster.
![\[Lista de clusters do Amazon DocumentDB mostrando um cluster regional com detalhes da instância primária.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/cluster-connect-choose.png)
1. Na guia **Conectividade e segurança**, localize **Conectar a este cluster com o shell mongo** na caixa **Conectar**:
![\[Configurações de conexão do cluster com a string de conexão do MongoDB destacada para se conectar a um cluster do Amazon DocumentDB usando o shell do mongo.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/connect-mongosh.png)
Copie a string de conexão fornecida e cole-a no terminal.
Faça as seguintes alterações:
1. Certifique-se de que o nome de usuário correto está na string.
1. Omita `` para que você seja solicitado a fornecer a senha pelo shell mongo ao se conectar.
1. Opcional: se você estiver usando a autenticação do IAM ou a versão anterior do shell do MongoDB, modifique sua string de conexão da forma a seguir:
`mongo --ssl --host mydocdbcluster.cluster-cozt4xr9xv9b.us-east-1.docdb.amazonaws.com:27017 --sslCAFile global-bundle.pem --username SampleUser1 --password`
Substitua `mydocdbcluster.cluster-cozt4xr9xv9b.us-east-1` pelas mesmas informações do seu cluster.
1. Pressione inserir no seu terminal. Agora você deverá fornecer sua senha. Insira a senha.
1. Ao inserir sua senha e ver o prompt `rs0 [direct: primary] >`, você se conecta com êxito ao seu cluster do Amazon DocumentDB.
Está tendo problemas para se conectar? Consulte [Solução de problemas do Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/troubleshooting.html).
## Etapa 8: inserir e consultar dados
Agora que você está conectado ao seu cluster, pode executar algumas consultas para se familiarizar com o uso de um banco de dados de documentos.
1. Para inserir um único documento, digite o seguinte:
```
db.collection.insertOne({"hello":"DocumentDB"})
```
Você obterá o seguinte resultado:
```
{
acknowledged: true,
insertedId: ObjectId('673657216bdf6258466b128c')
}
```
1. É possível ler o documento que escreveu com o comando `findOne()` (porque ele retorna apenas um único documento). Insira o seguinte:
```
db.collection.findOne()
```
Você obterá o seguinte resultado:
```
{ "_id" : ObjectId("5e401fe56056fda7321fbd67"), "hello" : "DocumentDB" }
```
1. Para realizar mais algumas consultas, considere um caso de uso de perfis de jogos. Primeiro, insira algumas entradas em uma coleção intitulada `profiles`. Insira o seguinte:
```
db.profiles.insertMany([{ _id: 1, name: 'Matt', status: 'active', level: 12, score: 202 },
{ _id: 2, name: 'Frank', status: 'inactive', level: 2, score: 9 },
{ _id: 3, name: 'Karen', status: 'active', level: 7, score: 87 },
{ _id: 4, name: 'Katie', status: 'active', level: 3, score: 27 }
])
```
Você obterá o seguinte resultado:
```
{ acknowledged: true, insertedIds: { '0': 1, '1': 2, '2': 3, '3': 4 } }
```
1. Use o `find()` comando para retornar todos os documentos na coleção de perfis. Insira o seguinte:
```
db.profiles.find()
```
Você obterá uma saída que corresponderá aos dados digitados na Etapa 3.
1. Use uma consulta para um único documento por meio de um filtro. Insira o seguinte:
```
db.profiles.find({name: "Katie"})
```
Você obterá o seguinte resultado:
```
{ "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27}
```
1. Agora vamos tentar encontrar um perfil e modificá-lo usando o comando `findAndModify`. Atribuiremos ao usuário Matt mais 10z pontos com o código a seguir:
```
db.profiles.findAndModify({
query: { name: "Matt", status: "active"},
update: { $inc: { score: 10 } }
})
```
Você obtém o seguinte resultado (observe que a pontuação dele ainda não aumentou):
```
{
[{_id : 1, name : 'Matt', status: 'active', level: 12, score: 202}]
```
1. É possível verificar se a pontuação dele mudou com a seguinte consulta:
`db.profiles.find({name: "Matt"})`
Você obterá o seguinte resultado:
```
{ "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" : 212 }
```
## Etapa 9: explorar
Parabéns\$1 Você concluiu com êxito o Guia de início rápido do Amazon DocumentDB.
E depois? Saiba como aproveitar totalmente esse poderoso banco de dados com alguns de seus atributos populares:
+ [Gerenciar o Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/managing-documentdb.html)
+ [Escalabilidade](https://docs.aws.amazon.com/documentdb/latest/developerguide/operational_tasks.html)
+ [Fazer backup e restaurar](https://docs.aws.amazon.com/documentdb/latest/developerguide/backup_restore.html)
**nota**
Para economizar, é possível interromper seu cluster Amazon DocumentDB para reduzir custos ou excluir o cluster. Por padrão, após 30 minutos de inatividade, seu AWS Cloud9 ambiente interromperá a instância subjacente do Amazon EC2.
# Conecte-se usando o driver JDBC do Amazon DocumentDB
O driver JDBC para o Amazon DocumentDB fornece uma interface relacional SQL para desenvolvedores e permite a conectividade a partir de ferramentas de BI, como Tableau e. DbVisualizer
Para obter informações mais detalhadas, consulte a documentação do [Amazon DocumentDB JDBC Driver](https://github.com/aws/amazon-documentdb-jdbc-driver/blob/develop/src/markdown/index.md) em. GitHub
**Topics**
+ [
## Introdução
](#connect-jdbc-gettingstarted)
+ [
# Conecte-se ao Amazon DocumentDB a partir do Tableau Desktop
](connect-jdbc-tableau.md)
+ [
# Conecte-se ao Amazon DocumentDB a partir de DbVisualizer
](connect-jdbc-DbVisualizer.md)
+ [
# Geração automática de esquema JDBC
](connect-jdbc-autoschemagen.md)
+ [
# Suporte e limitações do SQL
](connect-jdbc-sqlandlimits.md)
+ [
# Solução de problemas
](connect-jdbc-troubleshooting.md)
## Introdução
**Etapa 1. Criar Amazon DocumentDB Cluster**
Se você não tiver um cluster do Amazon DocumentDB criado, crie um usando as instruções na seção [Conceitos básicos](https://docs.aws.amazon.com/documentdb/latest/developerguide/get-started-guide.html) do Guia do desenvolvedor do Amazon DocumentDB.
O Amazon DocumentDB é um serviço somente de nuvem privada virtual (VPC). Se você estiver se conectando a partir de uma máquina local, fora da VPC do cluster, precisará criar uma conexão SSH com uma instância do Amazon EC2. Nesse caso, inicie seu cluster usando as instruções em [Conecte-se com EC2](https://docs.aws.amazon.com/documentdb/latest/developerguide/connect-ec2.html). Consulte [Usar um túnel SSH para se conectar ao Amazon DocumentDB](https://github.com/aws/amazon-documentdb-jdbc-driver/blob/develop/src/markdown/setup/setup.md#using-an-ssh-tunnel-to-connect-to-amazon-documentdb) para obter mais informações sobre tunelamento SSH e quando você precisar dele.
**Etapa 2. Instalação do JRE ou JDK**
Dependendo da sua aplicação de BI, talvez seja necessário garantir que uma versão 8 ou posterior da instalação do JRE ou JDK de 64 bits esteja instalada no seu computador. É possível fazer o download do Java SE Runtime Environment 8 [aqui](https://www.oracle.com/ca-en/java/technologies/javase-jre8-downloads.html).
**Etapa 3. Faça o download do driver JDBC DocumentDB**
Faça o download do driver JDBC do DocumentDB [aqui](https://github.com/aws/amazon-documentdb-jdbc-driver/releases). O driver é empacotado como um único arquivo JAR (por exemplo, documentdb-jdbc-1.0.0-all.jar).
**Etapa 4: Usando um túnel SSH para se conectar ao Amazon DocumentDB**
Os clusters do Amazon DocumentDB (compatível com MongoDB) são implantados dentro de uma Amazon Virtual Private Cloud (Amazon VPC). Eles podem ser acessados diretamente por instâncias do Amazon EC2 ou outros AWS serviços implantados na mesma Amazon VPC. Além disso, o Amazon DocumentDB pode ser acessado por EC2a instâncias ou outros AWS serviços diferentes na mesma AWS região ou VPCs em outras regiões por meio do emparelhamento de VPC.
É possível usar o tunelamento SSH (também conhecido como encaminhamento de portas) para acessar seus recursos do Amazon DocumentDB, de fora da VPC do cluster. Esse será o caso da maioria dos usuários que não executam suas aplicações em uma VM na mesma VPC do cluster DocumentDB.
Para criar um túnel SSH, você precisa de uma instância do Amazon EC2 em execução na mesma Amazon VPC que seu cluster do Amazon DocumentDB. É possível usar uma instância do EC2 existente na mesma VPC que seu cluster ou criar uma instância. É possível configurar um túnel SSH para o cluster do Amazon DocumentDB `sample-cluster.node.us-east-1.docdb.amazonaws.com` executando o seguinte comando em seu computador local.
```
ssh -i "ec2Access.pem" -L 27017:sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 ubuntu@ec2-34-229-221-164.compute-1.amazonaws.com -N
```
O sinalizador -L é usado para encaminhar uma porta local. Esse é um pré-requisito para se conectar a qualquer ferramenta de BI em execução em um cliente fora da sua VPC. Depois de executar a etapa acima, você pode passar para as próximas etapas da ferramenta de BI de sua escolha.
Para obter mais informações sobre o tunelamento SSH, consulte a documentação sobre [Como usar um túnel SSH para se conectar ao Amazon DocumentDB](https://github.com/aws/amazon-documentdb-jdbc-driver/blob/develop/src/markdown/setup/setup.md#using-an-ssh-tunnel-to-connect-to-amazon-documentdb ).
# Conecte-se ao Amazon DocumentDB a partir do Tableau Desktop
**Topics**
+ [
## Adicionar o driver JDBC do Amazon DocumentDB
](#connect-jdbc-tableau-adddriver)
+ [
## Conectar-se ao Amazon DocumentDB usando o Tableau - Túnel SSH
](#connect-jdbc-tableau-ssh)
## Adicionar o driver JDBC do Amazon DocumentDB
Para se conectar ao Amazon DocumentDB a partir do Tableau Desktop, você deve fazer o download e instalar o driver JDBC do Amazon DocumentDB e o conector DocumentDB Tableau.
1. Faça o download do arquivo JAR do driver JDBC do Amazon DocumentDB no [repositório do driver JDBC do Amazon DocumentDB](https://github.com/aws/amazon-documentdb-jdbc-driver/releases) e copie-o em um desses diretórios de acordo com seu sistema operacional:
+ *Windows* - `C:\Program Files\Tableau\Drivers`
+ *MacOS* - `~/Library/Tableau/Drivers`
1. *Baixe o conector DocumentDB Tableau (um arquivo TACO) do [site do Tableau Exchange](https://exchange.tableau.com/products/821) e copie-o para o diretório Meu Tableau. Repository/Connectors *
+ *Windows* - `C:\Users\[user]\Documents\My Tableau Repository\Connectors`
+ *MacOS* - `/Users/[user]/Documents/My Tableau Repository/Connectors`
Para obter informações, consulte a [Documentação do Tableau](https://tableau.github.io/connector-plugin-sdk/docs/run-taco).
**nota**
[Se você estiver usando certificados CA mais recentes, certifique-se de atualizar seu driver JDBC para a versão v1.4.5 (disponível neste repositório). AWS GitHub ](https://github.com/aws/amazon-documentdb-jdbc-driver/releases/tag/v1.4.5)
## Conectar-se ao Amazon DocumentDB usando o Tableau - Túnel SSH
Para se conectar ao Tableau a partir de uma máquina cliente fora da VPC do seu cluster do DocumentDB, você deve configurar um túnel SSH antes de seguir as etapas abaixo:
1. Inicie a aplicação Tableau Desktop.
1. Navegue até **Connect** > **To A Server** > **More**.
1. Escolha **Amazon DocumentDB da Amazon Web Services** em **Conectores instalados**.
![\[A interface Conectar no Tableau Desktop mostra o submenu Mais... na seção A um servidor. A opção Amazon DocumentDB está destacada no submenu Conectores instalados.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/jdbc/tableau-choose-docdb.png)
**Conectar-se ao Amazon DocumentDB usando o Tableau - Túnel SSH externo**
1. Insira os parâmetros de conexão necessários **Nome do host**, **porta**, **banco de dados**, **nome de usuário** e **senha**. Os parâmetros de conexão no exemplo abaixo são equivalentes à cadeia de conexão JDBC:
`jdbc:documentdb://localhost:27019/test? tls=true&tlsAllowInvalidHostnames=true&scanMethod=random&scanLimit=1000&loginTimeoutSec=0&readPreference=primary&retryReads=true&schemaName=_default` com os parâmetros de nome de usuário e senha passados separadamente em uma coleção de propriedades. Para obter mais informações sobre os parâmetros da cadeia de conexão, consulte a documentação do github do [driver JDBC do Amazon DocumentDB ](https://github.com/aws/amazon-documentdb-jdbc-driver/blob/develop/src/markdown/setup/connection-string.md).
![\[Guia geral na interface do conector Amazon DocumentDB mostrando os campos de nome do host, porta, banco de dados, nome de usuário e senha.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/jdbc/tableau-connect.png)
1. (Opcional) Opções mais avançadas podem ser encontradas na guia **Avançado**.
![\[Guia avançada na interface do conector Amazon DocumentDB mostrando opções adicionais de conexão.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/jdbc/tableau-advanced.png)
1. Escolha **Logon**.
**Conectar-se ao Amazon DocumentDB usando o Tableau - Túnel SSH interno**
**nota**
Se você preferir não configurar o túnel SSH usando um terminal, você pode usar a GUI do Tableau para especificar os detalhes da sua instância EC2, que o driver JDBC usará inerentemente para criar um túnel SSH.
1. Na guia **Avançado**, escolha a **opção Ativar túnel SSH** para revisar outras propriedades.
![\[Guia avançada na interface do conector Amazon DocumentDB com a opção Ativar túnel de SSH selecionada e campos de entrada de SSH adicionais mostrados.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/jdbc/tableau-advanced-Enablessh.png)
1. Insira o **usuário SSH**, o **nome do host SSH** e o **arquivo de chave privada SSH.**
1. (Opcional) É possível desativar a opção **SSH Strict Host Key Check**, que ignora a verificação da chave do host em relação a um arquivo host conhecido.
**nota**
Desativar essa opção é menos seguro, pois pode levar a um [man-in-the-middle](https://en.wikipedia.org/wiki/Man-in-the-middle_attack)ataque.
![\[Guia avançada na interface do conector Amazon DocumentDB com a opção Verificação rigorosa da chave do host de SSH desabilitada.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/jdbc/tableau-advanced-sshhostkeycheck.png)
1. Insira os parâmetros necessários; **Nome do host**, **porta**, **banco de dados**, **nome de usuário** e **senha**.
**nota**
Certifique-se de usar o endpoint do cluster DocumentDB e não o localhost ao usar a opção de túnel SSH interno.
![\[Guia geral na interface do conector Amazon DocumentDB mostrando os campos de nome do host, porta, banco de dados, nome de usuário e senha.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/jdbc/tableau-hostname.png)
1. Selecione **Fazer login**.
# Conecte-se ao Amazon DocumentDB a partir de DbVisualizer
**Topics**
+ [
## Adicionar o driver JDBC do Amazon DocumentDB
](#connect-jdbc-DbVisualizer-adddriver)
+ [
## Conectando-se ao Amazon DocumentDB usando DbVisualizer
](#connect-jdbc-DbVisualizer-connect)
## Adicionar o driver JDBC do Amazon DocumentDB
Para se conectar ao Amazon DocumentDB, DbVisualizer você deve primeiro importar o driver JDBC do Amazon DocumentDB.
1. Inicie o DbVisualizer aplicativo e navegue até o caminho do menu: **Ferramentas > Gerenciador de drivers...**
1. Escolha **\$1** (ou, no menu, selecione **Driver > Criar driver**).
1. Defina **Name (Nome)** como `DocumentDB`.
1. Defina **o formato do URL** como `jdbc:documentdb://[:port]/[?option=value[&option=value[...]]]`
1. Escolha o botão de **pasta** e, em seguida, selecione o arquivo JAR do driver JDBC Amazon DocumentDB e escolha o botão **Abrir.**
1. Verifique se o campo **Classe do motorista** está definido como`software.amazon.documentdb.jdbc.DocumentDbDriver`. As configurações do Driver Manager do **DocumentDB** devem ser como o exemplo a seguir.
![\[Interface de configurações de driver DbVisualizer com as configurações de nome, formato de URL e classe de driver do Amazon DocumentDB inseridas.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/jdbc/DbVisualizer-adddriver.jpg)
1. Feche o diálogo. O driver JDBC do Amazon DocumentDB estará configurado e pronto para uso.
## Conectando-se ao Amazon DocumentDB usando DbVisualizer
Conecte-se ao Amazon DocumentDB usando DbVisualizer
1. Se você estiver se conectando de fora da VPC do cluster Amazon DocumentDB, certifique-se de ter configurado um túnel SSH.
1. Escolha **Banco de dados > Criar conexão de banco de dados** no menu de nível superior.
1. Insira um nome descritivo para o campo **Name**.
1. Defina o **Driver (JDBC)** como o driver DocumentDB que você criou na seção anterior.
1. Defina o **URL do banco** de dados como sua string de conexão JDBC.
Por exemplo: `jdbc:documentdb://localhost:27017/database?tlsAllowInvalidHostnames=true`
1. Defina **Database Userid** como sua ID de usuário do Amazon DocumentDB.
1. Defina a **Senha do Banco de Dados** como a senha correspondente para a ID do usuário.
A caixa de diálogo de Conexão do Banco de Dados deve ter a seguinte aparência:
![\[Interface de conexão de banco de dados com configurações do DocumentDB.\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/images/jdbc/DbVisualizer-connect.jpg)
1. Selecione **Conectar**.
# Geração automática de esquema JDBC
O Amazon DocumentDB é um banco de dados de documentos e, portanto, não tem o conceito de tabelas e esquemas. No entanto, ferramentas de BI, como o Tableau, esperam que o banco de dados conectado apresente um esquema. Especificamente, quando a conexão do driver JDBC precisar obter o esquema da coleção no banco de dados, ela pesquisará todas as coleções no banco de dados. O driver determinará se já existe uma versão em cache do esquema dessa coleção. Se uma versão em cache não existir, ela fará uma amostra da coleção para documentos e criará um esquema com base no comportamento a seguir.
**Topics**
+ [
## Limitações de geração de esquemas
](#connect-jdbc-autoschemagen-limits)
+ [
## Opções do método de verificação
](#connect-jdbc-autoschemagen-scanningoptions)
+ [
## Tipos de dados do Amazon DocumentDB
](#connect-jdbc-autoschemagen-datatypes)
+ [
## Mapeamento de campos de documentos escalares
](#connect-jdbc-autoschemagen-scalarfields)
+ [
## Manipulação de tipos de dados de objetos e matrizes
](#connect-jdbc-autoschemagen-objectandarray)
## Limitações de geração de esquemas
O driver JDBC DocumentDB impõe um limite no tamanho dos identificadores em 128 caracteres. O gerador de esquema pode truncar o comprimento dos identificadores gerados (nomes de tabelas e nomes de colunas) para garantir que eles se encaixem nesse limite.
## Opções do método de verificação
O comportamento da amostragem pode ser modificado usando as opções de cadeia de conexão ou fonte de dados.
+ *scanMethod=*