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á.

# Conectar-se de forma programática ao Amazon DocumentDB
<a name="connect_programmatically"></a>

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 na qual 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, você pode continuar localizando e aplicando o exemplo de código apropriado.

**Topics**
+ [Determinando o valor do seu `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)
+ [Compressão de rede no Amazon DocumentDB](#connect_programmatically-network_compression)

## Determinando o valor do seu `parâmetro tls`
<a name="connect_programmatically-determine_tls_value"></a>

Determinar se o cluster tem o TLS habilitado é um processo de duas etapas que você pode executar usando o Console de gerenciamento da AWS ou. 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 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 à 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 AWS CLI código a seguir determina qual parâmetro está governando seu 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, selecione **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 ]

   Você pode usar o `describe-db-cluster-parameters` AWS CLI comando para visualizar os detalhes dos parâmetros em seu 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 um {{user input placeholder}} 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 começando com clusters do Amazon DocumentDB 5.0 (engine versão 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-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
<a name="connect_programmatically-tls_enabled"></a>

Para visualizar um exemplo de código para se conectar programaticamente a um cluster do TLS-enabled Amazon DocumentDB, 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ários 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 um {{user input placeholder}} 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á habilitado.

**Importante**  
Há uma limitação conhecida com Node.js drivers anteriores à versão 6.13.1, que atualmente não são suportados pela autenticação de identidade IAM para o Amazon DocumentDB. Node.js drivers e ferramentas que usam Node.js driver (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou Node.js superior do driver.

No exemplo a seguir, substitua cada um {{user input placeholder}} 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 um {{user input placeholder}} pelas informações do seu cluster.

```
<?php
//Include Composer's autoloader
require 'vendor/autoload.php';

$TLS_DIR = "/home/ubuntu/global-bundle.pem";

//Create a MongoDB client and open connection to Amazon DocumentDB
$client = new MongoDB\Client("mongodb://{{sample-user}}:{{password}}@{{sample-cluster.node}}.us-east-1.docdb.amazonaws.com:27017/?retryWrites=false", ["tls" => "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 um {{user input placeholder}} 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 TLS-enabled Amazon DocumentDB a partir de um aplicativo Java, seu programa deve usar o arquivo AWS de autoridade de certificação (CA) fornecido 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 alterá-lo {{truststore-password}} para outra coisa. 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 um {{user input placeholder }} por suas próprias informações. Mais notavelmente, onde quer que o diretório de exemplo {{mydir}} "" esteja 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 um {{user input placeholder}} 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<Document> numbersCollection = testDB.getCollection("sample-collection");
   
           Document doc = new Document("name", "pi").append("value", 3.14159);
           numbersCollection.insertOne(doc);
   
           MongoCursor<Document> cursor = numbersCollection.find().iterator();
           try {
               while (cursor.hasNext()) {
                   System.out.println(cursor.next().toJson());
               }
           } finally {
               cursor.close();
           }
   
       }
   }
   ```

------
#### [ C\# / .NET ]

O código a seguir demonstra como conectar-se ao Amazon DocumentDB usando C\# / .NET quando o TLS está habilitado.

No exemplo a seguir, substitua cada um {{user input placeholder}} 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 = "<PATH/global-bundle.p7b_file>";

            // 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<BsonDocument>("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 Node.js drivers anteriores à versão 6.13.1, que atualmente não são suportados pela autenticação de identidade IAM para o Amazon DocumentDB. Node.js drivers e ferramentas que usam Node.js driver (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou Node.js superior do driver.

Nos exemplos a seguir, substitua cada um {{user input placeholder}} 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 um {{user input placeholder}} 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 ="<PATH/global-bundle.pem>"))

#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 um {{user input placeholder}} 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
<a name="connect_programmatically-tls_disabled"></a>

Para ver um exemplo de código para se conectar programaticamente a um cluster do TLS-disabled Amazon DocumentDB, escolha a guia do idioma 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 um {{user input placeholder}} 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á desativado.

**Importante**  
Há uma limitação conhecida com Node.js drivers anteriores à versão 6.13.1, que atualmente não são suportados pela autenticação de identidade IAM para o Amazon DocumentDB. Node.js drivers e ferramentas que usam Node.js driver (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou Node.js superior do driver.

No exemplo a seguir, substitua cada um {{user input placeholder}} 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 um {{user input placeholder}} pelas informações do seu cluster.

```
<?php
//Include Composer's autoloader
require 'vendor/autoload.php';

//Create a MongoDB client and open connection to Amazon DocumentDB
$client = new MongoDB\Client("mongodb://{{sample-user}}:{{password}}@{{sample-cluster.node}}.us-east-1.docdb.amazonaws.com:27017/?retryWrites=false");

//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á desabilitado.

No exemplo a seguir, substitua cada um {{user input placeholder}} 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 um {{user input placeholder}} 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<Document> numbersCollection = testDB.getCollection("sample-collection");

        Document doc = new Document("name", "pi").append("value", 3.14159);
        numbersCollection.insertOne(doc);

        MongoCursor<Document> cursor = numbersCollection.find().iterator();
        try {
            while (cursor.hasNext()) {
                System.out.println(cursor.next().toJson());
            }
        } finally {
            cursor.close();
        }

    }
}
```

------
#### [ C\# / .NET ]

O código a seguir demonstra como se conectar ao Amazon DocumentDB usando C\#/.NET quando o TLS está desabilitado.

No exemplo a seguir, substitua cada um {{user input placeholder}} 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<BsonDocument>("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 Node.js drivers anteriores à versão 6.13.1, que atualmente não são suportados pela autenticação de identidade IAM para o Amazon DocumentDB. Node.js drivers e ferramentas que usam Node.js driver (por exemplo, mongosh) devem ser atualizados para usar a versão 6.13.1 ou Node.js superior do driver.

Nos exemplos a seguir, substitua cada um {{user input placeholder}} 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 um {{user input placeholder}} 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 um {{user input placeholder}} 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
```

