/ /

Conexões

Página inicial do Docs

/ /

Métodos de mongosh

Conexões

Página inicial do Docs

mongo() (método mongosh)

Descrição

Mongo(host, autoEncryptionOpts, api)

Construtor JavaScript para instanciar uma conexão de banco de dados a partir do mongosh ou de um arquivo JavaScript.

O método Mongo() tem os seguintes parâmetros:

Parâmetro	Tipo	Descrição
`host`	string ou instância `Mongo`	Opcional. Host ou string de conexão. O host pode ser uma string de conexão ou na forma de `<host>` ou `<host><:port>`. A string de conexão pode estar na forma de uma instância `Mongo` . Se você especificar uma `Mongo` instância, o `Mongo()` construtor usará a string de conexão da instância mongo especificada. Se omitido, instancia uma conexão com a interface localhost na`Mongo()` porta `27017` padrão.
`autoEncryptionOpts`	documento	Opcional. Parâmetros de configuração para ativar a criptografia em execução. `autoEncryptionOpts` substitui a configuração de criptografia em uso existente da conexão do banco de dados . Se omitido, `Mongo()` herda a configuração de criptografia em uso da conexão atual com o banco de dados. `AutoEncryptionOpts` Consulte para obter detalhes de uso e sintaxe .
`api`	documento	Opcional. Opções de configuração para ativar a API Stable. `api` Consulte para obter detalhes de uso e sintaxe .

Dica

Mongo.getDB() e a db.getMongo()

Compatibilidade

Esse método está disponível em implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

`AutoEncryptionOpts`

O documento autoEncryptionOpts especifica opções de configuração para criptografia em execução. Se sua conexão de banco de dados tiver uma configuração de criptografia em uso existente, o autoEncryptionOpts substituirá esta configuração. O MongoDB oferece duas abordagens para a criptografia em execução: Criptografia em nível de campo do lado do cliente e Queryable Encryption.

Por exemplo, iniciar mongosh com opções de linha de comando de criptografia em nível de campo do lado do cliente habilita a criptografia do lado do cliente para essa conexão. Novas conexões de banco de dados criadas usando Mongo() herdam as configurações de criptografia, a menos que Mongo() inclua autoEncryptionOpts.

O documento autoEncryptionOpts tem a seguinte sintaxe:

{
  "keyVaultClient" : <object>,
  "keyVaultNamespace" : "<string>",
  "kmsProviders" : <object>,
  "schemaMap" : <object>,
  "bypassAutoEncryption" : <boolean>,
  "tlsOptions": <object>,
  "encryptedFieldsMap": <object>
}

O documento autoEncryptionOpts recebe os seguintes parâmetros:

Parâmetro

Tipo

Descrição

keyVaultClient

Mongo() objeto de conexão.

(Opcional) O MongoDB cluster hospedando a coleção de cofre de chaves.

Especifique um Mongo() objeto de conexão que aponte para o cluster:

var keyVaultClient = Mongo(<MongoDB URI>);
var autoEncryptionOptions = {
  "keyVaultClient" : keyVaultClient,
  "keyVaultNamespace" : "<database>.<collection>",
  "kmsProviders" : { ... }
}

Se keyVaultClient for omitido, o host especificado para o objeto que contém Mongo() o autoEncryptionOpts documento será usado como o host do cofre de chaves.

keyVaultNamespace

string

(Obrigatório) O namespace completo da coleção de cofre de chaves.

kmsProviders

documento

(Obrigatório) O Serviço de Gerenciamento de Chaves (KMS, na sigla em inglês) usado pela criptografia no nível do campo do lado do cliente para gerenciar uma Chave Mestra do Cliente (CMK, na sigla em inglês). A criptografia criptografia no nível do campo do lado do cliente usa a CMK para criptografar e descriptografar chaves de criptografia de dados.

A criptografia no nível do campo do lado do cliente oferece suporte aos seguintes provedores de KMS:

Se possível, considere a possibilidade de definir as credenciais disponibilizadas no kmsProviders como variáveis de ambiente e, em seguida, passá-las para mongosh utilizando a opção --eval. Isso minimiza as chances de vazamento de credenciais em logs. Consulte Como criar uma chave de dados para ver exemplos dessa abordagem para cada KMS compatível.

KMS do Amazon Web Services

IMPORTANTE: para suporte do Amazon Web Services KMS, use mongosh, MongoDB 4.2.2 ou shell mongo legado posterior. O 4.2.0 e 4.2.1 O shell mongo legado não oferece suporte ao serviço Amazon Web Services KMS devido a uma alteração inesperada no objeto de resposta KMS. Consulte SERVER-44721 para mais informações.

Especifique o documento aws para kmsProviders com os seguintes campos:

