mongo() (método mongosh)

Descrição

Mongo(host, autoEncryptionOpts, api)

JavaScript constructor to instantiate a database connection from mongosh or from a JavaScript file.

The Mongo() method has the following parameters:

Parâmetro	Tipo	Descrição
`host`	string ou instância `Mongo`	Opcional. Host ou string de conexão. The host can either be a connection string or in the form of `<host>` or `<host><:port>`. The connection string can be in the form of a `Mongo` instance. If you specify a `Mongo` instance, the `Mongo()` constructor uses the connection string of the specified Mongo instance. If omitted, `Mongo()` instantiates a connection to the localhost interface on the default port `27017`.
`autoEncryptionOpts`	documento	Opcional. Parâmetros de configuração para ativar a criptografia em execução. `autoEncryptionOpts` overrides the existing in-use encryption configuration of the database connection. If omitted, `Mongo()` inherits the in-use encryption configuration of the current database connection. See `AutoEncryptionOpts` for usage and syntax details.
`api`	documento	Opcional. Opções de configuração para ativar a API Stable. See `api` for usage and syntax details.

Dica

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

Compatibilidade

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

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

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.

For example, starting mongosh with client-side field level encryption command-line options enables client-side encryption for that connection. New database connections created using Mongo() inherit the encryption settings unless Mongo() includes 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.

Specify a Mongo() connection object pointing to the cluster:

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

If keyVaultClient is omitted, the host specified to the Mongo() object containing the autoEncryptionOpts document is used as the key vault host.

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:

If possible, consider defining the credentials provided in kmsProviders as environment variables, and then passing them to mongosh using the --eval option. This minimizes the chances of credentials leaking into logs. See Create a Data Key for examples of this approach for each supported KMS.

KMS do Amazon Web Services

IMPORTANTE: para obter suporte ao AWS KMS, use mongosh ou o MongoDB 4.2.2 ou shell mongo legado posterior. Os shell 4.2.0 e 4.2.1 legado mongo não são compatíveis com o serviço AWS KMS devido a uma alteração inesperada no objeto de resposta KMS .Consulte SERVER-44721 para 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.

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

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

Novidade 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

(Optional) The path to the TLS client certificate and private key file in PEM format (tlsCertificateKeyFile), TLS client certificate and private key file password (tlsCertificateKeyFilePassword), or TLS certificate authority file (tlsCAFile) to use to connect to the KMS in PEM format. To learn more about these options, see TLS Options.

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

The following operation creates a new connection object from within a mongosh session:

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:

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

Crie seu cliente criptografado

Use the Mongo() constructor with the client-side field level encryption options configured to create a database connection. Replace the mongodb://myMongo.example.net URI with the connection string URI of the target cluster.

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 criptografia em execução 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 to load the key

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

The following operation creates a new connection object from within a mongosh session. The AutoEncryptionOpts option specifies the required options for enabling automatic client-side encryption on the hr.employees collection:

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.

The following operation creates a new connection object from within a mongosh session. The mongo.tlsOptions option enables a connection using KMIP as the KMS provider:

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 criptografia em execução 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

The following operation creates a new connection object from within a mongosh session. The api option enables Stable API V1 and specifies that you cannot run deprecated command or commands outside of the Stable API.

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