------

## Compressão de rede no Amazon DocumentDB
<a name="connect_programmatically-network_compression"></a>

Com a compactação de protocolo de fio, você pode reduzir os dados que seu aplicativo envia pela rede. O Amazon DocumentDB 8.0.1 e versões posteriores oferecem suporte à compactação. Você obtém um rendimento aprimorado para cargas de trabalho que transferem documentos grandes ou grandes conjuntos de resultados. Depois de ativar a compactação, o driver e o servidor trocam mensagens compactadas.

Ao ativar a compactação de rede, você troca recursos de CPU por largura de banda de rede reduzida. Ative a compactação quando sua carga de trabalho estiver vinculada à rede e transferir grandes cargas úteis. Para solicitações e respostas pequenas, talvez você não veja um benefício líquido, pois a sobrecarga de compressão pode exceder a economia.

### Compressores compatíveis
<a name="connect_programmatically-network_compression.supported"></a>

O Amazon DocumentDB oferece suporte ao `snappy` compressor. O Amazon DocumentDB não oferece suporte a outros compressores que os drivers do MongoDB oferecem, como e. `zlib` `zstd`

Se um driver solicitar uma lista de compressores, o Amazon DocumentDB negocia somente os compatíveis. Por exemplo, se um driver oferece `snappy` e`zstd`, o Amazon DocumentDB seleciona `snappy` e ignora. `zstd` Se um driver oferecer somente compressores não suportados, o Amazon DocumentDB não comprime a conexão. Nesse caso, o driver e o servidor trocam mensagens sem compressão.

### Ativar compressão
<a name="connect_programmatically-network_compression.enabling"></a>

Para ativar a compactação, adicione a `compressors` opção à sua cadeia de conexão e defina-a como`snappy`. Na cadeia de conexão a seguir `{{username}}``{{password}}`, substitua e `{{docdb-cluster-endpoint}}` com seus próprios valores:

```
mongodb://{{username}}:{{password}}@{{docdb-cluster-endpoint}}:27017/?tls=true&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false&compressors=snappy
```

Ao usar um driver MongoDB, defina a mesma opção por meio das opções de conexão do driver. A maioria dos drivers exige uma dependência adicional do lado do cliente para realizar uma compactação rápida:
+ O Node.js motorista exige o `snappy` pacote.
+ O driver Python (`PyMongo`) requer o `python-snappy` pacote. No Linux, `python-snappy` também requer a biblioteca snappy do sistema (por exemplo, por `snappy-devel` meio de `dnf` ou`yum`).

Para obter o nome exato da opção e os pacotes necessários, consulte a documentação do motorista.

**nota**  
Se a dependência de compressão do lado do cliente estiver ausente, o driver se conectará com êxito. No entanto, ele troca mensagens sem compressão e não retorna um erro. Para confirmar se a compressão está ativa, verifique o compressor negociado conforme descrito em[Verifique a compressão](#connect_programmatically-network_compression.verifying).

O exemplo de código Python a seguir se conecta ao seu cluster com a compactação rápida ativada e usa um `except` bloco `try` and para lidar com erros de conexão:

```
import pymongo

try:
    client = pymongo.MongoClient(
        'mongodb://{{username}}:{{password}}@{{docdb-cluster-endpoint}}:27017/'
        '?tls=true&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false'
        '&compressors=snappy',
        tlsCAFile='global-bundle.pem')

    db = client['sample-database']
    col = db['sample-collection']
    col.insert_one({'item': 'DocumentDB'})
    print(col.find_one())
except Exception as error:
    print(f'Connection failed: {error}')
```

### Verifique a compressão
<a name="connect_programmatically-network_compression.verifying"></a>

Para confirmar se um driver e o Amazon DocumentDB negociaram a compressão, inspecione o `compression` campo que o comando wire protocol do `hello` MongoDB retorna. Quando o driver e o Amazon DocumentDB negociam a compressão, esse campo lista os compressores acordados.