Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / /

Mongo()

Nesta página

  • Descrição
  • Compatibilidade
  • AutoEncryptionOpts
  • api
  • Exemplos
  • Conecte-se a um MongoDB Cluster
  • Conecte-se a cluster que tenha a criptografia do lado do cliente habilitada
  • Conecte-se a um cluster com a criptografia automática do lado do cliente habilitada
  • Conectar-se a um cluster com a Stable API habilitada
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

Opcional. O host, na forma de <host> ou <host><:port>.

Se omitido, o Mongo() instancia uma conexão com a interface do localhost na porta 27017 padrão.

autoEncryptionOpts
documento

Opcional. Parâmetros de configuração para ativar criptografia de nível de campo do lado do cliente.

autoEncryptionOpts substitui a configuração de criptografia de nível de campo do lado do cliente existente da conexão do banco de dados. Se omitido, o Mongo() herda a configuração de criptografia do nível de campo do lado do cliente da conexão do banco de dados atual.

Consulte AutoEncryptionOpts para obter detalhes de uso e sintaxe.

api
documento

Opcional. Opções de configuração para ativar a API Stable.

Consulte api para obter detalhes de uso e sintaxe.

Dica

Veja também:

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

O documento autoEncryptionOpts especifica as opções de configuração para Criptografia no nível do campo do lado do cliente. Se a conexão do banco de dados tiver uma configuração de criptografia no nível do campo no lado do cliente já existente, a especificação de autoEncryptionOpts substitui essa configuração.

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>
}

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 objeto de conexão Mongo() apontando 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 Mongo() que contém o documento autoEncryptionOpts será utilizado como o host do key vault.

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 Amazon Web Services KMS, use , ou o MongoDB mongosh 4.2.2 ou shell legado mongo shell posterior. O 4.2.0 e 4.2.1 O shell legado mongo shell não oferece suporte ao serviço Amazon Web Services KMS KMS Amazon Web Services KMS devido a uma alteração inesperada no objeto de resposta KMS. Consulte SERVER- para44721 obter 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.

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 sintaxe padrão Draft 4 do JSON schema e palavras-chave específicas de criptografia.

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.

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:

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> } }

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
1

Inicie o cliente mongosh .

mongosh --nodb
2

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")
3

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)
}
}
}
4

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 no nível de campo do lado do cliente para obter uma lista completa dos métodos de criptografia no nível do campo do lado do cliente.

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.

Consulte Métodos de criptografia no nível de campo do lado do cliente para obter uma lista completa dos métodos de criptografia no nível do campo do lado do cliente.

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