Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

Mongo()

Nesta página

Descrição

AutoEncryptionOpts
api
Exemplos
Conecte-se a um Cluster MongoDB
Conecte-se a um cluster com criptografia do lado do cliente ativada
Conecte-se a um cluster com criptografia automática do lado do cliente ativada
Conecte-se a um cluster com a API estável habilitada

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	Opcional. O host, na forma de `<host>` ou `<host><:port>`. Se omitido, `Mongo()` instancia uma conexão com a interface localhost na porta padrão `27017`.
`autoEncryptionOpts`	documento	Opcional. Parâmetros de configuração para ativar a 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 habilitar a API estável. Consulte `api` para obter detalhes de uso e sintaxe.

Dica

Veja também:

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

`AutoEncryptionOpts`

O documento autoEncryptionOpts especifica opções de configuração para criptografia de nível de campo do lado do cliente. Se a conexão do banco de dados tiver uma configuração de criptografia de nível de campo existente no lado do cliente, a especificação autoEncryptionOpts substituirá 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 usa os seguintes parâmetros:

Parâmetro

Tipo

Descrição

keyVaultClient

Mongo() objeto de conexão.

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

Especifique um objeto de conexão Mongo() 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 Mongo() que contém o documento autoEncryptionOpts será usado como o host do cofre de chaves.

keyVaultNamespace

string

(Obrigatório) O namespace completo da key vault collection.

kmsProviders

documento

(Obrigatório) O serviço de gerenciamento de chaves (KMS) usado pela criptografia em nível de campo do lado do cliente para gerenciar uma chave mestra do cliente (CMK). A criptografia no nível do campo no 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 é compatível com os seguintes provedores de KMS:

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

KMS do Amazon Web Services

Importante

Para suporte do AWS KMS, use mongosh ou o MongoDB 4.2.2 ou mongo shell legado posterior. O 4.2.0 e 4.2.1 mongo O shell legado não é compatível com o serviço AWS 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 IAM com todas as permissões List e Read para o serviço KMS.

Cofre de chaves do Azure

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 9664codificada em base sem caracteres de nova linha.

schemaMap

documento

4 Opcional) As regras automáticas de criptografia no nível do campo do lado do cliente especificadas usando a sintaxe padrão do JSON schema e as palavras-chave específicas da 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 execute a criptografia explícita (manual) por campo.

bypassQueryAnalysis

booleano

(Opcional) Especifique true para utilizar criptografia explícita em campos indexados sem a biblioteca do 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 API estável. Você pode 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 retornará um erro ApiStrictError . 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`, você também deverá especificar `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 Cluster MongoDB

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

Emitir 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 um cluster com criptografia do lado do cliente ativada

chave:

gerar uma string 96bytes codificada base64sem 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 a partir de uma sessão mongosh . A opção AutoEncryptionOpts especifica as opções necessárias para habilitar a criptografia em nível de campo no lado do cliente usando uma chave gerenciada localmente:

var autoEncryptionOpts = {
  "keyVaultNamespace" : "encryption.__dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : BinData(0, process.env["TEST_LOCAL_KEY"])
    }
  }
}
cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
  autoEncryptionOpts
)

Emitir operações em relação ao objeto cluster para interagir com o cluster mymongo.example.net:27017 e executar a 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 de nível de campo do lado do cliente para obter uma lista completa de métodos de criptografia de nível de campo do lado do cliente.

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

Configurar a criptografia de nível de campo do lado do cliente para uma chave gerenciada localmente requer a especificação de uma string de bytes codificada 9664sem quebras de linha. A seguinte operação gera uma chave que atende aos requisitos definidos e a carrega em mongosh:

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

A operação a seguir cria um novo objeto de conexão a partir de 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 collection hr.employees :

var autoEncryptionOpts = {
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : BinData(0,"BASE64-ENCODED-96-BYTE-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
)

Emitir operações em relação ao objeto cluster para interagir com o cluster mymongo.example.net:27017 e utilizar 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 clientes configurados para o KMS correto e acesso à chave de encriptação de dados especificada podem descriptografar o campo.

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

Conecte-se a um cluster com a API estável habilitada

A operação a seguir cria um novo objeto de conexão a partir de 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 , emita operações no objeto cluster . Para obter uma lista completa de comandos de API estáveis, consulte Comandos de API estáveis.

← connect()

Mongo.getDB() →

Mongo().css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Descrição

Dica

Veja também:

AutoEncryptionOpts

Importante

api

Exemplos

Conecte-se a um Cluster MongoDB

Conecte-se a um cluster com criptografia do lado do cliente ativada

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

Conecte-se a um cluster com a API estável habilitada

Mongo()

`AutoEncryptionOpts`

`api`