db.createEncryptedCollection()（mongosh方法）

7.0版本新增。

db.createEncryptedCollection(collName, options)

db.createEncryptedCollection() 在当前数据库上创建由 collName 指定的加密集合。

此方法是 ClientEncryption.createEncryptedCollection() 的包装器，如果 encryptedFields.fields[*].keyId 为 null 或在 options.createCollectionOptions.encryptedFields 定义中省略，则会自动创建数据键。

兼容性

此命令可用于以下环境中托管的部署：

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

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

语法

db.createEncryptedCollection() 通过以下语法实现：

db.createEncryptedCollection(
   collName,
   {
      provider: kmsProviderName,
      createCollectionOptions: encryptedFieldsMap,
      masterKey: customerMasterKeyCredentials
   }
)

命令字段

db.createEncryptedCollection() 采用这些字段：

字段	类型	必要性	说明
`collName`	字符串	必需	要在当前数据库上加密的集合的名称。
`options`	文档	必需	用于配置加密collection的选项。
`options.provider`	字符串	必需	用于存储客户主密钥的 KMS。
`options.createCollectionOptions`	文档	必需	要加密的字段。必须包含 `encryptedFields`文档。有关如何配置 `encryptedFields`文档的详细信息，请参阅步骤。
`options.masterKey`	文档	Optional	指定当KMS提供商为 AWS、 GCP或Azure时访问权限主密钥所需的凭证和密钥标识字段。当KMS提供商为 `local` 时，为可选。

行为

The mongosh client-side field level and queryable encryption methods require a database connection configured for client-side encryption. If the current database connection was not initiated with client-side field level encryption enabled, either:

使用 mongosh 中的 Mongo() 构造函数与所需的客户端字段级加密选项建立连接。Mongo() 方法支持以下用于“客户主密钥”(KMS) 管理的“密钥管理服务”(CMK) 提供商：

Use the mongosh command line options to establish a connection with the required options. The command line options only support the Amazon Web Services KMS provider for CMK management.

包装器行为

The db.createEncryptedCollection() method runs in the context of the current db and uses the same Queryable Encryption-enabled connection as the current mongosh session. Internally, it calls ClientEncryption.createEncryptedCollection() with the current database name, the specified collection name, and the provided options document.

当 options.createCollectionOptions.encryptedFields.fields[*].keyId 为 null 或被省略时，该方法会自动在密钥保管库中创建所需的数据密钥，并在创建的集合的 encryptedFields 定义中填充相应的 keyId 值。

例子

以下示例使用本地托管的 KMS 进行 Queryable Encryption 配置。

创建加密连接

启动 mongosh
运行：
mongosh --nodb
--nodb 表示不连接到数据库。
生成密钥string
生成一个基本 64 96 字节的string ：
const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
创建加密选项对象
要创建客户端字段级加密选项对象，请使用上一步中的 TEST_LOCAL_KEY string ：
var autoEncryptionOpts = { "keyVaultNamespace" : "encryption.__dataKeys", "kmsProviders" : { "local" : { "key" : BinData(0, TEST_LOCAL_KEY) } } }
创建加密客户端对象
要创建加密的客户端对象，请使用Mongo()构造函数。将 mongodb://myMongo.example.net URI 替换为目标集群的连接string URI 。示例：
encryptedClient = Mongo( "mongodb://myMongo.example.net:27017/?replSetName=myMongo", autoEncryptionOpts )

指定要加密的字段

创建encryptedFieldsMap以指定要加密的字段：

const encryptedFieldsMap = {
  encryptedFields: {
    fields: [
      {
        path: "secretField",
        bsonType: "string",
        queries: { queryType: "equality" },
        // keyId omitted; db.createEncryptedCollection() generates it
      },
    ],
  },
};

创建加密集合

在当前数据库上使用助手创建加密的enc.users集合：

const encDb = encryptedClient.getDB("enc");
let result = encDb.createEncryptedCollection(
  "users",
  {
    provider: "local",
    createCollectionOptions: encryptedFieldsMap,
    masterKey: {} // masterKey is optional when provider is local
  }
);

检查结果对象

db.createEncryptedCollection() 返回一个结果对象，其中包括创建的集合名称和该集合的 encryptedFields 定义。

检查 result.collection 的值，确认已在所需位置创建集合，并可选择检查已填充的 encryptedFields：

enc> result.collection
enc.users
enc> result.encryptedFields
{
  fields: [
    {
      path: "secretField",
      bsonType: "string",
      queries: { queryType: "equality", /* ... */ },
      keyId: UUID("...")
    }
  ]
}

了解详情

有关在启用客户端字段级加密的情况下启动 MongoDB 连接的完整文档，请参阅Mongo() 。
有关如何创建和查询加密集合的完整示例，请参阅Queryable Encryption快速入门。