Mongo()（mongosh方法）

说明

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:

Parameter	类型	说明
`host`	string或 `Mongo`实例	可选。主机或连接string 。 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`	文档	可选。用于启用In-正在使用的加密的配置参数。 `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`	文档	可选。用于启用稳定 API 的配置选项。 See `api` for usage and syntax details.

提示

Mongo.getDB() 和 db.getMongo()

兼容性

此方法可用于以下环境中托管的部署：

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

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

`AutoEncryptionOpts`

autoEncryptionOpts文档指定“正在使用的加密”的配置选项。如果数据库连接具有正在使用的加密配置，则 autoEncryptionOpts 将覆盖该配置。MongoDB提供两种“正在使用的加密”方法：客户端字段级加密和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.

autoEncryptionOpts 文档的语法如下：

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

autoEncryptionOpts 文档采用以下参数：

Parameter

类型

说明

keyVaultClient

Mongo() 连接对象。

（可选）托管密钥保管库集合的 MongoDB cluster。

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

字符串

（必填）密钥保管库集合的完整命名空间。

kmsProviders

文档

(必填）客户端字段级加密使用的密钥管理服务（KMS），用于管理客户主密钥（CMK）。客户端字段级加密使用 CMK 对数据加密密钥进行加密及解密。

客户端字段级加密支持以下 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.

Amazon Web Services KMS

重要提示：要获得 AWS KMS支持，请使用 mongosh 或MongoDB 4.2.2 或更高版本的旧版 mongo Shell 。由于KMS响应对象发生意外更改，4.2.0 和 4.2.1 传统 mongo Shell不支持AWS KMS服务。有关更多信息，请参阅 SERVER-44721。

使用以下字段将 aws 文档指定为 kmsProviders：

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

指定的 accessKeyId 必须对应于具有 KMS 服务的所有 List 和 Read 权限的 IAM 用户。

在某些环境中， Amazon Web Services SDK 可以自动获取凭证。要启用Amazon Web Services KMS而不向Amazon Web Services SDK 提供显式凭证，您可以将 kmsProvider 详细信息传递给 Mongo() 构造函数。

{
  "kmsProviders" : { "aws" : { } }
}

Azure Key Vault

使用以下字段将 azure 文档指定为 kmsProviders：

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

版本 5.0 中的新增功能。

Google Cloud KMS

使用以下字段将 gcp 文档指定为 kmsProviders：

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

版本 5.0 中的新增功能。

本地管理的密钥

使用以下字段将local文档指定为kmsProviders ：

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

指定的 key 必须是 base64 编码的 96 字节字符串，且不包含换行符。

schemaMap

文档

（可选） 使用JSON schema草案 4 标准语法和特定于加密的关键字指定的自动客户端字段级加密规则。此选项与 explicitEncryptionOnly 互斥。如果 schemaMap 和 encryptedFieldsMap 上同时存在一个集合，则初始化时会出现 libmongocrypt 错误。

有关完整的文档，请参阅加密模式。

bypassAutoEncryption

布尔

（可选）指定 true 可绕过自动客户端字段级加密规则并执行显式（手动）逐字段加密。

bypassQueryAnalysis

布尔

（可选）指定 true，在没有 crypt_shared 库的情况下对索引字段使用显式加密。有关详细信息，请参阅用于 Queryable Encryption 的 MongoClient 选项。

explicitEncryptionOnly

布尔

（可选）指定true以表示既不使用自动加密，也不使用自动解密。您可以使用getKeyVault()和getClientEncryption()执行显式加密。此选项与schemaMap互斥。如果省略，则默认为false 。

tlsOptions

对象

(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

文档

（可选）集合命名空间到 encryptedFields 文档的映射。encryptedFields 是描述Queryable Encryption加密字段的BSON文档。如果 schemaMap 和 encryptedFieldsMap 上同时存在一个集合，则初始化时会出现 libmongocrypt 错误。

要学习；了解有关Queryable Encryption中加密字段的更多信息，请参阅加密字段和启用的查询。

`api`

api 参数为 Stable API 指定配置选项。您可以使用以下选项启用或禁用可选行为：

选项	类型	说明
`version`	字符串	指定 API 版本。`"1"` 是目前唯一支持的版本。
`strict`	布尔	如果为 `true`：使用不属于已声明API版本的命令会返回APIStrictError错误。查询规划器会忽略 Stable API 不支持的索引。如果指定`strict` ，则还必须指定`version` 。如果未指定，则默认为 `false`。
`deprecationErrors`	布尔	如果为 `true`，则使用指定 API 版本中已弃用的命令或行为会返回 APIDeprecationError。如果指定 `deprecationErrors`，则还必须指定 `version`。如果未指定，则默认为 `false`。

api 参数采用以下语法：

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

示例

连接到 MongoDB 集群

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

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

针对cluster对象发出操作以与 mymongo.example.net:27017 集群交互：

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

连接到已启用客户端加密的集群

启动 mongosh

启动mongosh客户端。

mongosh --nodb

生成密钥

要为本地托管的密钥配置客户端字段级加密，请生成一个不带换行符的 base64 编码的 96 字节字符串。

const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")

创建客户端字段级加密选项

使用生成的本地密钥字符串创建客户端字段级加密选项：

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

创建加密客户端

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
)

对 cluster 对象发出操作，以便与 mymongo.example.net:27017 集群交互并执行显式加密：

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

有关客户端字段级加密方法的完整列表，请参阅正在使用的加密。

连接到已启用自动客户端加密的集群

为本地管理的密钥配置客户端字段级加密：

生成不带换行符的 base64 编码的 96 字节字符串
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
)

对 cluster 对象发出操作，以便与 mymongo.example.net:27017 集群交互并使用自动加密：

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

指定的自动加密规则使用指定的数据加密密钥和算法对 taxid 和 taxid-short 字段进行加密。只有配置了正确的 KMS 并且可以访问指定数据加密密钥的客户端才能解密该字段。

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

有关客户端字段级加密方法的完整列表，请参阅正在使用的加密。

连接到已启用稳定 API 的集群

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

要与 mymongo.example.net:27017 集群进行交互，请针对 cluster 对象发出操作。有关 Stable API 命令的完整列表，请参阅 Stable API 命令。