文档菜单
文档首页
/
MongoDB 手册
/
参考
/
mongosh 方法
/
连接

Mongo()

本页内容

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

描述

Mongo(host, autoEncryptionOpts, api)

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

Mongo()方法有以下参数

参数
类型
描述
host
字符串或Mongo实例

可选。主机或连接字符串。

主机可以是连接字符串或以下形式之一：<host> 或 <host><:port>。连接字符串可以表示为一个 Mongo 实例。如果您指定了一个 Mongo 实例，则 Mongo() 构造函数使用指定 Mongo 实例的连接字符串。

如果省略，Mongo() 将在默认端口 27017 上实例化到本地主机接口的连接。

autoEncryptionOpts
document

可选。启用自动加密的配置参数客户端字段级加密.

autoEncryptionOpts 覆盖了数据库连接现有的客户端字段级加密配置。如果省略，Mongo() 继承了当前数据库连接的客户端字段级加密配置。

有关用法和语法详情，请参阅 AutoEncryptionOpts。

api
document

可选。启用 稳定 API 的配置选项

有关用法和语法详情，请参阅 api。

提示

另请参阅

Mongo.getDB() 和 db.getMongo()

兼容性

此方法在以下环境中可用

  • MongoDB Atlas：云中 MongoDB 部署的全托管服务

AutoEncryptionOpts

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

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

autoEncryptionOpts 文档具有以下语法

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

autoEncryptionOpts 文档包含以下参数

参数
类型
描述
keyVaultClient
Mongo() 连接对象。

(可选) 存储密钥库集合的 MongoDB 集群。

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

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

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

keyVaultNamespace
字符串
(必需) 密钥库集合的完整 命名空间。
kmsProviders
document

(必需) 客户端字段级加密用于管理客户主密钥 (CMK) 的 密钥管理服务 (KMS)。客户端字段级加密使用 CMK 加密和解密数据加密密钥。

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

如果可能，请考虑将 kmsProviders 中提供的凭证定义为环境变量，然后使用 mongosh 的 --eval 选项将它们传递给 mongosh。这可以最大限度地减少凭证泄露到日志中的可能性。有关每个支持的 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用户。

在某些环境中，AWS SDK可以自动获取凭证。要启用AWS KMS使用而无需向AWS 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 必须是一个不包含换行符的96字节base64编码字符串。

schemaMap
document

(可选) 使用JSON schema Draft 4标准语法和加密特定关键字指定的自动客户端字段级加密规则。此选项与explicitEncryptionOnly互斥。

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

bypassAutoEncryption
布尔型
(可选) 指定true以绕过自动客户端字段级加密规则并执行显式（手动）的每个字段加密。
bypassQueryAnalysis
布尔型
(可选) 指定true以在索引字段上使用显式加密而不使用crypt_shared库。有关详细信息，请参阅可查询加密的MongoClient选项。
explicitEncryptionOnly
布尔型
(可选) 将true指定为不使用自动加密或自动解密。您可以使用getKeyVault()和getClientEncryption()进行显式加密。此选项与schemaMap互斥。如果省略，默认为false。
tlsOptions
对象
(可选) TLS客户端证书和私钥文件的路径，格式为PEM（tlsCertificateKeyFile），TLS客户端证书和私钥文件的密码（tlsCertificateKeyFilePassword），或用于连接到KMS的TLS证书授权文件（tlsCAFile），格式为PEM。有关这些选项的更多信息，请参阅TLS选项。

api

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

选项
类型
描述
version
字符串
指定API版本。目前仅支持"1"版本。
strict
布尔型
如果true

  • 使用不属于声明API版本的命令将返回一个APIStrictError错误。

  • 稳定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

使用客户端加密连接到集群

1

启动 mongosh

启动 mongosh 客户端。

mongosh --nodb
2

生成您的密钥

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

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

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

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

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

创建您的加密客户端

使用配置了客户端字段级加密选项的 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();

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

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

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

  • 生成一个不带换行符的 96 字节 base64 编码字符串

  • 使用 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 启用稳定 API V1 并指定您不能运行已弃用命令或稳定 API 之外的命令。

cluster = Mongo(
  "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
   null,
   { api: { version: "1", strict: true, deprecationErrors: true } }
)

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

返回

connect

下一页

Mongo.getDB