"kmsProviders" : {
   "aws" : {
     "accessKeyId" : "AWSAccessKeyId",
     "secretAccessKey" : "AWSSecretAccessKey"
   }
 }

O accessKeyId especificado deve corresponder a um usuário do IAM com todas as permissões List e Read para o serviço KMS.

Em alguns ambientes, o Amazon Web Services SDK pode coletar credenciais automaticamente. Para habilitar o uso Amazon Web Services KMS sem fornecer credenciais explícitas para o Amazon Web Services SDK, você pode passar os detalhes do kmsProvider para o construtor do Mongo().

{
  "kmsProviders" : { "aws" : { } }
}

Azure Key Vault

Especifique o documento azure para kmsProviders com os seguintes campos:

"kmsProviders" : {
  "azure" : {
    "tenantId" : "AzureTenantId",
    "clientId" : "AzureClientId",
    "clientSecret" : "AzureClientSecret"
  }
}

Novidades na versão 5.0.

KMS do Google Cloud

Especifique o documento gcp para kmsProviders com os seguintes campos:

"kmsProviders" : {
  "gcp" : {
    "email" : "GCPEmail",
    "privateKey" : "GCPPrivateKey"
  }
}

Novidades na versão 5.0.

Chave gerenciada localmente

Especifique o documento local para kmsProviders com o seguinte campo:

"kmsProviders" : {
  "local" : {
     "key" : BinData(0, "<96 byte base-64 encoded key>")
  }
}

O key especificado deve ser uma string de 96 bytes codificada em base-64 sem caracteres newline.

schemaMap

documento

(Opcional) As regras automáticas de criptografia no nível do campo do lado do cliente especificadas usando a 4 sintaxe padrão do JSON schema e as palavras-chave específicas da criptografia. Esta opção é mutuamente exclusiva com explicitEncryptionOnly. Se uma collection estiver presente em schemaMap e encryptedFieldsMap, libmongocrypt apresentará erro na inicialização.

Para obter a documentação completa, consulte Esquemas de criptografia.

bypassAutoEncryption

booleano

(Opcional) Especifique true para ignorar as regras automáticas de criptografia em nível de campo do lado do cliente e realizar criptografia explícita (manual) por campo.

bypassQueryAnalysis

booleano

(Opcional) Especifique true para usar criptografia explícita em campos indexados sem a biblioteca crypt_shared. Para obter detalhes, consulte Opções do MongoClient para Queryable Encryption.

explicitEncryptionOnly

booleano

(Opcional) Especifique true para não usar criptografia nem descriptografia automáticas. Você pode utilizar getKeyVault() e getClientEncryption() para executar criptografia explícita. Esta opção é mutuamente exclusiva com schemaMap. Se omitido, o padrão é false.

tlsOptions

objeto

(Opcional) O caminho para o certificado do cliente TLS e o arquivo de chave privada no formato PEM (tlsCertificateKeyFile), do certificado de cliente TLS e da senha do arquivo de chave privada (tlsCertificateKeyFilePassword) ou do arquivo de autoridade de certificação TLS (tlsCAFile) para usar para conecte-se ao KMS no formato PEM. Para saber mais sobre essas opções, consulte Opções de TLS.

encryptedFieldsMap

documento

(Opcional) O mapa de namespaces da coleção para documentos do encryptedFields. encryptedFields é um documento BSON que descreve os campos criptografados da Queryable Encryption . Se uma collection estiver presente em schemaMap e encryptedFieldsMap, libmongocrypt apresentará erro na inicialização.

Para saber mais sobre campos criptografados em Queryable Encryption, consulte Campos criptografados e queries ativadas.

`api`

O parâmetro api especifica opções de configuração para a Stable API. É possível habilitar ou desabilitar o comportamento opcional usando as seguintes opções:

Opção	Tipo	Descrição
`version`	string	Especifica a versão da API. `"1"` é atualmente a única versão suportada.
`strict`	booleano	Se `true`: Usar um comando que não faz parte da versão declarada da API retorna um erro APIStrictError . Os índices que não são suportados pela Stable API são ignorados pelo planejador de query. Se você especificar `strict`, você também deverá especificar `version`. Se não for especificado, o padrão será `false`.
`deprecationErrors`	booleano	Se `true`, o uso de um comando ou comportamento que está obsoleto na versão da API especificada retornará um APIDeprecationError. Se você especificar `deprecationErrors`, também deverá especificar a `version`. Se não for especificado, o padrão será `false`.

O parâmetro api tem a seguinte sintaxe:

{ api: { version: <string>, strict: <boolean>, deprecationErrors: <boolean> } }

Exemplos

Conecte-se a um MongoDB Cluster

A operação a seguir cria um novo objeto de conexão a partir de uma sessão mongosh:

cluster = Mongo("mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster")

Execute operações no objeto cluster para interagir com o cluster mymongo.example.net:27017:

