Mongo()

在此页面上

说明

兼容性
AutoEncryptionOpts
api
示例
连接到 MongoDB 集群
连接到已启用客户端加密的集群
连接到已启用自动客户端加密的集群
连接到已启用稳定 API 的集群

说明

Mongo(host, autoEncryptionOpts, api)

JavaScript 构造函数，用于实例化来自 mongosh或 JavaScript 文件的数据库连接。

Mongo() 方法具有以下参数：

Parameter	类型	说明
`host`	string或 `Mongo`实例	可选。主机或连接string 。主机可以是连接string ，也可以采用 `<host>` 或 `<host><:port>` 的形式。连接string可以采用 `Mongo` 实例的形式。如果指定`Mongo` 实例，则`Mongo()` 构造函数将使用指定string mongo实例的连接。如果省略，`Mongo()` 会在以下默认端口 `27017` 上实例化与本地主机接口的连接：
`autoEncryptionOpts`	文档	可选。用于启用客户端字段级加密的配置参数。 `autoEncryptionOpts` 覆盖数据库连接的现有客户端字段级加密配置。如果省略， `Mongo()`会继承当前数据库连接的客户端字段级加密配置。有关用法和语法的详细信息，请参见 `AutoEncryptionOpts`。
`api`	文档	可选。用于启用稳定 API 的配置选项。有关用法和语法的详细信息，请参见 `api`。

提示

另请参阅：

Mongo.getDB() 和 db.getMongo()

兼容性

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

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

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

`AutoEncryptionOpts`

autoEncryptionOpts 文档指定客户端字段级加密的配置选项。如果数据库连接已有客户端字段级加密配置，则指定 autoEncryptionOpts 会覆盖该配置。

例如，以 mongosh 开始的客户端字段级加密命令行选项可为该连接启用客户端加密。使用 Mongo() 创建的新数据库连接将继承加密设置，除非 Mongo() 包含 autoEncryptionOpts。

autoEncryptionOpts 文档的语法如下：

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

autoEncryptionOpts 文档采用以下参数：

Parameter

类型

说明

keyVaultClient

Mongo() 连接对象。

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

指定指向集群的 Mongo() 连接对象：

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

如果 keyVaultClient 被省略，则指定给包含 autoEncryptionOpts 文档的 Mongo() 对象的 host 会用作密钥保管库主机。

keyVaultNamespace

字符串

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

kmsProviders

文档

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

客户端字段级加密支持以下 KMS 提供商：

如果可能，可以考虑将kmsProviders 中提供的凭证定义为环境变量，然后使用 --eval 选项将它们传递给 mongosh。这可以最大限度地降低凭证泄漏到日志中的可能性。有关每种支持的 KMS 的这种方法的示例，请参阅创建数据密钥。

Amazon Web Services KMS

重要提示：要获得Amazon Amazon Web ServicesKMSmongoshMongoDB4.2.2Web Servicesmongoshell KMS支持，请使用或MongoDB 或更高版本的旧版 Shell 。4 。 2 。 0和 4 。 2。 1由于KMS响应对象发生意外更改，旧版 Shell不支持Amazonmongoshell Amazon Web ServicesKMSWeb Services KMS服务。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互斥。

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

bypassAutoEncryption

布尔

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

bypassQueryAnalysis

布尔

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

explicitEncryptionOnly

布尔

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

tlsOptions

对象

（可选） PEM 格式 ( tlsCertificateKeyFile ) 的 TLS客户端端证书和私钥文件、TLS客户端证书和私钥文件密码 ( tlsCertificateKeyFilePassword ) 或 TLS 证书颁发机构文件( tlsCAFile ) 的路径，用于以 PEM 格式连接到KMS 。要学习；了解有关这些选项的更多信息，请参阅TLS 选项。

`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 集群

以下操作从 mongosh 会话中创建一个新的连接对象：

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

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

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

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

创建加密客户端

使用配置了客户端字段级加密选项的 Mongo() 构造函数来创建数据库连接。将 mongodb://myMongo.example.net URI 替换为目标集群的连接字符串 URI。

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 字节字符串
使用 mongosh 加载密钥

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

以下操作从 mongosh 会话中创建新的连接对象。AutoEncryptionOpts 选项指定在 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
)

对 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 并且可以访问指定数据加密密钥的客户端才能解密该字段。

以下操作会在mongosh会话中创建新的连接对象。 mongo.tlsOptions选项支持使用 KMIP 作为 KMS 提供程序的连接：

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 的集群

以下操作会从 mongosh 会话中创建新的连接对象。api 选项启用 Stable API V1，并指定不能运行已弃用的命令或 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 命令。

后退

连接

来年

Mongo.getDB