/ /

Métodos mongosh

Conexiones

Docs Home

Manual de MongoDB

Referencia

Métodos mongosh

Conexiones

Mongo()

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 5.0, consulta el Procedimientos de actualización de MongoDB 6.0 .

Descripción

Mongo(host, ClientSideFieldLevelEncryptionOptions, api)

Constructor de JavaScript para instanciar una conexión de base de datos desde mongosh o desde un archivo JavaScript.

El método Mongo() tiene los siguientes parámetros:

Parameter	Tipo	Descripción
`host`	string	opcional. El host, ya sea en la forma de `<host>` o `<host><:port>`. Si se omite, `Mongo()` establece una conexión con la interfaz localhost en el puerto por defecto `27017`.
`ClientSideFieldLevelEncryptionOptions`	Documento	opcional. Parámetros de configuración para habilitar la encriptación a nivel de campo en el lado del cliente. `ClientSideFieldLevelEncryptionOptions` anula la configuración existente de cifrado a nivel de campo del lado del cliente de la conexión a la base de datos. Si se omite, `Mongo()` hereda la configuración de cifrado a nivel de campo del lado del cliente de la conexión actual a la base de datos. Consulta `ClientSideFieldLevelEncryptionOptions` para obtener detalles de uso y sintaxis.
`api`	Documento	opcional. Opciones de configuración para activar la Stable API. Consulta `api` para obtener detalles de uso y sintaxis.

Tip

Mongo.getDB() y db.getMongo()

Compatibilidad

Este método está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

`ClientSideFieldLevelEncryptionOptions`

El documento ClientSideFieldLevelEncryptionOptions especifica las opciones de configuración para cifrado a nivel de campo del lado del cliente. Si la conexión a la base de datos tiene una configuración existente de cifrado a nivel de campo del lado del cliente, especificar ClientSideFieldLevelEncryptionOptions anula esa configuración.

Por ejemplo, comenzar mongosh con cifrado a nivel de campo del lado del cliente opciones de línea de comandos habilita el cifrado del lado del cliente para esa conexión. Las nuevas conexiones de base de datos creadas con Mongo() heredan la configuración de cifrado a menos que Mongo() incluya ClientSideFieldLevelEncryptionOptions.

El documento ClientSideFieldLevelEncryptionOptions tiene la siguiente sintaxis:

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

El documento ClientSideFieldLevelEncryptionOptions toma los siguientes parámetros:

Parameter

Tipo

Descripción

keyVaultClient

Mongo() objeto de conexión.

(Opcional) El clúster de MongoDB que aloja la Colección de Bóvedas de Llaves.

Especifica un Mongo() objeto de conexión que apunte al clúster:

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

Si se omite keyVaultClient, el host especificado en el objeto Mongo() que contiene el documento ClientSideFieldLevelEncryptionOptions se utiliza como host de almacenamiento seguro de claves.

keyVaultNamespace

string

(Obligatorio) El namespace completo de la colección del almacén de claves.

kmsProviders

Documento

(Obligatorio) El Servicio de Gestión de Claves (KMS) utilizado por el cifrado a nivel de campo del lado del cliente para gestionar una llave maestra de cliente (llave maestra de cliente). El cifrado a nivel de campo del lado del cliente utiliza la llave maestra de cliente para cifrar y descifrar las claves de cifrado de datos.

El cifrado a nivel de campo del lado del cliente es compatible con los siguientes proveedores de KMS:

Si es posible, considera definir las credenciales proporcionadas en kmsProviders como variables de entorno y luego pasarlas a mongosh mediante la opción --eval. Esto minimiza las posibilidades de que las credenciales se filtren en los registros. Consulta Crear una clave de cifrado de datos para ejemplos de este enfoque para cada KMS compatible.

Amazon Web Services KMS

IMPORTANTE: Para soporte de AWS KMS, use mongosh, o el shell MongoDB 4.2.2 o posterior, o el shell "mongo" legacy. El 4.2.0 y 4.2.1 Legacy mongo shell no es compatible con el servicio AWS KMS debido a un cambio inesperado en el objeto de respuesta de KMS. Vea SERVIDOR-44721 para más información.

Especifique el documento aws a kmsProviders con los siguientes campos:

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

El accessKeyId especificado debe corresponder a un usuario IAM con todos los permisos List y Read para el servicio KMS.

Azure Key Vault

Especifique el documento azure a kmsProviders con los siguientes campos:

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

Nuevo en la versión 5.0.

Google Cloud KMS

Especifique el documento gcp a kmsProviders con los siguientes campos:

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