myDB = cluster.getDB("myDB"); //returns the database object
myColl = myDB.getCollection("myColl"); // returns the collection object

Conecte-se a cluster que tenha a criptografia do lado do cliente habilitada

Inicie o mongosh

Inicie o cliente mongosh .

mongosh --nodb

Gere sua chave

Para configurar a criptografia no nível do campo do lado do cliente para uma chave managed localmente, gere uma cadeia de 96 bytes codificada em base64 sem quebras de linha.

const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")

Criar as opções de criptografia em nível de campo do lado do cliente

Crie as opções de criptografia no nível do campo do lado do cliente usando a string de chave local gerada:

 var autoEncryptionOpts = {
   "keyVaultNamespace" : "encryption.__dataKeys",
   "kmsProviders" : {
     "local" : {
       "key" : BinData(0, TEST_LOCAL_KEY)
     }
   }
 }

Crie seu cliente criptografado

Use o construtor Mongo() com as opções de criptografia no nível do campo do lado do cliente configuradas para criar uma conexão com o banco de dados. Substitua o URI do mongodb://myMongo.example.net pelo URI da string de conexão do cluster de destino.

encryptedClient = Mongo(
  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
   autoEncryptionOpts
)

Execute operações no objeto cluster para interagir com o cluster mymongo.example.net:27017 e realizar criptografia explícita:

// returns the database object
myDB = cluster.getDB("myDB");
// returns the collection object
myColl = myDB.getCollection("myColl");
// returns object for managing data encryption keys
keyVault = cluster.getKeyVault();
// returns object for explicit encryption/decryption
clientEncryption = cluster.getClientEncryption();

Consulte Métodos de criptografia em execução para obter uma lista completa de métodos de criptografia de nível de campo no lado do cliente.

Conecte-se a um cluster com a criptografia automática do lado do cliente habilitada

Para configurar a criptografia no nível do campo do lado do cliente para uma chave gerenciada localmente:

gerar uma string de 96 bytes codificada em base 64sem quebras de linha
use mongosh para carregar a chave

export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
mongosh --nodb

A operação a seguir cria um novo objeto de conexão em uma sessão mongosh. A opção AutoEncryptionOpts especifica as opções necessárias para ativar a criptografia automática do lado do cliente na coleção hr.employees:

var autoEncryptionOpts = {
  "keyVaultNamespace" : "encryption.__dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : BinData(0, process.env["TEST_LOCAL_KEY"])
    }
  },
  schemaMap : {
    "hr.employees" : {
      "bsonType": "object",
      "properties" : {
        "taxid" : {
          "encrypt" : {
            "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
            "bsonType" : "string",
            "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
          }
        },
        "taxid-short": {
          "encrypt": {
            "keyId": [UUID("33408ee9-e499-43f9-89fe-5f8533870617")],
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
            "bsonType": "string"
          }
        }
      }
    }
  }
}
cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
  autoEncryptionOpts
)

Execute operações no objeto cluster para interagir com o cluster mymongo.example.net:27017 e utilizar a criptografia automática:

// returns the database object
myDB = cluster.getDB("myDB");
// returns the collection object
myColl = myDB.getCollection("myColl");
myColl.insertOne(
  {
    "name" : "J Doe",
    "taxid" : "123-45-6789",
    "taxid-short" : "6789"
  }
)

As regras de criptografia automática especificadas criptografam os campos taxid e taxid-short usando a chave de criptografia de dados e o algoritmo especificados. Somente os clientes configurados para o KMS correto e acesso à chave de criptografia de dados especificada podem descriptografar o campo.

A operação a seguir cria um novo objeto de conexão a partir de uma sessão mongosh . A opção mongo.tlsOptions habilita uma conexão utilizando KMIP como o provedor de KMS:

var csfleConnection = {
  keyVaultNamespace: "encryption.__keyVault",
  kmsProviders: { kmip: { endpoint: "kmip.example.com:123" } },
  tlsOptions: { kmip: { tlsCertificateKeyFile: "/path/to/client/cert-and-key-bundle.pem" } }
}
cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
  csfleConnection
);

Consulte Métodos de criptografia em execução para obter uma lista completa de métodos de criptografia de nível de campo no lado do cliente.

Conectar-se a um cluster com a Stable API habilitada

A operação a seguir cria um novo objeto de conexão em uma sessão mongosh. A opção api ativa a API estável V1 e especifica que você não pode executar comandos ou comandos obsoletos fora da API estável.

cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
   null,
   { api: { version: "1", strict: true, deprecationErrors: true } }
)

Para interagir com o cluster mymongo.example.net:27017, execute operações no objeto cluster. Caso deseje ver uma lista completa dos comandos da Stable API, consulte a página Comandos da Stable API.

Voltar

Conecte

Mongo.getDB