Mongo()

在此页面上

说明

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

说明

Mongo(host, ClientSideFieldLevelEncryptionOptions, api)

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

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

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

提示

另请参阅：

Mongo.getDB() 和 db.getMongo()

`ClientSideFieldLevelEncryptionOptions`

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

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

ClientSideFieldLevelEncryptionOptions 文档的语法如下：

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

ClientSideFieldLevelEncryptionOptions 文档采用以下参数：

Parameter

类型

说明

keyVaultClient

Mongo() 连接对象。

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

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

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

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

keyVaultNamespace

字符串

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

kmsProviders

文档

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

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

如果可能，请考虑将kmsProviders 中提供的档案定义为环境变量，然后使用选项将其传递给mongosh --eval。这样可以最大限度地减少凭证泄漏到日志中的可能性。有关适用于每个受支持的 KMS 的此方法的示例，请参阅创建数据加密密钥。

Amazon Web Services KMS

重要提示： 要获得mongosh AWS KMS支持，请使用或MongoDB4.2.2 或更高版本的旧版mongo Shell 。。4 2。0 和4 2。1 mongo。由于KMS响应对象发生意外更改，传统 Shell不支持AWS 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 可绕过自动客户端字段级加密规则并执行显式（手动）逐字段加密。

`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

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

为本地托管的密钥配置客户端字段级加密需要指定一个不带换行符的基本 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会话中创建新的连接对象。 ClientSideFieldLevelEncryptionOptions选项指定使用本地管理的密钥启用客户端字段级加密所需的选项：

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

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

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

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

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 会话中创建新的连接对象。ClientSideFieldLevelEncryptionOptions 选项指定在 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
)

对 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