Mongo()

在此页面上

说明

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

说明

Mongo(host, autoEncryptionOpts, api)

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

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

Parameter	类型	说明
`host`	字符串	可选。主机，采用 `<host>` 或 `<host><:port>` 形式。如果省略，`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>
}

autoEncryptionOpts 文档采用以下参数：

Parameter

类型

说明

keyVaultClient

Mongo() 连接对象。

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

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

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

keyVaultClient如果省略host Mongo()，则为包含autoEncryptionOpts 文档的对象指定的将用作密钥保管库托管。

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 用户。

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 模式草稿 4 标准语法和特定加密关键字指定的自动客户端字段级加密规则。

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

bypassAutoEncryption

布尔

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

bypassQueryAnalysis

布尔

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

`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

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

键：

生成不带换行符的 base64 编码的 96 字节字符串
使用 mongosh 加载密钥

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

以下操作会在mongosh会话中创建新的连接对象。 AutoEncryptionOpts选项指定使用本地管理的密钥启用客户端字段级加密所需的选项：

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
)

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

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

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

为本地托管的密钥配置客户端字段级加密需要指定一个不带换行符的基本 64 编码的 96 字节string 。以下操作生成满足所述要求的密钥并将其加载到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'"

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

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

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

连接到已启用稳定 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