Mongo()
Nesta página
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âmetroTipoDescriçãohost
stringOpcional. O host, na forma de
<host>
ou<host><:port>
.Se omitido, o
Mongo()
instancia uma conexão com a interface do localhost na porta27017
padrão.autoEncryptionOpts
documentoOpcional. 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, oMongo()
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
documentoOpcional. Opções de configuração para ativar a API Stable.
Consulte
api
para obter detalhes de uso e sintaxe.
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 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
Se | ||||||||||||||||||||||||
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
| ||||||||||||||||||||||||
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. |
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 você especificar Se não for especificado, o padrão será |
deprecationErrors | booleano | Se Se não for especificado, o padrão será |
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
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 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.
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.
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.
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.