Nuevo en la versión 5.0.

Clave gestionada localmente

Especifique el documento local para kmsProviders con el siguiente campo:

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

El key especificado debe ser una string de 96bytes codificada en base64sin caracteres de nueva línea.

schemaMap

Documento

(opcional) Las reglas automáticas de cifrado a nivel de campo del lado del cliente especificadas mediante la sintaxis estándar del borrador 4 del JSON schema y palabras clave específicas de cifrado.

Para la documentación completa, consulta Reglas de cifrado automático.

bypassAutoEncryption

booleano

(Opcional) Especifique true para eludir las reglas automáticas de cifrado a nivel de campo del lado del cliente y realizar cifrado explícito (manual) por campo.

`api`

El parámetro api especifica las opciones de configuración para la Stable API. Puede habilitar o deshabilitar comportamientos opcionales utilizando las siguientes opciones:

Opción	Tipo	Descripción
`version`	string	Especifica la versión de la API. Actualmente, `"1"` es la única versión soportada.
`strict`	booleano	En caso de que `true`: El uso de un comando que no forma parte de la versión declarada de la API devuelve un error APIStrictError. El planificador de query ignora los índices no compatibles con la Stable API. Si especificas `strict`, también debes especificar `version`. Si no se especifica, el valor por defecto es `false`.
`deprecationErrors`	booleano	Si `true`, usar un comando o comportamiento que está obsoleto en la versión de API especificada devuelve un APIDeprecationError. Si especifica `deprecationErrors`, también debe especificar `version`. Si no se especifica, el valor por defecto es `false`.

El parámetro api tiene la siguiente sintaxis:

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

Ejemplos

Conéctate a un clúster de MongoDB

La siguiente operación crea un nuevo objeto de conexión desde una sesión de mongosh:

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

Emite operaciones contra el objeto cluster para interactuar con el clúster mymongo.example.net:27017:

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

Conectar a un clúster con cifrado del lado del cliente habilitado

Configurar el cifrado a nivel de campo del lado del cliente para una clave administrada localmente requiere especificar un string de 96bytes codificada en base64sin saltos de línea. La siguiente operación genera una clave que cumple con los requisitos establecidos y la carga en 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'"

La siguiente operación crea un nuevo objeto de conexión desde una sesión de mongosh. La opción ClientSideFieldLevelEncryptionOptions especifica las configuraciones necesarias para habilitar el cifrado a nivel de campo del lado del cliente utilizando una clave gestionada localmente:

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultNamespace" : "encryption.dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : BinData(0, TEST_LOCAL_KEY)
    }
  }
}
cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
  ClientSideFieldLevelEncryptionOptions
)

Ejecute operaciones sobre el objeto cluster para interactuar con el clúster mymongo.example.net:27017 y realizar un cifrado explícito:

// 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();

Consulta Métodos de cifrado a nivel de campo del lado del cliente para obtener una lista completa de los métodos de cifrado a nivel de campo del lado del cliente.

Conéctate a un clúster con cifrado del lado del cliente automático habilitado

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

La siguiente operación crea un nuevo objeto de conexión desde una sesión de mongosh. La opción ClientSideFieldLevelEncryptionOptions especifica las opciones necesarias para habilitar el cifrado automático del lado del cliente en la colección hr.employees:

var ClientSideFieldLevelEncryptionOptions = {
  "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",
  ClientSideFieldLevelEncryptionOptions
)

Emite operaciones contra el objeto cluster para interactuar con el clúster mymongo.example.net:27017 y utilizar el cifrado automático:

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

Las reglas de cifrado automático especificadas cifran los campos taxid y taxid-short utilizando la llave de cifrado de datos y el algoritmo especificados. Solo los clientes configurados para el KMS correcto y que tengan acceso a la llave de cifrado de datos especificada pueden descifrar el campo.

Consulta Métodos de cifrado a nivel de campo del lado del cliente para obtener una lista completa de los métodos de cifrado a nivel de campo del lado del cliente.

Conéctate a un clúster con la Stable API habilitada.

La siguiente operación crea un nuevo objeto de conexión desde dentro de una mongosh sesión. La opción api habilita la Stable API v1 y especifica que no se puede ejecutar ningún comando obsoleto ni ningún comando fuera de la Stable API.

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

Para interactuar con el clúster mymongo.example.net:27017, realiza operaciones sobre el objeto cluster. Para ver una lista completa de órdenes de Stable API, consulta Órdenes de Stable API.

Volver

Conectar

Mongo.getDB